从参考素材生成视频

Agent 主路径

当图片或视频需要约束身份、外观、风格、商品、背景、姿态或声音时，使用 beatra.videos.generate_from_references。如果目标是修改已有片段，应使用编辑工具。

上传所有本地图片、视频与声音参考。
每个参考项用 kind: "image" 或 kind: "video" 标明类型，保持顺序，并按模型返回的参考指代语法编写提示词。
用 capability: "reference_to_video" 调用 beatra.models.list，读取当前数量、组合、时长规则与价格。
使用一个 client_request_id 提交一次，再用 beatra.tasks.get 轮询。

AI 指南

给 AI 的集成说明

接入自有应用时，可以把这份 API 指南复制给 Claude、Codex 或其他编程助手。

工具参数

{
  "prompt": "视频1在明亮影棚中展示图1，并保持同一位讲解者及其音色",
  "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 是绑定到某个参考项的音频媒体，不是布尔值； auto/Wan 的图片和视频分别按顺序使用“图n/视频n”（英文为 Image n/Video n）；HappyHorse 图片按数组顺序使用 [Image n]。 HappyHorse/Wan 不接受语义 role；仅当其他显式模型的发现结果列出角色时使用。

模型、控制与成本

通用控制项包括 prompt、negative_prompt、resolution、 duration、aspect_ratio、seed、enhance_prompt 和 watermark；每一项都应按所选模型的元数据使用。

参考数量、支持的类型、提示词指代语法、声音能力、条件时长限制、宽高比与价格均以 beatra.models.list 为准。若价格元数据表明输入视频时长参与计费，成本估算也必须包含它。

设置 model: "minimax-h3" 可生成 4–15 秒的 2K 多模态参考视频。H3 必须提供提示词，最多接受 5 张图片、3 个视频和 3 个音频；参考视频和参考音频各自累计不得超过 15 秒。音频不能单独作为参考，必须同时包含图片或视频。不要传 role 或 reference_voice。输入图片与音频免费；接受的输入视频时长和生成视频时长分别按每秒 590 credits 计费。

任务状态与恢复

相同重试必须保持参考顺序。queued 或 running 时轮询同一任务。参考、声音、提示词或输出控制有任何改变，都属于新请求，需用新的 client_request_id。

通过 REST 调用

直接协议集成可使用 POST /v1/videos/reference-to-video，并遵循 API 操作定义。推荐通过 Skill + MCP 接入；REST 适合自定义应用直连。