# テキストから動画を生成
> シーンの説明から動画を作成し、必要に応じて音声ガイドを付けられます。

シーンの説明から動画を作成し、必要に応じて音声ガイドを付けられます。

## Agent の基本フロー

Universal Skill から MCP ツール `beatra.videos.generate` を使います。この
ツールは課金対象で、非同期タスクを返します。

1. シーン、動き、長さ、画質を確定します。
2. モデル、音声対応、制約、価格が選択に影響する場合は、
   `capability: "text_to_video"` で `beatra.models.list` を呼びます。
   それ以外は `model` を省略するか `auto` を使います。
3. ローカル音声は `beatra.assets.upload` でアップロードし、artifact ID を使います。
4. 最終引数に対して不透明な `client_request_id` を一つ作り、一度だけ送信します。
5. `beatra.tasks.get` で同じタスクを終端状態までポーリングします。

## AI ガイド

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

## ツール引数

```json
{
  "prompt": "暖かな窓光の中の陶器カップへゆっくりドリーインする",
  "audio": { "type": "artifact", "artifact_id": "artifact_optional_audio" },
  "resolution": "720p",
  "duration": 6,
  "client_request_id": "vid-text-opaque-1"
}
```

`audio` は任意で、選択したモデルが対応している場合だけ指定します。

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

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

選択可能なモデル、音声、解像度、長さ、アスペクト比、既定値、価格の
最新情報は `beatra.models.list` を正とします。静的なモデル一覧や価格表を
Agent のプロンプトへコピーしないでください。

解像度と長さは通常コストに影響します。ユーザーに明示的な希望がない場合は
省略し、リクエスト依存の `auto` 選択で最終モデルが宣言する既定値を適用します。
ユーザーの意図または現在のモデル探索結果に基づく場合だけ指定してください。
明示されたモデルを黙って置き換えてはいけません。

### Seedance 2.5

**Seedance 2.5** を使用する場合は `model: "seedance-2.5"` または `"seedance-2.5-fast"`（2.0 系は `"seedance-2.0"` / `"seedance-2.0-fast"`）を指定します。シネマティックなカメラワークや複数アスペクト比に対応しており、最新の出力秒単価と対応解像度・秒数は `capability: "text_to_video"` で `beatra.models.list` を確認してください。

### MiniMax H3

MiniMax H3 を使うには `model: "minimax-h3"` を指定します。プロンプトは必須で、
長さは 4〜15 秒の整数です。公開 `720p` の出力は
1 秒あたり 370 クレジット、`2k` は 590 クレジットです。H3 を明示して解像度を省略
した場合の既定は 720p です。使用できる制御は `prompt`、`resolution`、
`duration`、`aspect_ratio`、`watermark` で、このモードは入力音声に対応しません。

### Wan 3.0

`model: "wan3.0-video"` または `wan3.0-video-prime` で 2〜30 秒、
`480p` / `720p` / `1080p`（既定は `720p`）。任意の `audio` は駆動音声で課金されません。
`480p` は `wan3.0-video` が出力 1 秒 225 クレジット、上位版は 335 です。
`negative_prompt` は使えません。価格は `beatra.models.list` を確認します。

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

`queued` と `running` は失敗ではありません。同じ `task_id` を継続して確認し、
実行中という理由で別タスクを作成しないでください。作成レスポンスを失った
場合は、同じ `client_request_id` と完全に同一の引数で再試行します。入力を
変えた場合は新しい ID が必要です。成果物、実モデル、課金は終端タスクの応答
だけを正とします。

## REST で呼び出す

直接プロトコル統合では `POST /v1/videos/text-to-video` と共通タスク API を
利用できます。[API 操作](https://docs.beatra.ai/ja/docs/api-reference/operations/videos/videos_t2v_v1_videos_text_to_video_post)
に従ってください。標準の Agent 体験は Skill + MCP です。