ナビゲーションにスキップ
BeatAPIKling 3Video API

Kling 3.0

テキスト、または 1～2 枚のフレームから、std または pro 区分の 3～15 秒の動画を生成します。マルチショットのストーリーボードと再利用できるエレメントに対応し、料金は秒単位です。

  • 非同期です。作成の呼び出しはタスク ID を返し、動画はタスクが成功した時点で得られます。
  • 入力方法は 3 通りです。テキストのみ、開始フレーム、または開始フレームと終了フレームです。このモデルは参照画像、参照動画、音声を受け付けません。
  • resolution は区分です。std は 720p、pro（デフォルト）は 1080p でレンダリングされます。
  • マルチショット：1 枚の開始フレーム画像から、最大 5 つのショットを作れます。各ショットには、それぞれのプロンプトと長さがあります。ショットの長さの合計は duration と一致する必要があります。
  • エレメント：elements で、名前を付けた被写体を最大 3 つまで一度だけ定義できます。
  • 料金は、選んだ区分での動画の秒数に応じて決まります。失敗したタスクには課金されません。
POST/v1/videos/tasks試してみる

このモデルをテスト画面で開きます。BeatAPI の API キーを入力するとタスクを作成できます。実際に呼び出され、ご自身の残高から課金されます。

エンドポイントと認証

POST https://api.beatapi.io/v1/videos/tasks

Authorization string 必須

BeatAPI の API キーを Bearer <BEATAPI_API_KEY> の形式で送信します。キーはダッシュボードで作成できます。キーはサーバー側で保管し、ブラウザーやモバイルアプリに含めないでください。

ボディは JSON で送信し、Content-Type: application/json を指定します。Idempotency-Key は任意です。論理的に 1 件のリクエストごとに一意の値（255 文字以内）を送り、まったく同じボディを再試行するときだけ再利用してください。24 時間以内に同じキーと同じボディで再試行すると、最初のレスポンスが Idempotent-Replayed: true 付きで再度返されます。同じキーで異なるボディを送ると 409 idempotency_conflict が返ります。2xx 以外のレスポンスは保存されないため、400 や 402 の後の再試行は改めて実行されます。

リクエストの流れ

1

タスクを作成する

下記のパラメーターをエンドポイントに POST します。201 が返れば、タスクが受け付けられ、料金が残高から仮確保されたことを意味します。処理はバックグラウンドで実行されます。data.id を保存してください。

2

完了を待つ

GET /v1/tasks/{task_id} を呼び出し、status が succeeded または failed になるまで、呼び出しの間隔を data.poll_after_seconds（画像は 5 秒、動画は 8 秒）だけ空けてください。あるいは task.succeeded と task.failed のWebhookを登録することもできます。処理タイムアウトで停止したタスクはイベントを送信しないため、フォールバックとしてポーリングも続けてください。

3

結果を保存する

succeeded の場合は、すべての data.output.media[].url をダウンロードし、必要なファイルを保存してください。結果 URL がいつまで利用できるかは保証されません。failed の場合は、data.error_code と data.error_message を確認してください。仮確保された金額は残高に戻されます。data.retryable は、同じリクエストをもう一度送れば成功する可能性があるかどうかを示します。

入力モード

モード必須の入力備考
テキストから動画model、promptimages は送らないでください。
開始フレームmodel、prompt、images（リンク 1 個）動画はその画像から始まります。
開始フレームと終了フレームmodel、prompt、images（リンク 2 個）images[0] が開始フレーム、images[1] が終了フレームです。
マルチショットmodel、prompt、images（リンクちょうど 1 個）、multi_shots: true、multi_promptショットの長さの合計は duration と一致する必要があります（省略すると 5）。
エレメントmodel、prompt、elements上記のどのモードとも組み合わせられます。エレメントは最大 3 つです。

リクエストパラメーター

model string 必須

実行するモデルです。

値：kling-v3

値が正しくない場合

  • 指定がない場合："model" is required
  • 画像モデルをこのエンドポイントに送った場合："model" nano-banana-2 is served by POST /v1/images/tasks, not this endpoint

prompt string 必須

動画の中で起きること（被写体、動き、カメラワーク、スタイル）です。

長さ：1–5000 文字

  • 長さは文字数で数えます（CJK 文字も 1 文字として数えます）。
  • マルチショットを含め、すべてのモードで必須です。マルチショットでは、各ショットにも multi_prompt の中に専用のプロンプトがあります。

値が正しくない場合

  • 指定がない場合："prompt" is required
  • 空、または上限を超える長さの場合："prompt" has an unsupported length

images string[] 任意

開始フレーム、または開始フレームと終了フレームです。

