# Generate from references
> Preserve subjects, products, scenes, video identity, or voice across a new video.

Preserve subjects, products, scenes, video identity, or voice across a new video.

## 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"`, `kind: "video"`, or `kind: "audio"`, 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`.

## AI guide

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

## 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 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-only references are valid. Do not send `role` or
`reference_voice`. Input images and audio are free. At public `720p`, accepted
input-video and generated output time each cost 370 credits per second; at
`2k`, each costs 590. Omitting resolution with explicit H3 now defaults to 720p.

### Wan 3.0

Set `model: "wan3.0-video"` or `wan3.0-video-prime`. Up to 10 images, 5 videos,
and 5 audio files (20 total); reference video/audio each cap at 15 seconds.
Audio requires a companion image or video. Input-video seconds are billed at
the same per-second rate as output. `480p` is 225 credits/s on `wan3.0-video`
and 335 on the higher tier.

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