# 从参考素材生成视频
> 在新视频中保持主体、商品、场景、视频身份或声音。

在新视频中保持主体、商品、场景、视频身份或声音。

## Agent 主路径

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

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

## AI 指南

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

## 工具参数

```json
{
  "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` 为准。若价格元数据表明输入视频时长参与计费，
成本估算也必须包含它。

### MiniMax H3

设置 `model: "minimax-h3"` 可生成 4–15 秒的多模态参考视频。H3 必须提供
提示词，最多接受 5 张图片、3 个视频和 3 个音频；参考视频和参考音频各自
累计不得超过 15 秒，并允许只提供音频参考。不要传 `role` 或
`reference_voice`。输入图片与音频免费；公共 `720p` 下，接受的输入视频
时长和生成视频时长各为每秒 370 积分；`2k` 下各为每秒 590 积分。
显式选择 H3 并省略分辨率时默认 720p。

### Wan 3.0

设置 `model: "wan3.0-video"` 或 `wan3.0-video-prime`。最多 10 张图、5 段视频、5 段音频（合计 20）；
参考视频/音频各累计不超过 15 秒。音频必须伴随图或视频。输入视频秒与输出同价计费。
`480p` 为每秒 225 / 335 积分（标准版 / 高阶版）。

## 任务状态与恢复

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

## 通过 REST 调用

直接协议集成可使用 `POST /v1/videos/reference-to-video`，并遵循
[API 操作定义](https://docs.beatra.ai/zh/docs/api-reference/operations/videos/videos_r2v_v1_videos_reference_to_video_post)。
推荐通过 Skill + MCP 接入；REST 适合自定义应用直连。