Kling Tasks API の連携と使用方法

Kling video generation API guide - Ace Data Cloud

Kling Tasks API の主な機能は、Kling Videos Generation API で生成されたタスクIDを入力して、そのタスクの実行状況を照会することです。

本ドキュメントでは、Kling Tasks API の連携手順を詳しく紹介し、この API の強力な機能を簡単に統合して最大限に活用できるよう支援します。Kling Tasks API を通じて、Kling Videos Generation API のタスク実行状況を簡単に照会できます。

​

申請手順

Kling Videos Generation API を使用するには、まず Ace Data Cloud コンソール で API Token を取得し、控えておいてください。

まだログインまたは登録していない場合は、自動的にログインページへ移動して登録とログインを案内します。完了後、自動的に現在のページへ戻ります。

1つの API Token でプラットフォームのすべてのサービスを呼び出すことができ、サービスごとに個別に申請する必要はありません。 初回申請時には無料クレジットが付与され、無料で体験できます。クレジットが不足した場合は、コンソール で共通残高をチャージできます。

📘 完全なドキュメント：Kling Videos Generation API →

​

リクエスト例

Kling Tasks API は、Kling Videos Generation API の結果を照会するために使用できます。Kling Videos Generation API の使用方法については、ドキュメント Kling Videos Generation API を参照してください。

Kling Videos Generation API サービスから返された1つのタスクIDを例として、この API の使用方法を説明します。タスクID：20068983-0cc9-4c6a-aeb6-9c6a3c668be0 があると仮定し、次に1つのタスクIDを渡してどのようにするかを説明します。

​

タスク例の図

​

リクエストヘッダーとリクエストボディの設定

Request Headers には以下が含まれます：

• accept：JSON 形式のレスポンス結果を受け取るよう指定します。ここでは application/json と入力します。
• authorization：API を呼び出すためのキーです。申請後、直接プルダウンから選択できます。

Request Body には以下が含まれます：

• id：アップロードするタスクID。
• action：タスクに対する操作方法。

設定は次の図のとおりです：

​

コード例

ページ右側にはすでに各種言語のコードが自動生成されていることがわかります。図のとおりです：

一部のコード例は以下のとおりです：

​

CURL

curl -X POST 'https://api.acedata.cloud/kling/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0",
  "action": "retrieve"
}'

​

Python

import requests

url = "https://api.acedata.cloud/kling/tasks"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0",
    "action": "retrieve"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

​

レスポンス例

リクエストが成功すると、API はここでの動画タスクの詳細情報を返します。例えば：

{
  "_id": "67c5163f550a4144a5b68698",
  "id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0",
  "api_id": "29187cb2-1acb-43b8-baf5-3f3f709292eb",
  "application_id": "f35762fe-e8a4-4613-bb70-e5c1be4f9fc2",
  "created_at": 1740969535.333,
  "started_at": 1740969535.393,
  "finished_at": 1740969852.463,
  "elapsed": 317.07,
  "credential_id": "ce81345f-7e2a-4871-b539-aefb5f725220",
  "request": {
    "action": "text2video",
    "model": "kling-v1",
    "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle.",
    "callback_url": "https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3"
  },
  "trace_id": "0a907f69-4ae2-4a08-b34c-ee15c1c47077",
  "type": "videos",
  "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
  "job_id": "CjJzzGfBfqcAAAAAAKdVMQ",
  "response": {
    "success": true,
    "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
    "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
    "duration": "5.1",
    "state": "succeed",
    "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
  }
}

返却結果には複数のフィールドがあり、request フィールドはタスク開始時の request body であり、同時にresponse フィールドはタスク完了後に返されるresponse bodyです。フィールドの説明は以下のとおりです。

• id、この動画タスクを生成する ID。今回の動画生成タスクを一意に識別するために使用されます。
• request、動画タスクにおけるリクエスト情報を照会します。
• response、動画タスクにおける返却情報を照会します。
• created_at、タスク作成時刻、Unix タイムスタンプ（秒、浮動小数点）。
• started_at、タスクの実行開始時刻、Unix タイムスタンプ（秒、浮動小数点）。
• finished_at、タスク完了時刻、Unix タイムスタンプ（秒、浮動小数点）。タスクが未完了の場合、このフィールドは返されません。
• elapsed、タスク実行時間。単位は秒（浮動小数点、小数点以下3桁を保持）。タスクが未完了の場合、このフィールドは返されません。