要素数：1–2
各要素は公開されている https:// の URL です。ローカルファイルは先に アップロード（POST /v1/files）し、返された data.url を渡してください。

  • リンク 1 個の場合は、動画がその画像から始まります。リンク 2 個の場合は、images[0] が開始フレーム、images[1] が終了フレームです。
  • マルチショット（multi_shots: true）では、画像はちょうど 1 枚です。
  • このモデルには参照画像のフィールドがありません。被写体の画像は elements に入れます。

値が正しくない場合

  • リンクが 3 個以上の場合："images" accepts at most 2 items
  • 空の配列の場合："images" requires at least 1 item
  • https:// のリンクではない場合："images[0]" must be a public HTTPS URL
  • multi_shots: true で画像がない、または 2 枚ある場合：Kling V3 multi-shot mode requires exactly one image

duration integer 任意デフォルト: 5

動画の長さです。単位は秒で、整数で指定します。料金はこの値に基づきます。

デフォルト：5
範囲：3–15

  • 省略すると 5 が使われ、その秒数で課金されます。
  • multi_shots: true の場合、multi_prompt 内の各ショットの duration の合計が、この値とちょうど一致する必要があります。duration を省略した場合は、合計が 5 になる必要があります。

値が正しくない場合

  • 範囲外、整数ではない、または文字列として送った場合："duration" is outside its supported range
  • マルチショットの長さの合計が duration と一致しない場合：Kling V3 shot durations must sum to duration

aspect_ratio string 任意デフォルト: 16:9

動画の形（幅:高さ）です。

指定できる値：16:9, 9:16, 1:1
デフォルト：16:9

  • デフォルトは 16:9 です。

値が正しくない場合

  • 一覧にない値の場合："aspect_ratio" must be one of: [16:9 9:16 1:1]

resolution string 任意デフォルト: pro

画質の区分です。std は 720p、pro は 1080p でレンダリングされます。pro は 1 秒あたりの料金が高くなります。指定する値は std と pro で、ピクセル数ではありません。

指定できる値：std, pro
デフォルト：pro

  • 省略すると pro が使われ、その区分で課金されます。
  • 4K、720p、1080p は受け付けません。std または pro を送ってください。

値が正しくない場合

  • 一覧にない値の場合（たとえば 720p や 4K）："resolution" must be one of: [std pro]

sound boolean 任意

動画に、生成されたサウンドトラックを付けるかどうかです。

  • 省略すると、音声は multi_shots に従います。マルチショットのリクエストではオン、それ以外ではオフです。自分で決める場合は true または false を送ります。

値が正しくない場合

  • true でも false でもない場合："sound" must be a boolean

multi_shots boolean 任意デフォルト: false

ストーリーボードモードをオンにします。動画は multi_prompt に並べたショットで構成されます。デフォルトは false です。

デフォルト：false

  • images にちょうど 1 枚の画像が必要で、multi_prompt のショットの長さの合計が duration と一致する必要があります。multi_shots: true がない場合、multi_prompt は拒否されます。
  • 確認は次の順で行われます。画像が 1 枚であること、次に multi_prompt があること、最後に長さです。

値が正しくない場合

  • true でも false でもない場合："multi_shots" must be a boolean
  • 画像がない、または 2 枚以上ある場合：Kling V3 multi-shot mode requires exactly one image
  • multi_prompt がない場合：Kling V3 multi-shot mode requires multi_prompt
  • ショットの長さの合計が duration と一致しない場合：Kling V3 shot durations must sum to duration

multi_prompt object[] 任意

マルチショット動画のショットを順番に並べたものです。1～5 個のオブジェクトで、それぞれに専用のプロンプトと長さがあります。

要素数：1–5

  • 各ショットは 2 つの必須フィールドを持つオブジェクトで、それ以外は受け付けません。
  • multi_prompt[].prompt（文字列、必須）：このショットで起きること。1～500 文字です。
  • multi_prompt[].duration（整数、必須）：このショットの長さ。整数秒で、1～12 です。
  • ショットの長さの合計は、リクエストの duration（duration を省略した場合は 5）と一致する必要があり、その合計は最大 15 です。
  • multi_shots: true の場合のみ有効です。

値が正しくない場合

  • multi_shots: true なしで送った場合："multi_prompt" requires multi_shots=true
  • ショットが 6 個以上の場合："multi_prompt" accepts at most 5 items
  • 空の配列の場合："multi_prompt" requires at least 1 item
  • ショットに prompt がない場合："prompt" is required in "multi_prompt[0]"
  • ショットに duration がない場合："duration" is required in "multi_prompt[0]"
  • ショットのプロンプトが空、または 500 文字を超える場合："multi_prompt[0].prompt" has an unsupported length
  • ショットの長さが 1～12 の範囲外、または整数ではない場合："multi_prompt[0].duration" is outside its supported range
  • prompt と duration 以外のキーがある場合：field "name" is not supported in "multi_prompt[0]"
  • ショットの長さの合計が duration と一致しない場合：Kling V3 shot durations must sum to duration

