ミュージックビデオ

POST https://api.beatapi.io/v1/music-video/tasks

画像、音声、制作設定を指定して、ミュージックビデオのワークフロータスクを作成します。

認証

Authorization   string   必須

BeatAPI の API キーを Bearer トークンとして送信します。API キーはダッシュボードで作成できます。

Authorization: Bearer <BEATAPI_API_KEY>

通常の API キーは、信頼できるサーバーで管理してください。リクエストボディには Content-Type: application/json が必要です。対応するエンドポイントでは Idempotency-Key は任意ですが、同一のリクエストボディで安全に再試行するために指定を推奨します。

リクエストボディ

mv_tier   enum<string>   任意

ミュージックビデオのプランを選択します。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<string>   任意

Standard ワークフローの台詞と歌詞に使用する言語です。

選択肢: en, zh

quality   enum<string>   任意

生成品質の区分です。540p では high を利用できません。

選択肢: standard, high
デフォルト値: "standard"

style   string   任意

映画風、アニメ風、ドキュメンタリー風、ファッション誌風など、視覚的なスタイルを簡潔に指定します。任意です。

文字数: 最大 200 文字

aspect_ratio   enum<string>   任意

出力先の表示形式です。掲載先のプレーヤーや SNS フィードに合わせて、明示的に指定してください。

選択肢: 1:1, 16:9, 9:16, 4:3, 3:4

resolution   enum<string>   任意

トップレベルに指定する出力解像度です。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<string>   任意

auto は最終ミュージックビデオを自動で合成します。manual は requires_action で一時停止し、合成前にショットを確認・編集できます。

選択肢: auto, manual
デフォルト値: "auto"

mv_mode   enum<string>   任意

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 が返されます。

{
  "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 から取得します。

エラー