# Beatra Skill + MCP — Generate toward a final frame

> Generate motion toward a controlled last frame, with an optional first frame.
> Self-contained workflow guide for AI agents.
> Human-readable page: https://docs.beatra.ai/en/docs/capabilities/videos/frames-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.interpolate`
- Dynamic model facts: call `beatra.models.list` with `capability: "frames_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 `beatra.videos.interpolate` when a required last image defines the ending.
Add `first_frame` only when the opening must also be controlled.

1. Upload the last frame, an optional first frame, and optional driving audio.
2. Call `beatra.models.list` with `capability: "frames_to_video"` for current
   media combinations, duration, resolution, audio support, and prices.
3. Describe the movement toward the ending, including the transition from the
   first frame when one is supplied.
4. Submit once with one `client_request_id`; poll with `beatra.tasks.get`.

## Tool arguments

```json
{
  "prompt": "The product rises and rotates smoothly between the two views",
  "first_frame": { "type": "artifact", "artifact_id": "artifact_start" },
  "last_frame": { "type": "artifact", "artifact_id": "artifact_end" },
  "driving_audio": { "type": "artifact", "artifact_id": "artifact_optional_audio" },
  "resolution": "720p",
  "duration": 6,
  "client_request_id": "vid-frames-opaque-1"
}
```

`last_frame` is required; `first_frame` and `driving_audio` are optional but
must be supported by the selected model. Image-driven aspect-ratio rules come
from model discovery.

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

Use `beatra.models.list` instead of a static model table. It returns selectable
models, accepted frame/audio combinations, constraints, defaults, ignored
fields, and customer prices. Resolution and duration normally affect cost; do
not silently change them.

### MiniMax H3

Set `model: "minimax-h3"` for a last-frame-only or first-and-last-frame H3
request. The last frame and prompt are required; the first frame is optional.
Duration is 4–15 seconds. Public `720p` costs 370 credits per output second;
`2k` costs 590. Omitting resolution with explicit H3 now defaults to 720p.
H3 accepts `watermark` but not driving audio or the other optional controls.
Supplied boundary images are free.

### Wan 3.0

Set `model: "wan3.0-video"` or `wan3.0-video-prime` with first and last frames.
Duration is 2–30 seconds. Do not send `driving_audio`. `480p` is
225 credits per output second on `wan3.0-video` and 335 on prime.

## Task status and recovery

Poll the same task through `queued` and `running`. A lost create response may be
retried only with identical arguments and the same `client_request_id`.
Swapping either frame or changing audio, prompt, or output settings requires a
new ID.

## REST API

Direct protocol integrations may use `POST /v1/videos/frames-to-video`. Follow
the generated [API operation](https://docs.beatra.ai/en/docs/api-reference/operations/videos/videos_f2v_v1_videos_frames_to_video_post).
Skill + MCP is the recommended integration; REST serves custom 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`.