Kling 3

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

テキストまたはフレーム画像から、3～15 秒の動画を生成します。マルチショットや再利用可能な要素の指定に対応し、最大 4K で出力できます。

対応する生成モード

非同期処理の流れ： タスクを作成して data.id を保存し、GET /v1/tasks/{task_id} でステータスをポーリングします。succeeded の場合は data.output.media から結果を取得します。failed の場合は data.error_code と data.error_message を確認し、エラーと再試行の方針に従って対処してください。

ローカルファイルを使う場合： 先に入力ファイルをアップロードし、返された data.url を指定してください。

認証

Authorization   string   必須

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

Authorization: Bearer <BEATAPI_API_KEY>

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

リクエストボディ

model   string   必須

kling-3 を指定してください。

固定値: kling-3

prompt   string   必須

動画生成の指示です。

文字数: 1 – 5000 文字

images   string[]   任意

開始フレーム 1 枚、または開始・終了フレームの画像を公開 HTTPS URL で指定します。マルチショットモードで画像を指定する場合は、1 枚だけ指定できます。

要素数: 1 – 2 件

duration   integer   任意

出力動画の長さを秒単位で指定します。

デフォルト値: 5
範囲: 3 – 15

aspect_ratio   enum<string>   任意

テキストから生成する場合のデフォルト値は 16:9 です。フレーム画像を使う場合は省略すると、入力画像のアスペクト比に合わせて生成されます。

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

resolution   enum<string>   任意

出力品質の区分です。

選択肢: std, pro, 4K
デフォルト値: "pro"

sound   boolean   任意

動画と同期した音声を生成します。マルチショットモードのデフォルト値は true です。

multi_shots   boolean   任意

絵コンテ形式のマルチショット生成を有効にします。

デフォルト値: false

multi_prompt   object[]   任意

multi_shots=true の場合に必要な、各ショットの定義です。

要素数: 1 – 5 件

multi_prompt.prompt   string   親フィールドを指定した場合は必須

このショットの指示です。

文字数: 1 – 500 文字

multi_prompt.duration   integer   親フィールドを指定した場合は必須

ショットの長さを秒単位で指定します。すべてのショットの長さの合計は、タスク全体の長さと一致する必要があります。

範囲: 1 – 12

elements   object[]   任意

再利用する人物や物体の参照素材です。最大 3 個まで指定できます。

要素数: 最大 3 件

elements.name   string   親フィールドを指定した場合は必須

プロンプト内でこの要素を参照するための、一貫した名前です。

文字数: 最小 1 文字

elements.description   string   任意

人物や物体に関する任意の説明です。

elements.element_input_urls   string[]   親フィールドを指定した場合は必須

2～4 個の画像 URL、または 1 個の動画 URL を指定します。

要素数: 1 – 4 件

elements.element_input_audio_urls   string[]   任意

動画要素とともに使用する、任意の音声 URL です。

要素数: 1 – 1 件

elements.start_time   integer   任意

動画要素として使用する区間の開始時刻を、ミリ秒単位で指定します。

範囲: 0 – 30000

elements.end_time   integer   任意

動画要素として使用する区間の終了時刻を、ミリ秒単位で指定します。区間の長さは 3～8 秒にしてください。

範囲: 0 – 30000

リクエスト例

テキストから動画を生成

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-3",
  "prompt": "A dramatic product reveal with a slow orbiting camera move.",
  "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-3",
  "prompt": "Animate the product with a slow orbit and precise studio reflections.",
  "images": [
    "https://media.beatapi.io/samples/smart-bottle.png"
  ],
  "duration": 5,
  "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-3",
  "prompt": "A two-shot cinematic product reveal.",
  "duration": 6,
  "aspect_ratio": "16:9",
  "resolution": "pro",
  "sound": true,
  "multi_shots": true,
  "multi_prompt": [
    {
      "prompt": "Macro detail shot with moving reflections.",
      "duration": 3
    },
    {
      "prompt": "Wide hero reveal on a dark pedestal.",
      "duration": 3
    }
  ]
}'

再利用可能な要素

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-3",
  "prompt": "Keep @product consistent during a slow cinematic camera orbit.",
  "duration": 5,
  "resolution": "pro",
  "elements": [
    {
      "name": "product",
      "description": "The featured bottle",
      "element_input_urls": [
        "https://media.beatapi.io/samples/smart-bottle.png",
        "https://media.beatapi.io/samples/neon-singer.png"
      ]
    }
  ]
}'

レスポンス

リクエストが成功すると、HTTP 201 が返されます。

{
  "data": {
    "id": "task_8K2qA",
    "object": "task",
    "task_kind": "video",
    "capability_id": "kling-3",
    "capability_version": null,
    "media_type": "video",
    "model": "kling-3",
    "status": "queued",
    "stage": "queued",
    "created_at": 1782210000,
    "updated_at": 1782210000,
    "completed_at": null,
    "output": null,
    "usage": {
      "credits_reserved": 0.65,
      "credits_charged": 0.65,
      "billable_duration_seconds": 5,
      "credits_settled": 0,
      "credits_refunded": 0
    },
    "request_id": "req_abc123",
    "error_code": null,
    "error_message": null
  }
}

エラー