# 動画 Source: https://aiand-docs-staging.pages.dev/ja/api/videos/ Videos API はテキストプロンプトから動画クリップを生成し、必要に応じてアップロード済みのメディア（first/last フレームとしての 1〜2 枚の画像、または参照画像・動画クリップ・音声クリップ）を条件に指定できます。レンダリングには数秒ではなく数分かかるため、**非同期のジョブリソース**として提供されます。ジョブを作成し、終了ステータスになるまでポーリングし、出力をダウンロードします。 ```http POST /v1/videos GET /v1/videos GET /v1/videos/models GET /v1/videos/acceptance POST /v1/videos/acceptance GET /v1/videos/{video_id} GET /v1/videos/{video_id}/content GET /v1/videos/{video_id}/thumbnail ``` 出力は音声付き MP4、768p です。すべてのリクエストで `aspect_ratio` の指定が必要です。 MiniMax H3 による動画生成は日本国内のハードウェアで実行されます。 日本語のシーン説明は、生成前に英語へ翻訳されます。翻訳時、`…` 内のセリフとシーン内に表示されるテキストはそのまま保持するよう翻訳モデルに指示しています。 ## 利用規約への同意 動画ジョブを開始するには、その人がコンソールのプレイグラウンドで Video Service Terms に同意している必要があります。同意した本人が使う API キーはその後使えます。同じ組織でも、同意していない同僚はジョブを開始できません。 ジョブの作成は同意の記録にはなりません。記録できるのは、コンソールログインからの `POST /v1/videos/acceptance` だけです。API キーでは同意できません。 `GET /v1/videos/acceptance` は、現行の規約バージョンと、この組織でその人が同意済みかを返します。 同意がない場合は `403`、コード `agreement_required` です。ジョブ一覧・取得・モデル一覧は開いたままです。 ## ジョブを作成する ```bash curl https://api.aiand.com/v1/videos \ -H "Authorization: Bearer $AIAND_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimaxai/minimax-h3", "prompt": "A paper boat drifting down a rain-soaked gutter at dusk", "seconds": 8, "aspect_ratio": "16:9" }' ``` | フィールド | 必須 | 説明 | | ----------------- | ------ | --------------------------------------------------------------------------------------------------------- | | `model` | はい | [`GET /v1/videos/models`](#動画モデルの一覧) が返すモデル ID | | `prompt` | はい | 最大 7000 文字 | | `seconds` | はい | クリップの長さ、4〜30 秒。**16〜30 秒は試験提供中のため、品質が安定しない場合があります。** | | `aspect_ratio` | はい | `Auto`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` のいずれか | | `image_reference` | いいえ | 一意の `first_frame`/`last_frame` ロールを持つ画像を 1〜2 個（`purpose: "vision"`、image-to-video） | | `references` | いいえ | 条件にする参照メディア（reference-to-video）: `images`, `videos`, `audio`。`image_reference` とは併用不可 | ### 最初と最後のフレーム（image-to-video） 最初に各画像をアップロードし、返された `file_id` を使用します。各画像は `purpose: "vision"` の PNG、JPEG、WebP ファイルで、**30 MiB 以下**である必要があります。動画生成では、100 MiB までアップロードできる Files API よりも低い入力上限があります。 ```bash curl https://api.aiand.com/v1/files \ -H "Authorization: Bearer $AIAND_API_KEY" \ -F "purpose=vision" \ -F "file=@first.jpg" ``` 次に、ユーザーが決めた順序で 1〜2 個のファイル参照を送信します。 ```bash curl https://api.aiand.com/v1/videos \ -H "Authorization: Bearer $AIAND_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimaxai/minimax-h3", "prompt": "A cinematic scene inspired by the references, natural motion", "seconds": 5, "aspect_ratio": "16:9", "image_reference": [ { "file_id": "file-first", "role": "first_frame" }, { "file_id": "file-last", "role": "last_frame" } ] }' ``` API は各ファイルが同じ組織に属し、`purpose: "vision"` であることを検証します。保存済みのファイルは、動画を生成する直前に短時間だけ有効な署名付き URL に変換されるため、公開 URL は不要です。どちらのロールも単独で使用できるため、`first_frame` だけを指定しても `last_frame` は必要ありません。両方を指定する場合、ロールは重複できません。 ### 参照画像・動画・音声（reference-to-video） フレームではなく参照メディアを条件にする場合は、各ファイルを対応する purpose でアップロードし（画像は `vision`、動画は `video`、音声は `audio`）、`file_id` を `references` オブジェクトに入れて渡します。 ```bash curl https://api.aiand.com/v1/videos \ -H "Authorization: Bearer $AIAND_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimaxai/minimax-h3", "prompt": "A cinematic scene inspired by the references, natural motion", "seconds": 5, "aspect_ratio": "16:9", "references": { "images": [{ "file_id": "file-img1" }], "videos": [{ "file_id": "file-clip1" }], "audio": [{ "file_id": "file-aud1" }] } }' ``` 個数、ファイルごとのサイズ、合計サイズはリクエスト時に検証されます。リクエストした動画より長い動画・音声の参照はカットされ、先頭から `seconds` の長さ分だけが使われます。たとえば 8 秒の動画なら、各クリップの最初の 8 秒です。最良の結果を得るには、2〜15 秒のクリップを使ってください。 | 参照 | purpose | 最大個数 | 最大サイズ | 推奨の長さ | | ---- | -------- | -------- | ---------- | ---------- | | 画像 | `vision` | 9 | 30 MiB | — | | 動画 | `video` | 3 | 50 MiB | 2〜15 秒 | | 音声 | `audio` | 3 | 15 MiB | 2〜15 秒 | 次のルールがあります。 - **フレームと参照は混在できません。** リクエストは `image_reference` か `references` のどちらか一方のみを使い、両方は使えません（別々のリクエスト形式です）。 - **音声にはアンカーが必要です。** `references` には画像または動画が少なくとも 1 つ必要で、音声単独は拒否されます。 - **参照は合計 12 個までです。** 上記の種類ごとの上限に加えて、`references` 全体で 12 個を超えるファイルは指定できません。 - **入力ファイルは合計 256 MiB までです。** 上記のファイルごとの上限に加えて、1 回のリクエストの入力ファイルの合計は 256 MiB を超えられません。同じファイルを 2 つの枠で使う場合は 2 回分として数えます。 - **入力ファイルには 1 時間以上の有効期限が必要です。** 1 時間以内に期限切れになるフレームや参照ファイルは拒否されます。再度アップロードしてください。 - **枠ごとに受け付ける形式が決まっています。** 最初と最後のフレームおよび参照画像は PNG、JPEG、WebP。参照動画は MP4、MOV、WebM。参照音声は WAV、MP3、FLAC、OGG、M4A、または MP4・WebM ファイルに入った音声です。GIF や HEIC など、その他の形式は拒否されます。 - **入力ファイルは空であってはなりません。** 0 バイトのフレームや参照ファイルは拒否されます。 - **画像の縦横比は 1:4〜4:1 の範囲である必要があります。** 長辺が短辺の 4 倍を超えるフレーム画像や参照画像は拒否されます。 - **画像には標準的で読み取り可能なヘッダーが必要です。** JPEG は 8 ビットのベースラインまたはプログレッシブ形式に限られ、マルチピクチャ JPEG（一部の iPhone 写真など）や CMYK の JPEG は拒否されます。Ultra HDR 写真は使用できます。画像ヘッダーはファイルの先頭 64 KiB 以内にある必要があり、メタデータが非常に大きいとそれより後ろにずれることがあります。標準的な PNG または JPEG に変換してください。 - **画像は静止画である必要があります。** アニメーション PNG やアニメーション WebP は拒否されます。 これらのルールに違反したリクエストは `400 invalid_value` で拒否されます。可能な場合、`param` が原因の入力を示します。 レスポンスは `status: "moderating"` のジョブオブジェクトです。 ```json { "id": "video_9f2c1b7e4a3d4e8fa1b0c9d8e7f6a5b4", "object": "video", "model": "minimaxai/minimax-h3", "prompt": "A paper boat drifting down a rain-soaked gutter at dusk", "seconds": 8, "status": "moderating", "error": null, "cost": "0.64000000", "currency": "usd", "created_at": 1755302400, "completed_at": null, "thumbnail": false } ``` `status` は `moderating`、`translating`、`queued`、`in_progress`、`completed`、`failed`、`canceled` のいずれかです。現在 `canceled` で終わるジョブはありません。認識できないステータスは「実行中」として扱ってください — 中間ステージは今後追加される可能性があります。`error` はジョブが失敗した場合のみ設定されます。 ## 入力モデレーション すべてのジョブは `moderating` から始まり、プロンプトと参照メディアがコンテンツポリシーに照らして検査されます。通常は数秒（参照がある場合は最大 1 分程度）で完了し、許可されたジョブはプロンプトを英語へ翻訳する `translating` を経て `queued` に進み、通常どおりレンダリングされます。ポリシーに違反するリクエストはエラーコード `moderation_blocked` で失敗し、課金は発生しません。 ```json { "status": "failed", "error": { "code": "moderation_blocked", "message": "Your request was rejected by our content moderation system." } } ``` モデレーションシステム自体が利用できない場合、ジョブはエラーコード `moderation_unavailable` でフェイルクローズします。何も判定されず課金もされないため、後で再送信してください。同様に、日本語プロンプトの翻訳ができない場合、ジョブはエラーコード `translation_unavailable` でフェイルクローズします。課金はされないため、後で再送信してください。 ## 完了をポーリングする ```bash curl https://api.aiand.com/v1/videos/video_9f2c1b7e4a3d4e8fa1b0c9d8e7f6a5b4 \ -H "Authorization: Bearer $AIAND_API_KEY" ``` 通常のクリップで数分かかります。終了ステータスになるまで 10〜30 秒間隔でポーリングしてください。より短い間隔でポーリングしてもレンダリングは早く終わりません。 ## 出力をダウンロードする `status` が `completed` になったらバイト列を取得します。レスポンスは JSON ではなく MP4 そのものです。 ```bash curl https://api.aiand.com/v1/videos/video_9f2c1b7e4a3d4e8fa1b0c9d8e7f6a5b4/content \ -H "Authorization: Bearer $AIAND_API_KEY" \ -o clip.mp4 ``` `completed` でないジョブのコンテンツを要求すると `400` が返ります。 ### サムネイル 完了したジョブには通常、クリップの冒頭付近から切り出した幅 480 ピクセルの JPEG 静止画もあります。ダウンロードできるサムネイルがある場合、ジョブの `thumbnail` は `true` になります。ない場合は `404` を、ジョブが `completed` でない場合は `400` を返します。 ```bash curl https://api.aiand.com/v1/videos/video_9f2c1b7e4a3d4e8fa1b0c9d8e7f6a5b4/thumbnail \ -H "Authorization: Bearer $AIAND_API_KEY" \ -o clip.jpg ``` サムネイルは無料で、動画と一緒に削除されます。 ## ジョブの一覧 ```bash curl "https://api.aiand.com/v1/videos?limit=20" \ -H "Authorization: Bearer $AIAND_API_KEY" ``` 新しい順に返ります。`limit` の既定値は 20、上限は 100 です。ページングには `after=` を指定します。組織内の全員のジョブが返ります。自分（または API キーの所有者）が作成したジョブだけに絞るには `mine=true` を指定します。 ## 動画モデルの一覧 認証は任意です。API キーを付けると組織の請求通貨で価格が表示され、付けない場合は USD で表示されます。キーなしのリクエストは IP ごとに毎分 600 回までに制限されます。この上限は [`GET /v1/models`](/ja/api/models/) を含む、キーなしで呼べるすべてのカタログエンドポイントで共有されます。 ```bash curl https://api.aiand.com/v1/videos/models ``` API キーを使う場合: ```bash curl https://api.aiand.com/v1/videos/models \ -H "Authorization: Bearer $AIAND_API_KEY" ``` 各エントリには秒単価が、出力解像度ごとに 1 行ずつ含まれます。 ```json { "object": "list", "data": [ { "id": "minimaxai/minimax-h3", "object": "video_model", "name": "MiniMaxAI/MiniMax-H3", "description": null, "pricing": [ { "resolution": "768p", "per_second": "0.055000", "currency": "usd" } ] } ] } ``` ## 課金 レンダリングの料金は `秒単価 × 秒数` で、**完了時にのみ課金されます**。失敗またはタイムアウトしたジョブが課金されることはありません。送信後のジョブはキャンセルできません。 1 回のレンダリングは数ドル規模で途中で中断できないため、料金は送信時に `秒単価 × リクエストした秒数` で確定します。その確定料金と実行中のレンダリング料金の合計を残高がカバーできない場合、ジョブは拒否されます。残高がゼロを超えていればリクエストを受け付けるチャットエンドポイントより厳格です。 ジョブオブジェクトの `cost` と `currency` は最初のレスポンスからこの確定料金を示します。残高からの差し引きは、レンダリングが正常に完了した後にのみ行われます。 ## エラー | ステータス | コード | 意味 | | ---------- | ---------------------------- | ------------------------------------------------------------------------------------ | | `400` | `invalid_value` | 不正なボディ、範囲外の `seconds`、不正またはサイズ超過の参照、完了前のコンテンツ要求 | | `403` | `agreement_required` | この人がコンソールのプレイグラウンドで現行の Video Service Terms に同意していない | | `403` | `zero_data_retention` | 組織が[ゼロデータリテンション](/ja/organizations/zero-data-retention/)のため、動画を生成できない | | `402` | `insufficient_credits` | 残高がこのレンダリングの確定料金に満たない | | `402` | `monthly_budget_reached` | 組織の月間予算の残りが、このレンダリングと実行中のレンダリングの確定料金に満たない | | `404` | `model_not_found` | 不明なモデル | | `404` | `model_access_denied` | 組織にこのモデルの利用権限がない | | `429` | `concurrency_limit_exceeded` | プランで許可された同時レンダリング数に達している | | `429` | `rate_limit_exceeded` | 組織からの送信が 1 分あたり 10 回を超えた。`Retry-After` の秒数後に再試行 | | `409` | `conflict` | ジョブが実行中、または審査中のため削除できない | | `503` | `provider_unavailable` | このモデルの動画生成は一時的に利用できません | 受け付け済みのジョブも失敗することがあります。たとえば次のエラーコードです。失敗したジョブは課金されません。 - `engine_unavailable`：動画生成を利用できませんでした。後で再送信してください。 - `engine_timeout`：制限時間内に動画生成が完了しませんでした。再送信してください。解決しない場合はサポートまでお問い合わせください。 - `engine_rejected`：動画を生成できませんでした。同じ入力で再試行しても同じ結果になります。解決しない場合はサポートまでお問い合わせください。 ## 保持期間と削除 完了したジョブ（生成された動画と、プロンプトを含むジョブ記録）は、完了から **30 日後** に自動的に削除されます。残しておきたいものは、それまでにダウンロードしてください。 `DELETE /v1/videos/{video_id}` で即時に削除できます。 ```bash curl -X DELETE https://api.aiand.com/v1/videos/video_abc123 \ -H "Authorization: Bearer $AIAND_API_KEY" ``` ```json { "id": "video_abc123", "object": "video", "deleted": true } ``` 削除は完全で、取り消せません。実行中のジョブは先に完了させる必要があります。ステータスが終了状態 になるまでポーリングしてから削除してください。