# Beatra Skill + MCP — Generate video from text

> Create a video from a scene description, with optional audio guidance.
> Self-contained workflow guide for AI agents.
> Human-readable page: https://docs.beatra.ai/en/docs/capabilities/videos/text-to-video

- Primary surface: the Universal Beatra Skill with authenticated MCP.
- Install or reconnect: https://beatra.ai/install.md
- MCP endpoint: `https://mcp.beatra.ai/mcp`
- Billable action: `beatra.videos.generate`
- Dynamic model facts: call `beatra.models.list` with `capability: "text_to_video"` only when model constraints, controls, or prices matter.
- Interaction model: create one opaque `client_request_id`, submit the finalized arguments exactly once, then poll the returned `task_id` with `beatra.tasks.get` until terminal.
- Local media: call `beatra.assets.upload`, perform the returned HTTPS PUT exactly, and use the artifact ID from the PUT response.

REST/OpenAPI is the fallback protocol path, not the primary agent packaging.

---

## 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.

## 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 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](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.

---

## Appendix: shared Skill + MCP contract

### Retry identity

One logical generation has one `client_request_id`. If the create response is
lost, retry the exact same arguments with that ID. If any prompt, media, model,
or output control changes, use a new ID. Never create another paid task merely
because the first task is `queued` or `running`.

### Polling and billing truth

Poll with `beatra.tasks.get` using bounded backoff. Stop at `succeeded`,
`failed`, or `canceled`. Only the task response is authoritative for the
resolved model, artifacts, charged credits, and refunded credits.

### Recovery

Preserve structured Beatra error codes. Reconnect on authentication failure;
stop and request a balance action on insufficient balance; refresh current
constraints with `beatra.models.list` after model validation; request a new
upload grant after expiration or MIME/length mismatch. Changed generation
arguments always require a new `client_request_id`.