elements object[] 任意

名前を付けた被写体（キャラクター、商品、小道具）を最大 3 つまで、画像を使って一度だけ定義します。

要素数：≤ 3

  • 最大 3 個のオブジェクトの配列です。各オブジェクトは次のキーのみ受け付けます。
  • elements[].name（文字列、必須）：エレメントの名前。1 文字以上です。
  • elements[].description（文字列、任意）：そのエレメントが何であるか。省略すると、name が説明として使われます。
  • elements[].element_input_urls（文字列の配列、必須）：そのエレメントを写した公開 HTTPS リンクを 1～4 個です。
  • elements[].element_input_audio_urls（文字列の配列、任意）：そのエレメントの公開 HTTPS 音声リンクをちょうど 1 個です。
  • elements[].start_time と elements[].end_time（整数、任意）：時間をミリ秒で指定します。それぞれ 0～30000 の整数です。両方を送るか、どちらも送らないかのいずれかにします。end_time は start_time より大きく、end_time - start_time は 3000～8000（3～8 秒）である必要があります。
  • リンクの上限は、各エレメントごとに適用されます。すべてのエントリが、それぞれ 4 個のリンクと 1 個の音声リンクを持てます。

値が正しくない場合

  • エレメントが 4 個以上の場合："elements" accepts at most 3 items
  • エレメントがオブジェクトではない場合："elements[0]" must be an object
  • エレメントに name がない場合："name" is required in "elements[0]"
  • エレメントに element_input_urls がない場合："element_input_urls" is required in "elements[0]"
  • name が空の場合："elements[0].name" has an unsupported length
  • リンクが 5 個以上の場合："elements[0].element_input_urls" accepts at most 4 items
  • element_input_urls が空の配列の場合："elements[0].element_input_urls" requires at least 1 item
  • リンクが https:// ではない場合："elements[0].element_input_urls[1]" must be a public HTTPS URL
  • 音声リンクが 2 個以上の場合："elements[0].element_input_audio_urls" accepts at most 1 items
  • start_time または end_time が 0～30000 の範囲外、または整数ではない場合："elements[0].start_time" is outside its supported range
  • エレメントが受け付けないキーがある場合：field "color" is not supported in "elements[0]"
  • start_time と end_time の片方だけを送った、end_time が start_time より後ではない、または区間が 3 秒より短い、もしくは 8 秒より長い場合：Kling V3 element segment must provide a 3-8 second start_time/end_time range

入力メディアの上限

ゲートウェイはタスク作成前にすべての入力を読み取り、次の上限を超えるものは、その入力を示す 400 bad_request で拒否します。課金はされません。

  • ゲートウェイは、タスクを作成する前に、各画像、エレメントのリンク、音声リンクが公開 HTTPS リンクであることだけを確認します。サイズ、形式、寸法は確認しないため、モデルが使えない入力は送信後にタスクが失敗します。そのメッセージには変更すべき点が示され、予約された金額は全額返却されます。
  • ローカルのファイルしかない場合は、POST /v1/files でアップロードし、返された data.url を渡してください。

マルチショットのルール

タスクの作成時に、次の順で確認されます。ルールに反するリクエストは 400 bad_request で拒否され、課金されません。

ルールメッセージ
multi_prompt を送ったが、multi_shots が true ではない"multi_prompt" requires multi_shots=true
multi_shots: true だが、images の画像がちょうど 1 枚ではないKling V3 multi-shot mode requires exactly one image
multi_shots: true だが multi_prompt がないKling V3 multi-shot mode requires multi_prompt
ショットの長さの合計が duration（省略すると 5）と一致しないKling V3 shot durations must sum to duration
  • テキストのみのマルチショットは使えません。マルチショット動画は、必ず 1 枚の画像から始まります。
  • マルチショットのリクエストは duration 秒分で課金されます。これはショットの長さの合計です。

このモデルが受け付けないフィールド

次のフィールドを送ると、無視されるのではなく、課金される前に拒否されます。

  • reference_images、reference_videos、reference_audios、generate_audio、seed、quality、watermark、task_type、output_format → field "reference_images" is not supported by model kling-v3（送ったフィールド名が入ります）。
  • その他の未知のフィールド → unknown field: <name>。

リクエスト例

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v3",
  "prompt": "A dramatic product reveal of a glass water bottle, slow orbiting camera, soft studio reflections",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "pro",
  "sound": true
}'

