Query & Download (Kling Unified Format)

After submitting a task, poll the query endpoint with the id from the submit response. Once the task succeeds, the response already carries the direct video link — querying and fetching are one call; no extra download endpoint needed.

Endpoint

GET /kling-video/v1/videos/{task_id}

task_id is the id from the submit response (see Submit Task · Response Body).

Request Example

Poll until SUCCESS / FAILURE, then download result_url:

cURL
Python
Node.js
# Query task status and result link
curl https://api-model.shuntianchuang.cn/kling-video/v1/videos/task_xxxxxxxx \
  -H "Authorization: Bearer sk-your-token"

# Once SUCCESS, result_url is the direct video link
curl -o output.mp4 "the URL returned in result_url"

Response Body

FieldDescription
codeAlways "success" (business errors use the unified error envelope, see Failures & Errors)
messageAlways an empty string
data.task_idTask id
data.statusFour values: QUEUED → IN_PROGRESS → SUCCESS / FAILURE
data.progress"0%"–"100%"; always "100%" on SUCCESS
data.result_urlNon-empty only on SUCCESS: direct video link, ready to use
data.fail_reasonNon-empty only on FAILURE: why the task failed

Task status advances automatically in the platform backend — customer polling is not required for progress; it is only how you obtain result_url.

State machine:

submit ──> QUEUED ──> IN_PROGRESS ──> SUCCESS (result_url downloadable)
                          └────────> FAILURE (fail_reason)

Response Example

// In progress
{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_xxxxxxxx",
    "status": "IN_PROGRESS",
    "progress": "40%",
    "result_url": "",
    "fail_reason": ""
  }
}
// Succeeded
{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_xxxxxxxx",
    "status": "SUCCESS",
    "progress": "100%",
    "result_url": "https://example.com/output.mp4",
    "fail_reason": ""
  }
}

Downloading the Result

result_url is a direct link: open it in a browser to preview / save; HTTP GET download, <video> playback, or frontend fetch all work.

The link expires — download and store your videos promptly after generation, and do not treat it as a permanent distribution link.

Failures and Errors

  • Failed task: data.status is FAILURE and data.fail_reason carries a readable reason (e.g. non-compliant material); failed tasks are never billed;
  • Task not found (HTTP 404):
{
  "code": "task_not_found",
  "message": "Task not found (request id: …)",
  "data": null
}