Generate video from text

Primary agent path

Use the Universal Skill with the MCP tool beatra.videos.generate. The tool is billable and returns an asynchronous task.

Finalize the scene, motion, duration, and fidelity choices.
If a model, audio support, constraint, or price matters, call beatra.models.list with capability: "text_to_video". Otherwise use model: "auto" or omit model.
Upload local audio with beatra.assets.upload and use its artifact ID.
Create one opaque client_request_id and submit the final arguments once.
Poll the returned task with beatra.tasks.get until it is terminal.

AI guide

MCP integration guide for AI

For custom API integrations, copy this guide into Claude, Codex, or another coding assistant.

Markdown

Tool arguments

{
  "prompt": "A slow dolly toward a ceramic cup in warm window light",
  "audio": { "type": "artifact", "artifact_id": "artifact_optional_audio" },
  "resolution": "720p",
  "duration": 6,
  "client_request_id": "vid-text-opaque-1"
}

audio is optional and must be supported by the selected model. Omit it for a visually driven result.

Models, controls, and cost

Common controls are prompt, negative_prompt, resolution, duration, aspect_ratio, seed, enhance_prompt, and watermark. Use each only according to the selected model's metadata.

beatra.models.list is the current source for selectable models, supported audio, resolutions, durations, aspect ratios, defaults, and customer prices. Do not copy a model catalog or price table into an agent prompt.

Resolution and duration normally affect cost. Omit them when the user has no preference so request-dependent auto selection can apply the selected model's declared defaults. Set them only from user intent or current discovery. An explicit model is never silently replaced.

MiniMax H3

Set model: "minimax-h3" for MiniMax H3. It requires a prompt, produces 2K video, and accepts integer durations from 4 through 15 seconds. Its supported controls are prompt, resolution, duration, aspect_ratio, and watermark; input audio is not accepted in this mode. Generated output costs 590 credits per second.

Task status and recovery

queued and running are not failures. Keep polling the same task_id; never submit a replacement because work is still running. On a lost create response, retry the identical arguments with the same client_request_id. If any input changes, use a new ID. Return artifacts, resolved model, and charged or refunded credits only from the terminal task response.

REST API

Direct protocol integrations may use POST /v1/videos/text-to-video and the shared task endpoints. Follow the generated API operation. Skill + MCP is the recommended integration; use REST for custom, non-agent applications.