Generate from references

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.

AI guide

Tool arguments

{
  "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. Skill + MCP is the recommended integration; REST serves custom applications.