テキストから動画

pro 区分（1080p）で、音声付きの 5 秒のクリップです。

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v3",
  "prompt": "A dramatic product reveal of a glass water bottle, slow orbiting camera, soft studio reflections",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "pro",
  "sound": true
}'

開始フレーム

動画はその画像から始まります。

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v3",
  "prompt": "The bottle slowly rotates on its pedestal while reflections move across the glass",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png"
  ],
  "duration": 5,
  "resolution": "pro",
  "sound": true
}'

開始フレームと終了フレーム

動画は 1 枚目の画像から 2 枚目の画像へ動きます。より安い std 区分（720p）を使っています。

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v3",
  "prompt": "The camera moves from the bottle on the table to the singer on a neon stage in one continuous shot",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png",
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "duration": 5,
  "resolution": "std"
}'

マルチショット

1 枚の開始フレーム画像から作る、3 秒のショット 2 つです。ショットの長さ（3 + 3）が duration（6）と一致しています。

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v3",
  "prompt": "A two-shot cinematic product reveal",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png"
  ],
  "duration": 6,
  "aspect_ratio": "16:9",
  "resolution": "pro",
  "sound": true,
  "multi_shots": true,
  "multi_prompt": [
    {
      "prompt": "Macro detail shot of the bottle with moving reflections",
      "duration": 3
    },
    {
      "prompt": "Wide hero reveal of the bottle on a dark pedestal",
      "duration": 3
    }
  ]
}'

再利用できるエレメント

2 枚の画像から、名前付きのエレメントを 1 つ定義します。エレメントの名前は product で、説明は任意です。

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v3",
  "prompt": "A slow cinematic camera orbit around the product",
  "duration": 5,
  "resolution": "pro",
  "elements": [
    {
      "name": "product",
      "description": "The featured water bottle",
      "element_input_urls": [
        "https://cdn.beatapi.io/samples/smart-bottle.png",
        "https://cdn.beatapi.io/samples/neon-singer.png"
      ]
    }
  ]
}'

レスポンス

タスクの作成（201）

タスクオブジェクトです。タスクが成功するまで output は null です。「実行中」と記載されたフィールドは、タスクの完了後に表示されなくなります。

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "kling-v3",
    "capability_version": 1,
    "media_type": "video",
    "model": "kling-v3",
    "status": "queued",
    "stage": "queued",
    "created_at": 1791993600,
    "updated_at": 1791993600,
    "completed_at": null,
    "poll_after_seconds": 8,
    "output": null,
    "usage": {
      "credits_reserved": 0.65,
      "credits_settled": 0,
      "credits_refunded": 0,
      "credits_charged": 0.65,
      "billable_duration_seconds": 5
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}
フィールド型説明
data.idstringタスク ID です。task_ の後に英数字 32 文字が続きます。ポーリングや Webhook イベントとの照合に使います。
data.objectstring常に task です。
data.task_kindstringimage または video です。
data.capability_idstring送信したモデル ID です。
data.capability_versionintegerモデルの仕様バージョンです。現在は 1 です。
data.media_typestringimage または video です。
data.modelstring送信したモデル ID です（capability_id と同じ）。
data.statusstringqueued、processing、succeeded、failed のいずれかです。最終状態は後ろの 2 つだけです。
data.stagestringstatus と同じ値です。古いクライアント向けに残されています。
data.created_atintegerタスクの作成日時（Unix 秒）です。
data.updated_atinteger最終更新日時（Unix 秒）です。
data.completed_atinteger | nullタスクの完了日時（Unix 秒）です。実行中は null です。
data.poll_after_secondsinteger実行中のみ。次のポーリングまでに待つ秒数です（画像は 5、動画は 8）。
data.typical_secondsobject実行中のみ、直近のタスクが十分にある場合に含まれます。直近 window の samples 件のタスクについて、完了までの時間（秒）の p50 と p90 を示します。
data.outputobject | null結果です。status が succeeded になるまでは null です。下の出力フィールドを参照してください。
data.usage.credits_reservednumberタスク作成時に残高から仮確保された金額（USD）です。
data.usage.credits_chargednumberこのタスクの料金（USD）です。失敗したタスクでは 0 です。
data.usage.credits_settlednumber最終的に差し引かれた金額（USD）です。タスクが成功した時点で設定され、それ以外では 0 です。
data.usage.credits_refundednumber残高に戻された金額（USD）です。失敗したタスクでは、返金が記録された時点で仮確保した金額と一致します。
data.usage.billable_duration_secondsinteger動画のみ。料金の算定に使われた秒数です。モデルが長さを報告しない場合は含まれません。
data.request_idstringリクエスト ID です。サポートに問い合わせる際に添えてください。
data.error_codestring | null失敗コードです。タスクが失敗した場合以外は null です。
data.error_messagestring | null何が問題で、何を変更すればよいかを示します。タスクが失敗した場合以外は null です。

