> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.beatapi.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server. # ミュージックビデオ > 画像、音声、制作設定を指定して、ミュージックビデオのワークフロータスクを作成します。 `POST https://api.beatapi.io/v1/music-video/tasks` 画像、音声、制作設定を指定して、ミュージックビデオのワークフロータスクを作成します。 ## 認証 `Authorization`   `string`   **必須** BeatAPI の API キーを Bearer トークンとして送信します。API キーは[ダッシュボード](https://beatapi.io/dashboard)で作成できます。 ``` Authorization: Bearer ``` 通常の API キーは、信頼できるサーバーで管理してください。リクエストボディには `Content-Type: application/json` が必要です。対応するエンドポイントでは `Idempotency-Key` は任意ですが、同一のリクエストボディで安全に再試行するために指定を推奨します。 ## リクエストボディ `mv_tier`   `enum`   **任意** ミュージックビデオのプランを選択します。Standard の場合は省略でき、Premium の場合は `premium` を指定する必要があります。 **選択肢:** `standard`, `premium` \ **デフォルト値:** `"standard"` --- `images`   `string[]`   **任意** トップレベルに指定するシーン画像です。Standard は 1～7 枚が必須です。Premium の歌唱モードは 0～6 枚に対応し、dance と perform は公開 HTTPS の PNG・JPEG・WebP 画像の URL をちょうど 6 個指定する必要があります。 **要素数:** 0 – 7 件 --- `audio_url`   `string`   **必須** トップレベルに指定する公開 HTTPS 音声 URL です。Standard は 10～180 秒、Premium は 10～300 秒に対応しています。 **形式:** `uri` --- `prompt`   `string`   **任意** ストーリー、舞台設定、パフォーマンス、カメラワーク、照明、テンポに関する制作方針を任意で指定します。最大 3000 文字です。 **文字数:** 最大 3000 文字 --- `language`   `enum`   **任意** Standard ワークフローの台詞と歌詞に使用する言語です。 **選択肢:** `en`, `zh` --- `quality`   `enum`   **任意** 生成品質の区分です。540p では high を利用できません。 **選択肢:** `standard`, `high` \ **デフォルト値:** `"standard"` --- `style`   `string`   **任意** 映画風、アニメ風、ドキュメンタリー風、ファッション誌風など、視覚的なスタイルを簡潔に指定します。任意です。 **文字数:** 最大 200 文字 --- `aspect_ratio`   `enum`   **任意** 出力先の表示形式です。掲載先のプレーヤーや SNS フィードに合わせて、明示的に指定してください。 **選択肢:** `1:1`, `16:9`, `9:16`, `4:3`, `3:4` --- `resolution`   `enum`   **任意** トップレベルに指定する出力解像度です。Standard は 540p・720p・1080p に対応し、Premium は 720p 固定です。 **選択肢:** `540p`, `720p`, `1080p` \ **デフォルト値:** `"720p"` --- `lip_sync`   `boolean`   **任意** 口の動きを音声に合わせたパフォーマンスを生成します。true の場合は `lip_ref_url` が必要です。 **デフォルト値:** `false` --- `lip_ref_url`   `string`   **任意** Standard のリップシンクに使う、正面から撮影した顔のアップ画像の公開 HTTPS URL です。 **形式:** `uri` --- `add_subtitle`   `boolean`   **任意** 生成した字幕、または指定した字幕を最終動画に焼き込みます。 **デフォルト値:** `false` --- `subtitle_color`   `string`   **任意** 字幕の文字色を 6 桁の 16 進数で指定します。字幕を有効にした場合に使用されます。 --- `srt_url`   `string`   **任意** 任意の公開 HTTPS `.srt` 字幕ファイルです。ローカルの字幕ファイルは `POST /v1/files` でアップロードしてください。 **形式:** `uri` --- `duration`   `integer`   **任意** トップレベルの課金計算用の代替値です。検出された音声の長さが優先されます。Standard は 10～180 秒、Premium は 10～300 秒に対応しています。 **範囲:** 10 – 300 --- `compose_mode`   `enum`   **任意** auto は最終ミュージックビデオを自動で合成します。manual は `requires_action` で一時停止し、合成前にショットを確認・編集できます。 **選択肢:** `auto`, `manual` \ **デフォルト値:** `"auto"` --- `mv_mode`   `enum`   **任意** Premium のパフォーマンスモードです。歌唱モードでは `lip_ref_urls` が必要です。dance と perform では `images` をちょうど 6 枚指定する必要があります。 **選択肢:** `sing`, `sing_perform`, `dance`, `perform` --- `lip_ref_urls`   `string[]`   **任意** sing と sing\_perform では必須です。dance と perform では省略してください。正面から撮影した顔のアップ画像を、公開 HTTPS URL で 1～2 枚指定します。 **要素数:** 1 – 2 件 ## レスポンス リクエストが成功すると、HTTP `201` が返されます。 ```json { "data": { "id": "task_8K2qA", "object": "task", "task_kind": "workflow", "capability_id": "music-video", "capability_version": 1, "workflow": "music-video", "status": "queued", "stage": "queued", "storyboard": { "shots": [] }, "created_at": 1782210000, "updated_at": 1782210000, "completed_at": null, "output": null, "usage": { "credits_reserved": 1.5, "credits_charged": 1.5, "billable_duration_seconds": 15, "credits_settled": 0, "credits_refunded": 0 }, "request_id": "req_abc123", "error_code": null, "error_message": null } } ``` ## 手動レビューの流れ `compose_mode` が `manual` の場合は、タスクが `requires_action` になるまでポーリングし、返された絵コンテとショット ID を使って次の操作を行います。 1. ショットのプロンプトや Premium の参照画像を調整する場合は、`POST /v1/music-video/tasks/{task_id}/shots/{shot_id}/edit` を呼び出します。 2. レビュー用のホスト済みプレビューが必要な場合は、`GET /v1/music-video/tasks/{task_id}/shots/{shot_id}/media` を呼び出します。 3. 選択したショットの準備ができたら、`POST /v1/music-video/tasks/{task_id}/compose` を呼び出して合成します。 編集や合成の後も、同じ親タスクを引き続きポーリングしてください。自動合成では、これらの手動操作は必要ありません。 ## 次の手順 受付レスポンスの `data.id` を保存し、`status` が `succeeded` または `failed` になるまで、5～10 秒ごとに `GET /v1/tasks/{task_id}` をポーリングします。完成した素材は `data.output.media` から取得します。 ## エラー | ステータスコード | 意味と対処方法 | | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | JSON の形式が不正、またはフィールド・値・組み合わせが未対応です（`bad_request`。メッセージにフィールド名が記載されます）。入力がコンテンツ審査で拒否された場合は `content_policy_violation` です。修正せずに再試行しても成功しません。 | | `401` | API キーが未指定（`missing_api_key`）、またはキーが不正・期限切れ・無効・上限到達です（`invalid_api_key`。理由はメッセージに記載されます）。`Authorization: Bearer ` で送信してください。`sk-` 接頭辞の有無にかかわらず使えます。そのまま再試行しないでください。 | | `402` | 残高不足です（`insufficient_credits`）。残高がゼロ、またはこのリクエストの料金に足りません。残高をチャージしてから再度送信してください。それまでは再試行しないでください。 | | `403` | キーまたはアカウントに、この呼び出しの権限がありません（`forbidden`）。例として、無料クレジットでは利用できないモデル（チャージすると利用可能）、キーの IP 許可リスト外からのリクエスト、キーのグループに含まれないモデルがあります。そのまま再試行しないでください。 | | `409` | `Idempotency-Key` が別のリクエストボディで使用済み、または同じキーの最初のリクエストが処理中です（`idempotency_conflict`）。そのまま再試行しないでください。 | | `429` | 同時処理中のタスクが多すぎます（`user_concurrency_exceeded`）、またはリクエスト数が上限を超えています（`rate_limit_exceeded`）。処理中のタスクが完了した後、または `Retry-After` の秒数だけ待った後に再試行できます。 | | `500` | 予期しない内部エラーです（`internal_error`）。再試行できます。繰り返し発生する場合は、`request_id` を控えてサポートに連絡してください。 | | `503` | リクエストを完了できませんでした（`processing_unavailable`、`processing_timeout`、`processing_failed`、`result_transfer_failed`）。課金されていません。待機時間を段階的に延ばして再試行できます。待機時間が判明している場合は `Retry-After` が返されます。BeatAPI は 502 や 504 を返しません。 |