> ## Documentation Index > Fetch the complete documentation index at: https://docs.jiekou.ai/llms.txt > Use this file to discover all available pages before exploring further. # Kling 3.0 Turbo パラメータと使用方法は公式に合わせています。詳細なパラメータは公式ドキュメントを直接参照してください。 ## 1. 概要 本書では、Kling 3.0 Turbo の公式プロトコルを通じてテキストから動画生成および画像から動画生成の機能を使用する方法について説明します。Turbo は標準の Kling 3.0 と同じ公式プロトコルを採用しており、リクエストとレスポンスの構造は同一ですが、対応機能の範囲、解像度の区分、課金のみが異なります。 どちらの機能も非同期タスク方式を採用しています： 1. 対応する作成エンドポイントを呼び出します。 2. 作成レスポンスの `data.id` を保存します。 3. タスク作成時と同じ API Key を使用してタスクステータスを照会します。 4. タスク成功後、`outputs` から生成された動画を取得して保存します。 ### 1.1 API エンドポイント | 機能 | タスク作成 | タスク照会 | | - | - | - | | テキストから動画生成 | `POST /v3/kling/text-to-video/kling-3.0-turbo` | `GET /v3/kling/tasks` | | 画像から動画生成 | `POST /v3/kling/image-to-video/kling-3.0-turbo` | `GET /v3/kling/tasks` | 本文中の例における完全なアドレスは、`https://{api_domain}` に表内の API パスを加えたものです。ここで `{api_domain}` はお使いの API ドメインです。Turbo はテキストから動画生成と画像から動画生成のみを提供し、Omni 動画とモーション制御には対応していません。 ### 1.2 認証 すべてのリクエストに API Key を含める必要があります。POST リクエストでは、JSON コンテンツタイプも指定する必要があります： ``` Authorization: Bearer Content-Type: application/json ``` ### 1.3 レスポンス構造 作成レスポンスの `data` はオブジェクトです。一般的なフィールドは `id`（Kling システムが生成したタスク ID。以降の照会に使用）、`external_id`（`options.external_task_id` のエコーバック。設定されていない場合は返されないことがあります）、`status`（作成直後のタスクステータス。通常は `submitted`）です。 照会レスポンスの `data` は配列です。各タスクには `id`、`external_id`、`status`（`submitted`、`processing`、`succeeded`、`failed`）、`message`、`create_time`、`update_time`、`outputs` が含まれます。`outputs` 内の動画結果で一般的なフィールドは `type`、`id`、`url`、`watermark_url`、`duration` です。`url` は透かしなし結果のアドレス、`watermark_url` は透かし付き結果のアドレス、`duration` は動画の長さ（秒）です。 ## 2. テキストから動画生成 ### 2.1 タスク作成 ``` POST https://{api_domain}/v3/kling/text-to-video/kling-3.0-turbo ``` リクエストフィールド： | フィールド | 型 | 必須 | デフォルト値 / 取り得る値 | 説明 | | - | - | - | - | - | | `prompt` | string | はい | | テキストプロンプト。ポジティブおよびネガティブな記述を含められます。上限 3072 文字、2500 文字以下を推奨 | | `settings.resolution` | string | いいえ | デフォルト `720p`；`720p`、`1080p` | 生成動画の解像度 | | `settings.aspect_ratio` | string | いいえ | デフォルト `16:9`；`16:9`、`9:16`、`1:1` | 生成動画のアスペクト比（幅:高さ） | | `settings.duration` | int | いいえ | デフォルト 5；3～15 の整数 | 生成動画の長さ（秒） | | `options.callback_url` | string | いいえ | | タスクステータス変化時にコールバック通知を受け取るアドレス | | `options.external_task_id` | string | いいえ | | カスタムタスク ID。システムタスク ID は上書きしません。照会に使用でき、単一ユーザー内で一意である必要があります | | `options.watermark_info.enabled` | boolean | いいえ | デフォルト `false` | 透かし付き結果を生成するかどうか | マルチショット動画は `prompt` の固定フォーマット「镜头 n, m, words; 镜头 n, m, words;」（半角記号で区切る）で実現します。ここで n はショット番号（最大 6 個、最小 1 個）、m はショットの長さ（各ショットは 1 以上、すべてのショットの長さの合計は動画全体の長さと等しい）、words はショットのプロンプト（最長 512 文字）です。 ### 2.2 作成例 ```bash theme={null} curl -X POST 'https://{api_domain}/v3/kling/text-to-video/kling-3.0-turbo' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A cinematic tracking shot of a red sports car driving along a coastal road at sunset", "settings": { "resolution": "1080p", "aspect_ratio": "16:9", "duration": 5 }, "options": { "external_task_id": "turbo-text-20260826-0001" } }' ``` 作成に成功するとタスク ID が返されます： ```json theme={null} { "code": 0, "message": "success", "request_id": "provider-request-id", "data": { "id": "kling-turbo-text-task-id", "external_id": "turbo-text-20260826-0001", "status": "submitted", "create_time": 1781080778802, "update_time": 1781080794151 } } ``` `data.id` を保存してください。`options.external_task_id` を渡していない場合、`data.external_id` は返されないことがあります。 ### 2.3 タスク照会 ``` GET https://{api_domain}/v3/kling/tasks?task_ids={task_id} ``` タスク作成時と同じ API Key を使用してください。`external_task_ids` を使用してカスタムタスク ID を照会することもできます。`task_ids` と `external_task_ids` は毎回必ずどちらか一方のみを指定してください。どちらも英語のカンマで区切って 1～50 個の ID を指定でき、レスポンスの `data` は配列でリクエストした ID の順序を保持します。 ### 2.4 照会例 ```bash theme={null} curl -X GET 'https://{api_domain}/v3/kling/tasks?task_ids=kling-turbo-text-task-id' \ -H 'Authorization: Bearer ' ``` タスク成功時は次のように返されます： ```json theme={null} { "code": 0, "message": "success", "request_id": "provider-request-id", "data": [ { "id": "kling-turbo-text-task-id", "status": "succeeded", "outputs": [ { "type": "video", "url": "https://your-result-cdn.example.com/turbo-text.mp4", "duration": 5 } ] } ] } ``` `status=processing` はタスクがまだ実行中であることを示します。10～30 秒ごとに照会することを推奨します。`status=failed` はタスク失敗を示し、ポーリングを継続しないでください。タスク成功後は、`outputs[type=video].url` に対応するファイルを速やかに保存してください。ダウンロード URL には有効期限がある可能性があります。 ### 2.5 課金について ``` タスク料金 = 対応解像度の 1 秒あたり単価 × settings.duration ``` 料金区分は `settings.resolution`（`720p` または `1080p`）のみで決まります。`duration` を渡していない場合はデフォルトの 5 秒で課金されます。タスク作成時にリクエストした長さに応じて課金されます。タスク作成に失敗した場合、または最終的な生成に失敗した場合、料金は自動的に返金されます。具体的な単価は、ご利用のサービスの料金ページに準じます。 ## 3. 画像から動画生成 ### 3.1 タスク作成 ``` POST https://{api_domain}/v3/kling/image-to-video/kling-3.0-turbo ``` リクエストフィールド： | フィールド | 型 | 必須 | デフォルト値 / 取り得る値 | 説明 | | - | - | - | - | - | | `contents` | array | はい | | 参照素材のコレクション。少なくとも 1 項目を含みます | | `contents[].type` | string | はい | `prompt`、`first_frame` | 素材タイプ：プロンプト、先頭フレーム画像 | | `contents[].text` | string | いいえ | | `type=prompt` の場合のテキストプロンプト。最長 2500 文字 | | `contents[].url` | string | いいえ | | `type=first_frame` の場合の先頭フレーム画像。URL または Base64 をサポート | | `settings.resolution` | string | いいえ | デフォルト `720p`；`720p`、`1080p` | 生成動画の解像度 | | `settings.duration` | int | いいえ | デフォルト 5；3～15 の整数 | 生成動画の長さ（秒） | | `options.external_task_id` | string | いいえ | | カスタムタスク ID。システムタスク ID は上書きしません。照会に使用でき、単一ユーザー内で一意である必要があります | | `options.watermark_info.enabled` | boolean | いいえ | デフォルト `false` | 透かし付き結果を生成するかどうか | 画像は `.jpg`、`.jpeg`、`.png` に対応し、ファイルサイズは 50 MB 以下、幅と高さは 300 ピクセル以上、アスペクト比は 1:2.5 から 2.5:1 の範囲である必要があります。画像から動画生成では先頭フレーム画像のみに対応し、「先頭フレーム＋末尾フレーム」および「末尾フレームのみ」には現時点で対応していません。`options.callback_url` も渡すことができ、使用方法はテキストから動画生成と同じです。マルチショットも同様に `prompt` の固定フォーマットで実現します。 ### 3.2 作成例 ```bash theme={null} curl -X POST 'https://{api_domain}/v3/kling/image-to-video/kling-3.0-turbo' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "contents": [ { "type": "prompt", "text": "The subject turns toward the camera while the wind moves naturally through the scene" }, { "type": "first_frame", "url": "https://your-cdn.example.com/first-frame.png" } ], "settings": { "resolution": "1080p", "duration": 5 }, "options": { "external_task_id": "turbo-image-20260826-0001" } }' ``` 作成成功時は次のように返されます： ```json theme={null} { "code": 0, "message": "success", "request_id": "provider-request-id", "data": { "id": "kling-turbo-image-task-id", "external_id": "turbo-image-20260826-0001", "status": "submitted", "create_time": 1781080778802, "update_time": 1781080794151 } } ``` ### 3.3 タスク照会 作成レスポンスの `data.id` を使用してタスクを照会します： ``` GET https://{api_domain}/v3/kling/tasks?task_ids={task_id} ``` `task_ids` で照会する場合は、タスク作成時と同じ API Key を使用してください。`external_task_ids` を使用して、作成時に渡した `options.external_task_id` を照会することもできます。照会パラメータは英語のカンマで区切った 1～50 個の ID をサポートします。 ### 3.4 照会例 ```bash theme={null} curl -X GET 'https://{api_domain}/v3/kling/tasks?task_ids=kling-turbo-image-task-id' \ -H 'Authorization: Bearer ' ``` タスク成功時、動画アドレスは `outputs[type=video].url` にあります： ```json theme={null} { "code": 0, "message": "success", "request_id": "provider-request-id", "data": [ { "id": "kling-turbo-image-task-id", "status": "succeeded", "outputs": [ { "type": "video", "url": "https://your-result-cdn.example.com/turbo-image.mp4", "duration": 5 } ] } ] } ``` `status=processing` の場合は 10～30 秒ごとに照会を続けることを推奨します。`status=failed` の場合はポーリングを停止し、エラーメッセージに従って入力を修正してください。 ### 3.5 課金について ``` タスク料金 = 対応解像度の 1 秒あたり単価 × settings.duration ``` 料金区分は `settings.resolution`（`720p` または `1080p`）のみで決まります。`duration` を渡していない場合はデフォルトの 5 秒で課金されます。タスク作成時にリクエストした長さに応じて課金されます。タスク作成に失敗した場合、または最終的な生成に失敗した場合、料金は自動的に返金されます。具体的な単価は、ご利用のサービスの料金ページに準じます。 ## 4. よくあるエラーと注意事項 API エラーは次の構造になります： ```json theme={null} { "code": 1203, "message": "task not found (trace_id: platform-trace-id)", "request_id": "", "data": null } ``` よくあるステータスコード：400/1200（パラメータまたはコンテンツタイプが不正。`message` に従って修正）、401/1000（API Key が欠落しているか無効）、403/1103（実行権限なし）、404/1203（タスクが存在しない、または照会権限なし）、429/1302（リクエスト過多。頻度を下げて指数バックオフ）、500/5000、503/5001、504/5002（サービス異常またはタイムアウト。後で再試行し、制御なく重複送信しないでください）。`message` に `trace_id` が含まれる場合は、テクニカルサポートへの問い合わせ時に併せて提供してください。 その他の注意事項： * リクエストボディに `model` や `model_name` を追加する必要はありません。モデルバージョンは URL に含まれています。 * タスク作成後は `data.id` を永続化してください。`request_id` をタスク ID として扱わないでください。 * 1 回のリクエストボディの最大サイズは 64 MB です。大きな画像には、Kling が公開アクセスできるパブリック URL の使用を推奨します。 * 入力素材の URL は Kling が公開アクセスできる必要があり、社内ネットワーク、Cookie、一時的なログイン状態に依存してはいけません。 * 照会 API では 10～30 秒のポーリング間隔を使用し、全体のタイムアウトと指数バックオフを設定してください。 * POST がタイムアウトしても、タスクが作成されなかったとは限りません。まず `external_task_id` で照会し、その後再試行するか判断してください。 * 成功ステータスを受信したら、直ちに `outputs[type=video].url` に対応するファイルを保存してください。結果 URL は期限切れになる可能性があります。 ## 5. Python 呼び出し例 以下の例では標準の `requests` ライブラリを使用し、テキストから動画生成の作成とポーリングを演示します。画像から動画生成では、作成エンドポイントとリクエストボディを置き換えるだけです。 ```python theme={null} import os import time import requests api_domain = os.environ["API_DOMAIN"] api_key = os.environ["PLATFORM_API_KEY"] headers = { "Authorization": f"Bearer {api_key}", "Content-Type": "application/json", } payload = { "prompt": "A calm cinematic landscape at sunrise", "settings": { "resolution": "1080p", "aspect_ratio": "16:9", "duration": 5, }, "options": { "external_task_id": "turbo-python-20260826-0001", }, } created = requests.post( f"https://{api_domain}/v3/kling/text-to-video/kling-3.0-turbo", headers=headers, json=payload, timeout=60, ) created.raise_for_status() task_id = created.json()["data"]["id"] while True: response = requests.get( f"https://{api_domain}/v3/kling/tasks", headers={"Authorization": f"Bearer {api_key}"}, params={"task_ids": task_id}, timeout=30, ) response.raise_for_status() task = response.json()["data"][0] if task["status"] == "succeeded": video = next(item for item in task["outputs"] if item["type"] == "video") print(video["url"]) break if task["status"] == "failed": raise RuntimeError(task) time.sleep(20) ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.