​

一括照会操作

これは複数のタスクIDを対象に動画タスクの詳細を照会するもので、上記と異なる点はactionをretrieve_batchに選択する必要があることです

Request Body には以下が含まれます：

• ids：アップロードするタスクID配列。
• action：タスクに対する操作方法。

設定は次の図のとおりです：

​

コード例

ページ右側にはすでに各種言語のコードが自動生成されていることがわかります。図のとおりです：

一部のコード例は以下のとおりです：

​

レスポンス例

リクエストが成功すると、API は今回のすべての一括動画タスクの具体的な詳細情報を返します。例えば：

{
  "items": [
    {
      "_id": "67c5163f550a4144a5b68698",
      "id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0",
      "api_id": "29187cb2-1acb-43b8-baf5-3f3f709292eb",
      "application_id": "f35762fe-e8a4-4613-bb70-e5c1be4f9fc2",
      "created_at": 1740969535.333,
      "started_at": 1740969535.393,
      "finished_at": 1740969852.463,
      "elapsed": 317.07,
      "credential_id": "ce81345f-7e2a-4871-b539-aefb5f725220",
      "request": {
        "action": "text2video",
        "model": "kling-v1",
        "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle.",
        "callback_url": "https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3"
      },
      "trace_id": "0a907f69-4ae2-4a08-b34c-ee15c1c47077",
      "type": "videos",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "job_id": "CjJzzGfBfqcAAAAAAKdVMQ",
      "response": {
        "success": true,
        "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
        "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
        "duration": "5.1",
        "state": "succeed",
        "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
      }
    },
    {
      "_id": "67c51415550a4144a5b442a5",
      "id": "e3a575aa-a4bd-49c8-9b12-cde38d5462e0",
      "api_id": "29187cb2-1acb-43b8-baf5-3f3f709292eb",
      "application_id": "f35762fe-e8a4-4613-bb70-e5c1be4f9fc2",
      "created_at": 1740968981.619,
      "started_at": 1740968981.679,
      "finished_at": 1740969297.937,
      "elapsed": 316.258,
      "credential_id": "ce81345f-7e2a-4871-b539-aefb5f725220",
      "request": {
        "action": "text2video",
        "model": "kling-v1",
        "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle."
      },
      "trace_id": "4f32ba2d-8846-4ea9-9253-997ec0b2e052",
      "type": "videos",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "job_id": "Cjil4mfBfs0AAAAAAKbMQQ",
      "response": {
        "success": true,
        "video_id": "af9a1af0-9aa0-4638-81c1-d41d6143c508",
        "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
        "duration": "5.1",
        "state": "succeed",
        "task_id": "e3a575aa-a4bd-49c8-9b12-cde38d5462e0"
      }
    }
  ],
  "count": 2
}

返却結果には複数のフィールドがあり、そのうち items にはバッチ動画タスクの具体的な詳細情報が含まれています。各動画タスクの具体的な情報は上記のフィールドと同じであり、フィールド情報は以下のとおりです。

• items、バッチ動画タスクのすべての具体的な詳細情報。これは配列であり、各配列要素の形式は上記の単一タスクの照会結果と同じです。
• count、ここでバッチ照会する動画タスクの数です。

​

CURL

curl -X POST 'https://api.acedata.cloud/kling/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["e3a575aa-a4bd-49c8-9b12-cde38d5462e0","20068983-0cc9-4c6a-aeb6-9c6a3c668be0"],
  "action": "retrieve_batch"
}'

​

エラー処理

API を呼び出す際にエラーが発生した場合、API は対応するエラーコードと情報を返します。例：

• 400 token_mismatched：不正なリクエスト。パラメータの欠落または無効が原因である可能性があります。
• 400 api_not_implemented：不正なリクエスト。パラメータの欠落または無効が原因である可能性があります。
• 401 invalid_token：未認証。認可トークンが無効または存在しません。
• 429 too_many_requests：リクエストが多すぎます。レート制限を超過しています。
• 500 api_error：内部サーバーエラー。サーバーで問題が発生しました。

​

エラーレスポンスの例

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​

結論

本ドキュメントを通じて、Kling Tasks API を使用して単一またはバッチの動画タスクに関するすべての具体的な詳細情報を照会する方法を理解しました。本ドキュメントが、この API の連携および利用により役立つことを願っています。ご不明な点がございましたら、いつでも弊社の技術サポートチームまでお問い合わせください。