完了したタスク

GET /v1/tasks/{task_id} は HTTP 200 と status: "succeeded" を返し、結果は data.output に入ります。

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "kling-v3",
    "capability_version": 1,
    "media_type": "video",
    "model": "kling-v3",
    "status": "succeeded",
    "stage": "succeeded",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": {
      "media": [
        {
          "type": "video",
          "url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4",
          "mime_type": "video/mp4"
        }
      ],
      "r2_url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4"
    },
    "usage": {
      "credits_reserved": 0.65,
      "credits_settled": 0.65,
      "credits_refunded": 0,
      "credits_charged": 0.65,
      "billable_duration_seconds": 5
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

出力フィールド

フィールド型説明
output.mediaobject[]生成されたファイルです。このモデルでは動画が 1 本です。
output.media[].typestring常に video です。
output.media[].urlstring保存された動画への HTTPS リンクです。ダウンロードして保管してください。保持期間は保証されません。
output.media[].mime_typestringファイルのメディアタイプです。通常は video/mp4 です。
output.r2_urlstring古いクライアント向けに、動画の URL を再掲したものです。代わりに media を読んでください。

失敗したタスク

失敗したタスクも、GET /v1/tasks/{task_id} では HTTP 200 になります。失敗はボディに示されます。仮確保された金額は全額戻されるため、課金されません。

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "kling-v3",
    "capability_version": 1,
    "media_type": "video",
    "model": "kling-v3",
    "status": "failed",
    "stage": "failed",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": null,
    "usage": {
      "credits_reserved": 0.65,
      "credits_settled": 0,
      "credits_refunded": 0.65,
      "credits_charged": 0,
      "billable_duration_seconds": 5
    },
    "retryable": true,
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": "processing_failed",
    "error_message": "The task failed during processing on our side. Retry; a failed task is refunded."
  }
}
フィールド型説明
data.error_codestringbad_request と content_policy_violation（リクエストを修正してください）、または processing_unavailable、processing_timeout、processing_failed、result_transfer_failed（時間をおいて再試行してください）のいずれかです。エラーを参照してください。
data.error_messagestring問題と対処方法を示す文です。
data.retryableboolean失敗したタスクにのみ含まれます。同じリクエストをもう一度送れば成功する可能性がある場合は true です。
data.usageobject返金が記録された時点（通常はタスクが失敗した瞬間）で、credits_charged と credits_settled は 0 になり、credits_refunded は credits_reserved と一致します。

完全なコード例

タスクを作成し、サーバーが示すポーリング間隔で完了を待ち、結果の URL を出力します。環境変数に BEATAPI_API_KEY を設定し、requests をインストールしてください。

import os
import time
import uuid
import requests
API = "https://api.beatapi.io"
HEADERS = {"Authorization": f"Bearer {os.environ['BEATAPI_API_KEY']}"}
def create_task(body: dict) -> dict:
    # One Idempotency-Key per logical request: a retry with the same key cannot create a second task.
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
    for attempt in range(3):
        response = requests.post(f"{API}/v1/videos/tasks", headers=headers, json=body, timeout=60)
        if response.status_code in (429, 503) and attempt < 2:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        break
    try:
        payload = response.json()
    except ValueError:  # an edge error page is not JSON
        response.raise_for_status()
        raise
    if not response.ok:
        error = payload["error"]
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']} (request_id={error.get('request_id')})")
    return payload["data"]
def wait_for_task(task_id: str, timeout_seconds: int = 1800) -> dict:
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        response = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        if response.status_code == 429 or response.status_code >= 500:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        response.raise_for_status()
        task = response.json()["data"]
        if task["status"] in ("succeeded", "failed"):
            return task
        time.sleep(task.get("poll_after_seconds", 5))
    raise TimeoutError(f"task {task_id} is still running; keep polling later")
task = create_task({
  "model": "kling-v3",
  "prompt": "A dramatic product reveal of a glass water bottle, slow orbiting camera, soft studio reflections",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "pro",
  "sound": True
})
print("created", task["id"])
task = wait_for_task(task["id"])
if task["status"] == "failed":
    raise SystemExit(f"{task['error_code']}: {task['error_message']}")
for item in task["output"]["media"]:
    print(item["url"])

