# Generate video from text
> Create video clips from a scene description, with optional audio guidance.

Create video clips from a scene description, with optional audio guidance.

## Primary agent path

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

1. Finalize the scene, motion, duration, and fidelity choices.
2. 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`.
3. Upload local audio with `beatra.assets.upload` and use its artifact ID.
4. Create one opaque `client_request_id` and submit the final arguments once.
5. Poll the returned task with `beatra.tasks.get` until it is terminal.

## AI guide

AI integration guide: https://docs.beatra.ai/llms/videos-text-to-video.md

## Tool arguments

```json
{
  "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 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.

### Seedance 2.5

Set `model: "seedance-2.5"` or `"seedance-2.5-fast"` for **Seedance 2.5** (`Seedance 2.5` / `Seedance 2.5 Fast`), or `"seedance-2.0"` / `"seedance-2.0-fast"` for the 2.0 tier. Seedance 2.5 supports multi-aspect cinematic motion and synchronized audio options; check `beatra.models.list` with `capability: "text_to_video"` for live per-second credit rates and supported resolution/duration combinations.

### MiniMax H3

Set `model: "minimax-h3"` for MiniMax H3. It requires a prompt and accepts
integer durations from 4 through 15 seconds. Public `720p` costs 370 credits per output second; `2k` costs 590 credits per output
second. Omitting resolution with explicit H3 now defaults to 720p. Its supported
controls are `prompt`, `resolution`, `duration`, `aspect_ratio`, and `watermark`;
input audio is not accepted in this mode.

### Wan 3.0

Set `model: "wan3.0-video"` or `wan3.0-video-prime` for 2–30 second clips at
`480p`, `720p`, or `1080p` (default `720p`). Optional `audio` is driving audio
and is not billed. `480p` is 225 credits per output second on `wan3.0-video`
and 335 on the higher tier. `negative_prompt` is not supported. Confirm prices with
`beatra.models.list`.

## 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](https://docs.beatra.ai/en/docs/api-reference/operations/videos/videos_t2v_v1_videos_text_to_video_post).
Skill + MCP is the recommended integration; use REST for custom, non-agent
applications.