# 画像をアニメーション化
> 一枚の静止画を動かし、必要に応じて駆動音声に追従させます。

一枚の静止画を動かし、必要に応じて駆動音声に追従させます。

## Agent の基本フロー

一枚の画像が開始構図を決める場合は `beatra.videos.animate` を使います。開始
フレームと終了フレームの両方が必要なら `beatra.videos.interpolate` を使います。

1. ローカル画像と任意の音声を `beatra.assets.upload` でアップロードします。
2. モデル制約、音声対応、価格が重要なら `capability: "image_to_video"` で
   `beatra.models.list` を呼びます。
3. 元画像と矛盾しない動きとカメラワークを記述します。
4. 一つの `client_request_id` で一度だけ送信し、`beatra.tasks.get` で確認します。

## AI ガイド

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

## ツール引数

```json
{
  "prompt": "被写体がカメラを向き、カメラはゆっくり前進する",
  "image": { "type": "artifact", "artifact_id": "artifact_first_frame" },
  "driving_audio": { "type": "artifact", "artifact_id": "artifact_optional_audio" },
  "resolution": "720p",
  "duration": 6,
  "client_request_id": "vid-animate-opaque-1"
}
```

`driving_audio` は省略できます。画像には公開 HTTPS `url`、または URI 全体が
256KB 以下の `data_uri` を使えます。それより大きいメディアは先にアップロードし、
artifact を使ってください。ローカルファイルパスは使えません。

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

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

対応メディア組み合わせ、音声制限、解像度、長さ、入力画像から導出される
比率、既定値、価格は `beatra.models.list` を正とします。解像度や長さを
黙って下げないでください。ユーザーが選択可能なモデルを指定しない限り
`auto` を使います。

### MiniMax H3

MiniMax H3 で画像を動画化するには `model: "minimax-h3"` を指定します。
プロンプトは必須、長さは 4〜15 秒で、アスペクト比は入力画像から導出されます。
公開 `720p` の出力は 1 秒あたり 370 クレジット、`2k` は 590 クレジットです。
H3 を明示して解像度を省略した場合の既定は 720p です。H3 は `watermark` に
対応しますが、駆動音声やその他の任意制御には対応しません。入力画像は無料です。

### Wan 3.0

`model: "wan3.0-video"` または `wan3.0-video-prime`。長さは 2〜30 秒、アスペクト比は画像に従います。
`driving_audio` は送らないでください（先頭フレームと混在できません）。`480p` は出力 1 秒 225 / 335 クレジット（標準 / 上位）です。

## 保存したアバター

トーキングアバター用の人物写真をアカウントの「アバター」として保存すると、別のセッションでもそのまま使えます。

- `beatra.avatars.list` は読み取り専用で課金はありません。アバター一覧（デフォルトが先頭）と `default_avatar_id` を返します。各アバターには `image.artifact_id` と組み合わせた `voice` が含まれます。`image.artifact_id` を `beatra.videos.animate` の人物写真として渡し、いつもどおり先にライブのモデルカードと照合してください。
- `beatra.avatars.save` は課金されません。ユーザーが保存に同意し、肖像の同意文を確認したあとにだけ呼び出します。`consent_subject` は `self`（写真の人物がユーザー本人）か `authorized_other`（本人から個別の同意を得ている）です。同じ画像を再度保存すると、同じアバターが返ります。

```json
{
  "artifact_id": "artifact_01JX...",
  "display_name": "鵬博士・講義",
  "purpose": "講師",
  "voice_id": "voice_01JX...",
  "consent_attested": true,
  "consent_subject": "self"
}
```

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

`queued` または `running` の間は同じ `task_id` を確認します。作成応答を失った
場合は同じ引数と `client_request_id` だけで再試行できます。画像、音声、
プロンプト、モデル、出力制御を変える場合は新しい ID が必要です。

## REST で呼び出す

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