課金

  • sound は料金に影響しません。料金は duration と resolution だけで決まるため、音声の有無にかかわらず料金表の行がそのまま適用されます。
  • 料金は、選んだ区分での動画の秒数に応じて決まります。下の一覧は 8 秒のクリップの料金なので、8 で割ると 1 秒あたりの単価になります（std で約 0.11/秒、‘pro‘で0.11 / 秒、`pro` で 0.13）。
  • 秒数は duration で、省略すると 5 です。マルチショットのリクエストではショットの長さの合計で、これは duration と一致します。タスクの usage.billable_duration_seconds に表示されます。
  • 料金はタスクの作成時に予約され、動画の完成時に確定します。失敗したタスク（送信後にモデレーションで拒否されたものを含む）は全額返金されます。

よくあるエラー

エラーまたは症状原因対処
400 "resolution" must be one of: [std pro]720p、1080p、4K のようなピクセルサイズを送っています。このモデルが受け付けるのは区分です。std（720p でレンダリング）または pro（1080p でレンダリング）を送ってください。
400 Kling V3 multi-shot mode requires exactly one imagemulti_shots: true で、画像がない、または 2 枚あります。images に画像を 1 枚送ってください。テキストのみのマルチショットはありません。
400 Kling V3 shot durations must sum to durationmulti_prompt の長さの合計が duration と一致しません。duration を省略した場合は、5 と一致しません。ショットの長さの合計を duration とちょうど一致させてください。たとえば duration: 6 なら 3 + 3 です。
400 "multi_prompt" requires multi_shots=truemulti_shots: true なしで multi_prompt を送っています。multi_shots: true を追加するか、multi_prompt を削除してください。
400 Kling V3 multi-shot mode requires multi_promptmulti_shots: true ですが、multi_prompt がありません。1～5 個のショットを含む multi_prompt を追加してください。
400 Kling V3 element segment must provide a 3-8 second start_time/end_time rangeエレメントに start_time と end_time の片方しかない、end_time が start_time より後ではない、または区間が 3 秒より短い、もしくは 8 秒より長いです。どちらもミリ秒で指定します。両方をミリ秒で送り、end_time - start_time が 3000～8000 になるようにしてください。
400 "elements[0].element_input_urls" accepts at most 4 items1 つのエレメントに 5 個以上のリンクがあります。1 つのエレメントにつきリンクは 4 個までにしてください。被写体は別のエレメントに分けます（最大 3 つ）。
400 field "reference_images" is not supported by model kling-v3このモデルには参照用のフィールドがありません（generate_audio、seed、quality も同様です）。そのフィールドを削除してください。被写体の画像は elements に入れます。
400 "duration" is outside its supported range3～15 の整数ではない、または文字列として送っています。5 のような整数を送ってください。
タスクが failed になり、content_policy_violation が返るプロンプト、入力画像、または生成結果がモデレーションで拒否されました。プロンプトまたは画像を変更してください。そのまま再試行しても再び失敗します。課金はされません。
402 insufficient_credits残高が、この長さと区分の予約額を下回っています。チャージするか、duration を短くするか、std を使ってください。

HTTP エラー早見表

タスクが作られる前のエラーは、2xx 以外のレスポンスで返されます。課金はされません。error.code または error.retryable で処理を分岐してください。message には問題の内容が示されます。全一覧と再試行のルールはエラーにあります。

{
  "error": {
    "code": "bad_request",
    "message": "\"prompt\" is required",
    "retryable": false,
    "request_id": "req_5f0c2a9e4b7d4e31"
  }
}
HTTP ステータスerror.code対処方法
400bad_request, content_policy_violationリクエストを修正してください。メッセージにフィールド名が示されます。そのまま再試行しないでください。
401missing_api_key, invalid_api_key（古いクライアントでは unauthorized が返ることがあります）有効なキーを Authorization: Bearer <key> で送信してください。
402insufficient_credits残高をチャージするか、キーのクォータを引き上げてから、再度送信してください。
403forbiddenこのキーまたはアカウントでは、このモデルを利用できない可能性があります（たとえば、無料クレジットは一部のモデルにのみ使えます）。そのまま再試行しないでください。
404not_foundGET /v1/tasks/{task_id} の場合：このキーのアカウントに該当するタスクが存在しません。ID を確認してください。
409idempotency_conflict新しい Idempotency-Key を使うか、同じキーの最初のリクエストが完了するまで待ってください。
429rate_limit_exceededRetry-After の秒数（error.retry_after_seconds にも含まれます）だけ待ってから再試行してください。
500internal_errorバックオフを入れて再試行してください。解消しない場合は、request_id を添えてサポートにお問い合わせください。
503processing_unavailable, processing_timeout, processing_failed, result_transfer_failed課金はされていません。指数バックオフで再試行してください。

認証

AuthorizationBearer

