# Beatra Skill + MCP — Generate from references

> Preserve subjects, products, scenes, video identity, or voice across a new video.
> Self-contained workflow guide for AI agents.
> Human-readable page: https://docs.beatra.ai/en/docs/capabilities/videos/reference-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_from_references`
- Dynamic model facts: call `beatra.models.list` with `capability: "reference_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.generate_from_references` when media should guide identity,
appearance, style, product, background, pose, or voice. Use edit when the goal
is to change an existing clip rather than create a new one.

1. Upload every local image, video, and voice reference.
2. Give each reference `kind: "image"` or `kind: "video"`, preserve its order,
   and use the model's returned prompt-reference syntax.
3. Call `beatra.models.list` with `capability: "reference_to_video"` for current
   counts, media combinations, duration rules, and prices.
4. Submit once with one `client_request_id`; poll with `beatra.tasks.get`.

## Tool arguments

```json
{
  "prompt": "Video 1 presents Image 1 in a bright studio scene while keeping the same voice",
  "references": [
    {
      "kind": "image",
      "media": { "type": "artifact", "artifact_id": "artifact_product" }
    },
    {
      "kind": "video",
      "media": { "type": "artifact", "artifact_id": "artifact_presenter" },
      "reference_voice": { "type": "artifact", "artifact_id": "artifact_voice" }
    }
  ],
  "resolution": "720p",
  "duration": 6,
  "client_request_id": "vid-refs-opaque-1"
}
```

`reference_voice` is an audio media reference attached to one reference item;
it is not a Boolean.
For `auto`/Wan, images and videos are numbered separately as `Image n` and
`Video n` (or `图n` and `视频n`). HappyHorse image references use `[Image n]`
in array order. HappyHorse/Wan reject semantic `role`; only use it when model
discovery explicitly lists supported roles for another selected model.

## 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 authoritative for reference counts, supported kinds,
prompt-reference syntax, optional voice support, conditional duration limits,
aspect-ratio behavior, and prices. Input-video seconds can affect billing when
the returned price metadata says so.

### MiniMax H3

Set `model: "minimax-h3"` for 2K multimodal reference generation lasting
4–15 seconds. H3 requires a prompt and accepts up to five images, three videos,
and three audio files. Referenced video and audio are each limited to 15
seconds in aggregate; audio cannot be used without at least one image or
video. Do not send `role` or `reference_voice`. Input images and audio are
free. Accepted input-video time and generated output time each cost 590 credits
per second.

## Task status and recovery

Keep reference order stable across an identical retry. Poll the same task while
it is `queued` or `running`. Any changed reference, voice,
prompt, or output control is a new logical request and needs a new
`client_request_id`.

## REST API

Direct protocol integrations may use `POST /v1/videos/reference-to-video`.
Follow the generated [API operation](https://docs.beatra.ai/en/docs/api-reference/operations/videos/videos_r2v_v1_videos_reference_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`.