# 参照素材から動画を生成
> 人物、商品、シーン、動画上の同一性、声を新しい動画で維持します。

人物、商品、シーン、動画上の同一性、声を新しい動画で維持します。

## Agent の基本フロー

画像や動画で同一性、外観、スタイル、商品、背景、ポーズ、声をガイドする
場合は `beatra.videos.generate_from_references` を使います。既存クリップを
変更する目的なら edit を使います。

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": "Video 1 presents Image 1 in a bright studio 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` は参照項目に付く音声メディアで、真偽値ではありません。
`auto`/Wan では画像と動画を別々に `Image n`/`Video n`（中国語では
`图n`/`视频n`）で数えます。HappyHorse は配列順の `[Image n]` を使います。
HappyHorse/Wan では意味的 `role` は使えません。別モデルの discovery が
対応 role を明示した場合だけ指定してください。

## モデル、制御、コスト

共通コントロールは `prompt`、`negative_prompt`、`resolution`、
`duration`、`aspect_ratio`、`seed`、`enhance_prompt`、`watermark` です。
各項目は選択モデルのメタデータに従って使います。

参照数、対応 kind、プロンプト参照構文、声の対応、条件付き長さ、比率、価格は
`beatra.models.list` を正とします。価格メタデータで入力動画秒数が課金対象に
なっている場合は、それも見積りに含めます。

### MiniMax H3

`model: "minimax-h3"` を指定すると、4〜15 秒のマルチモーダル参照動画を生成
できます。プロンプトは必須で、画像は最大 5 枚、動画は最大 3 本、音声は最大
3 本です。参照動画と参照音声はそれぞれ合計 15 秒までで、音声だけの参照も
利用できます。`role` と `reference_voice` は指定しません。入力画像と音声は
無料です。公開 `720p` では受理された入力動画時間と生成動画時間がそれぞれ
1 秒あたり 370 クレジット、`2k` では 590 クレジットです。H3 を明示して解像度を
省略した場合の既定は 720p です。

### Wan 3.0

`model: "wan3.0-video"` または `wan3.0-video-prime`。画像 10、動画 5、音声 5（合計 20）まで。
参照動画/音声はそれぞれ合計 15 秒まで。音声には画像または動画の同伴が必要です。
入力動画秒は出力と同じ単価です。`480p` は 1 秒 225 / 335 クレジット（標準 / 上位）。

## タスクの状態とリカバリー

同一再試行では参照順序を維持します。`queued` または `running` の間は
同じタスクを確認します。参照、声、プロンプト、出力制御
の変更は新しい論理リクエストであり、新しい `client_request_id` が必要です。

## REST で呼び出す

直接プロトコル統合では `POST /v1/videos/reference-to-video` を利用できます。
[API 操作](https://docs.beatra.ai/ja/docs/api-reference/operations/videos/videos_r2v_v1_videos_reference_to_video_post)
に従ってください。推奨の統合方法は Skill + MCP です。REST はカスタムアプリケーション向けです。