Send your API key as Authorization: Bearer <BEATAPI_API_KEY>.

ヘッダー

Idempotency-Keystringオプション<=255 characters

ボディは JSON で送信し、Content-Type: application/json を指定します。Idempotency-Key は任意です。論理的に 1 件のリクエストごとに一意の値（255 文字以内）を送り、まったく同じボディを再試行するときだけ再利用してください。24 時間以内に同じキーと同じボディで再試行すると、最初のレスポンスが Idempotent-Replayed: true 付きで再度返されます。同じキーで異なるボディを送ると 409 idempotency_conflict が返ります。2xx 以外のレスポンスは保存されないため、400 や 402 の後の再試行は改めて実行されます。

リクエスト

This endpoint expects an object.
modelenum必須

実行するモデルです。

値：kling-v3

値が正しくない場合

  • 指定がない場合："model" is required
  • 画像モデルをこのエンドポイントに送った場合："model" nano-banana-2 is served by POST /v1/images/tasks, not this endpoint
許可された値:
promptstring必須1-5000 characters

動画の中で起きること（被写体、動き、カメラワーク、スタイル）です。

長さ：1–5000 文字

  • 長さは文字数で数えます（CJK 文字も 1 文字として数えます）。
  • マルチショットを含め、すべてのモードで必須です。マルチショットでは、各ショットにも multi_prompt の中に専用のプロンプトがあります。

値が正しくない場合

  • 指定がない場合："prompt" is required
  • 空、または上限を超える長さの場合："prompt" has an unsupported length
aspect_ratioenumオプションデフォルト値 16:9

動画の形（幅:高さ）です。

指定できる値：16:9, 9:16, 1:1

デフォルト：16:9

  • デフォルトは 16:9 です。

値が正しくない場合

  • 一覧にない値の場合："aspect_ratio" must be one of: [16:9 9:16 1:1]
許可された値:
durationintegerオプション3-15デフォルト値 5

動画の長さです。単位は秒で、整数で指定します。料金はこの値に基づきます。

デフォルト：5

範囲：3–15

  • 省略すると 5 が使われ、その秒数で課金されます。
  • multi_shots: true の場合、multi_prompt 内の各ショットの duration の合計が、この値とちょうど一致する必要があります。duration を省略した場合は、合計が 5 になる必要があります。

値が正しくない場合

  • 範囲外、整数ではない、または文字列として送った場合："duration" is outside its supported range
  • マルチショットの長さの合計が duration と一致しない場合：Kling V3 shot durations must sum to duration
elementslist of objectsオプション

名前を付けた被写体（キャラクター、商品、小道具）を最大 3 つまで、画像を使って一度だけ定義します。

要素数：≤ 3

  • 最大 3 個のオブジェクトの配列です。各オブジェクトは次のキーのみ受け付けます。
  • elements[].name（文字列、必須）：エレメントの名前。1 文字以上です。
  • elements[].description（文字列、任意）：そのエレメントが何であるか。省略すると、name が説明として使われます。
  • elements[].element_input_urls（文字列の配列、必須）：そのエレメントを写した公開 HTTPS リンクを 1～4 個です。
  • elements[].element_input_audio_urls（文字列の配列、任意）：そのエレメントの公開 HTTPS 音声リンクをちょうど 1 個です。
  • elements[].start_time と elements[].end_time（整数、任意）：時間をミリ秒で指定します。それぞれ 0～30000 の整数です。両方を送るか、どちらも送らないかのいずれかにします。end_time は start_time より大きく、end_time - start_time は 3000～8000（3～8 秒）である必要があります。
  • リンクの上限は、各エレメントごとに適用されます。すべてのエントリが、それぞれ 4 個のリンクと 1 個の音声リンクを持てます。

値が正しくない場合

  • エレメントが 4 個以上の場合："elements" accepts at most 3 items
  • エレメントがオブジェクトではない場合："elements[0]" must be an object
  • エレメントに name がない場合："name" is required in "elements[0]"
  • エレメントに element_input_urls がない場合："element_input_urls" is required in "elements[0]"
  • name が空の場合："elements[0].name" has an unsupported length
  • リンクが 5 個以上の場合："elements[0].element_input_urls" accepts at most 4 items
  • element_input_urls が空の配列の場合："elements[0].element_input_urls" requires at least 1 item
  • リンクが https:// ではない場合："elements[0].element_input_urls[1]" must be a public HTTPS URL
  • 音声リンクが 2 個以上の場合："elements[0].element_input_audio_urls" accepts at most 1 items
  • start_time または end_time が 0～30000 の範囲外、または整数ではない場合："elements[0].start_time" is outside its supported range
  • エレメントが受け付けないキーがある場合：field "color" is not supported in "elements[0]"
  • start_time と end_time の片方だけを送った、end_time が start_time より後ではない、または区間が 3 秒より短い、もしくは 8 秒より長い場合：Kling V3 element segment must provide a 3-8 second start_time/end_time range
