> 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. # Kling 3 > テキストまたはフレーム画像から、3～15 秒の動画を生成します。マルチショットや再利用可能な要素の指定に対応し、最大 4K で出力できます。 `POST https://api.beatapi.io/v1/videos/tasks` テキストまたはフレーム画像から、3～15 秒の動画を生成します。マルチショットや再利用可能な要素の指定に対応し、最大 4K で出力できます。 ### 対応する生成モード | モード | 必須の入力 | 入力ルール | | ----------- | ------------------------------------------------ | ---------------------------------------------------------------- | | テキストから動画を生成 | `model`, `prompt` | `images`、`multi_prompt`、`elements` は省略してください。 | | 開始フレームを指定 | `model`, `prompt`, `images` | 開始フレームには画像 URL を 1 個指定します。開始・終了フレームを使う場合は 2 個指定します。 | | マルチショット | `model`, `prompt`, `multi_shots`, `multi_prompt` | `multi_shots=true` を指定します。すべてのショットの長さの合計を `duration` に一致させてください。 | | 再利用可能な要素 | `model`, `prompt`, `elements` | 名前を付けた画像または動画の参照要素を、最大 3 個指定します。 | **非同期処理の流れ：** タスクを作成して `data.id` を保存し、`GET /v1/tasks/{task_id}` で[ステータスをポーリング](/quick-guide#get-task-status)します。`succeeded` の場合は `data.output.media` から結果を取得します。`failed` の場合は `data.error_code` と `data.error_message` を確認し、[エラーと再試行の方針](/quick-guide#errors-and-retry-policy)に従って対処してください。 **ローカルファイルを使う場合：** 先に[入力ファイルをアップロード](/quick-guide#upload-an-input-file)し、返された `data.url` を指定してください。 ## 認証 `Authorization`   `string`   **必須** BeatAPI の API キーを Bearer トークンとして送信します。API キーは[ダッシュボード](https://beatapi.io/dashboard)で作成できます。 ``` Authorization: Bearer ``` 通常の 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`   **任意** テキストから生成する場合のデフォルト値は 16:9 です。フレーム画像を使う場合は省略すると、入力画像のアスペクト比に合わせて生成されます。 **選択肢:** `16:9`, `9:16`, `1:1` --- `resolution`   `enum`   **任意** 出力品質の区分です。 **選択肢:** `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 ## リクエスト例 ### テキストから動画を生成 ```bash curl --request POST \ --url https://api.beatapi.io/v1/videos/tasks \ --header 'Authorization: Bearer ' \ --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 }' ``` ### 開始フレームを指定 ```bash curl --request POST \ --url https://api.beatapi.io/v1/videos/tasks \ --header 'Authorization: Bearer ' \ --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 }' ``` ### マルチショット ```bash curl --request POST \ --url https://api.beatapi.io/v1/videos/tasks \ --header 'Authorization: Bearer ' \ --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 } ] }' ``` ### 再利用可能な要素 ```bash curl --request POST \ --url https://api.beatapi.io/v1/videos/tasks \ --header 'Authorization: Bearer ' \ --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` が返されます。 ```json { "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 } } ``` ## エラー | ステータスコード | 意味と対処方法 | | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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` | リクエスト数が上限を超えています（無料モデルの制限を含む `rate_limit_exceeded`）、または同時処理中のタスクが多すぎます（`user_concurrency_exceeded`）。`Retry-After` の秒数だけ待ってから再試行できます。同じ値は `error.retry_after_seconds` にも含まれます。 | | `500` | 予期しない内部エラーです（`internal_error`）。再試行できます。繰り返し発生する場合は、`request_id` を控えてサポートに連絡してください。 | | `503` | リクエストを完了できませんでした（`processing_unavailable`、`processing_timeout`、`processing_failed`、`result_transfer_failed`）。課金されていません。待機時間を段階的に延ばして再試行できます。待機時間が判明している場合は `Retry-After` が返されます。BeatAPI は 502 や 504 を返しません。 |