Kling Tasks API Integration and Usage

The main function of the Kling Tasks API is to query the execution status of a task by entering the task ID generated by the Kling Videos Generation API.

This document will provide a detailed introduction to the integration instructions for the Kling Tasks API, helping you easily integrate and make full use of the powerful features of this API. Through the Kling Tasks API, you can easily query the task execution status of the Kling Videos Generation API.

Application Process

To use the Kling Videos Generation API, first go to the qiyaov Console to obtain your API Token and keep it for later use.

If you have not yet logged in or registered, you will be automatically redirected to the login page to invite you to register and log in. After completion, you will automatically return to the current page.

One API Token can call all platform services, with no need to apply separately for each service. Your first application will include free credits for a free trial; when credits are insufficient, you can recharge your general balance in the Console.

📘 Full documentation: Kling Videos Generation API →

Request Example

The Kling Tasks API can be used to query the results of the Kling Videos Generation API. For how to use the Kling Videos Generation API, please refer to the documentation Kling Videos Generation API .

We take one task ID returned by the Kling Videos Generation API service as an example to demonstrate how to use this API. Suppose we have a task ID: 20068983-0cc9-4c6a-aeb6-9c6a3c668be0. Next, we demonstrate how to by passing in one task ID.

Task Example Image

Set Request Headers and Request Body

Request Headers include:

  • accept: Specifies the response result received in JSON format; enter application/json here.
  • authorization: The key for calling the API, which can be directly selected from the dropdown after application.

Request Body includes:

  • id: The uploaded task ID.
  • action: The operation method for the task.

Configure it as shown in the image below:

Code Example

It can be found that code in various languages has already been automatically generated on the right side of the page, as shown in the image:

Some code examples are as follows:

CURL

curl -X POST 'https://api.qiyaov.com/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.qiyaov.com/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)

Response Example

After the request succeeds, the API will return detailed information about the video task here. For example:

{
  "_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"
  }
}

The returned result contains multiple fields in total. The request field is the request body when initiating the task, while the response field is the response body returned after the task is completed. The field descriptions are as follows.

  • id, the ID that generates this video task, used to uniquely identify this video generation task.
  • request, the request information in the queried video task.
  • response, the returned information in the queried video task.
  • created_at, the task creation time, Unix timestamp (seconds, floating-point).
  • started_at, the task execution start time, Unix timestamp (seconds, floating-point).
  • finished_at, the task completion time, Unix timestamp (seconds, floating-point). This field is not returned when the task is not completed.
  • elapsed, the task execution duration, in seconds (floating-point, retained to 3 decimal places). This field is not returned when the task is not completed.

Batch Query Operation

This is for querying video task details for multiple task IDs. Unlike the above, you need to select retrieve_batch for action.

Request Body includes:

  • ids: An array of uploaded task IDs.
  • action: The operation method for the task.

Configure it as shown in the image below:

Code Example

It can be found that code in various languages has already been automatically generated on the right side of the page, as shown in the image:

Some code examples are as follows:

Response Example

After the request succeeds, the API will return specific detailed information for all batch video tasks this time. For example:

{
  "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
}

The response result contains multiple fields. Among them, items contains the detailed information of batch video tasks. The detailed information of each video task is the same as the fields above. The field information is as follows.

  • items, all detailed information of batch video tasks. It is an array, and each element in the array has the same format as the response result for querying a single task above.
  • count, the number of video tasks queried in this batch.

CURL

curl -X POST 'https://api.qiyaov.com/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"
}'

Error Handling

When calling the API, if an error occurs, the API will return the corresponding error code and information. For example:

  • 400 token_mismatched: Bad request, possibly due to missing or invalid parameters.
  • 400 api_not_implemented: Bad request, possibly due to missing or invalid parameters.
  • 401 invalid_token: Unauthorized, invalid or missing authorization token.
  • 429 too_many_requests: Too many requests, you have exceeded the rate limit.
  • 500 api_error: Internal server error, something went wrong on the server.

Error Response Example

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

Conclusion

Through this document, you have learned how to use the Kling Tasks API to query all detailed information of a single or batch video tasks. We hope this document can help you better integrate with and use this API. If you have any questions, please feel free to contact our technical support team.