imageslist of stringsオプション

開始フレーム、または開始フレームと終了フレームです。

要素数：1–2

各要素は公開されている https:// の URL です。ローカルファイルは先に アップロード（POST /v1/files）し、返された data.url を渡してください。

  • リンク 1 個の場合は、動画がその画像から始まります。リンク 2 個の場合は、images[0] が開始フレーム、images[1] が終了フレームです。
  • マルチショット（multi_shots: true）では、画像はちょうど 1 枚です。
  • このモデルには参照画像のフィールドがありません。被写体の画像は elements に入れます。

値が正しくない場合

  • リンクが 3 個以上の場合："images" accepts at most 2 items
  • 空の配列の場合："images" requires at least 1 item
  • https:// のリンクではない場合："images[0]" must be a public HTTPS URL
  • multi_shots: true で画像がない、または 2 枚ある場合：Kling V3 multi-shot mode requires exactly one image
multi_promptlist of objectsオプション

マルチショット動画のショットを順番に並べたものです。1～5 個のオブジェクトで、それぞれに専用のプロンプトと長さがあります。

要素数：1–5

  • 各ショットは 2 つの必須フィールドを持つオブジェクトで、それ以外は受け付けません。
  • multi_prompt[].prompt（文字列、必須）：このショットで起きること。1～500 文字です。
  • multi_prompt[].duration（整数、必須）：このショットの長さ。整数秒で、1～12 です。
  • ショットの長さの合計は、リクエストの duration（duration を省略した場合は 5）と一致する必要があり、その合計は最大 15 です。
  • multi_shots: true の場合のみ有効です。

値が正しくない場合

  • multi_shots: true なしで送った場合："multi_prompt" requires multi_shots=true
  • ショットが 6 個以上の場合："multi_prompt" accepts at most 5 items
  • 空の配列の場合："multi_prompt" requires at least 1 item
  • ショットに prompt がない場合："prompt" is required in "multi_prompt[0]"
  • ショットに duration がない場合："duration" is required in "multi_prompt[0]"
  • ショットのプロンプトが空、または 500 文字を超える場合："multi_prompt[0].prompt" has an unsupported length
  • ショットの長さが 1～12 の範囲外、または整数ではない場合："multi_prompt[0].duration" is outside its supported range
  • prompt と duration 以外のキーがある場合：field "name" is not supported in "multi_prompt[0]"
  • ショットの長さの合計が duration と一致しない場合：Kling V3 shot durations must sum to duration
multi_shotsbooleanオプションデフォルト値 false

ストーリーボードモードをオンにします。動画は multi_prompt に並べたショットで構成されます。デフォルトは false です。

デフォルト：false

  • images にちょうど 1 枚の画像が必要で、multi_prompt のショットの長さの合計が duration と一致する必要があります。multi_shots: true がない場合、multi_prompt は拒否されます。
  • 確認は次の順で行われます。画像が 1 枚であること、次に multi_prompt があること、最後に長さです。

値が正しくない場合

  • true でも false でもない場合："multi_shots" must be a boolean
  • 画像がない、または 2 枚以上ある場合：Kling V3 multi-shot mode requires exactly one image
  • multi_prompt がない場合：Kling V3 multi-shot mode requires multi_prompt
  • ショットの長さの合計が duration と一致しない場合：Kling V3 shot durations must sum to duration
resolutionenumオプションデフォルト値 pro

画質の区分です。std は 720p、pro は 1080p でレンダリングされます。pro は 1 秒あたりの料金が高くなります。指定する値は std と pro で、ピクセル数ではありません。

指定できる値：std, pro

デフォルト：pro

  • 省略すると pro が使われ、その区分で課金されます。
  • 4K、720p、1080p は受け付けません。std または pro を送ってください。

値が正しくない場合

  • 一覧にない値の場合（たとえば 720p や 4K）："resolution" must be one of: [std pro]
許可された値:
soundbooleanオプション

動画に、生成されたサウンドトラックを付けるかどうかです。

  • 省略すると、音声は multi_shots に従います。マルチショットのリクエストではオン、それ以外ではオフです。自分で決める場合は true または false を送ります。

値が正しくない場合

  • true でも false でもない場合："sound" must be a boolean

レスポンス

タスクオブジェクトです。タスクが成功するまで output は null です。「実行中」と記載されたフィールドは、タスクの完了後に表示されなくなります。

エラー

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error