> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a Kling task

> Query a Kling video generation task by task_id and return its status, progress, and result metadata for polling.

Use this endpoint family after you create a Kling task. It is the common polling step for Kling async media jobs.

<Warning>
  A query can return the task object directly or inside the standard `data`
  envelope. Normalize each response with `task = payload.data ?? payload` before
  reading task fields.
</Warning>

## What to check first

* `task.task_status`; Motion Control tasks use `submitted`, `processing`,
  `succeed`, or `failed`
* `task.task_result.videos[0].url` when a video task succeeds
* `task.task_status_msg` or other returned detail fields when a task stops early
* `code`, `message`, and `request_id` when the response uses the standard
  envelope

## Polling pattern

<Steps>
  <Step title="Create the task from the matching endpoint">
    Start with the Kling creation page for your workflow, such as [Text to Video](./text-to-video), [Image to Video](./image-to-video), or [Motion Control](./motion-control).
  </Step>

  <Step title="Poll until the task is terminal">
    Normalize the response shape, then keep querying with the returned task id
    until it reaches a terminal state. For Motion Control, the terminal states
    are `succeed` and `failed`.
  </Step>

  <Step title="Continue to the next workflow step">
    Use the finished output directly, or move into the next applicable action page if your workflow supports chained operations.
  </Step>
</Steps>

## Common path pairs

| Workflow          | Query path                                      |
| ----------------- | ----------------------------------------------- |
| Text to video     | `/kling/v1/videos/text2video/{task_id}`         |
| Image to video    | `/kling/v1/videos/image2video/{task_id}`        |
| Motion Control    | `/kling/v1/videos/motion-control/{task_id}`     |
| Multi-image video | `/kling/v1/videos/multi-image2video/{task_id}`  |
| Video effects     | `/kling/v1/videos/effects/{task_id}`            |
| Video extension   | `/kling/v1/videos/video-extend/{task_id}`       |
| Avatar video      | `/kling/v1/videos/avatar/image2video/{task_id}` |

<Note>
  For the full parameter reference, see the [official Kling documentation](https://kling.ai/document-api).
</Note>


## OpenAPI

````yaml api/openapi/video/kling/get-individual-queries.openapi.json GET /kling/v1/{action}/{action2}/{task_id}
openapi: 3.1.0
info:
  title: Kling task query API
  version: 1.0.0
servers:
  - url: https://api.cometapi.com
security:
  - bearerAuth: []
paths:
  /kling/v1/{action}/{action2}/{task_id}:
    get:
      summary: 'Individual queries '
      description: >-
        The example uses `videos/text2video`; substitute the action segments
        that match your task type, such as `images/generations` or
        `audio/text-to-audio`.
      operationId: individual_queries
      parameters:
        - name: action
          in: path
          required: true
          description: 'Resource type. One of: `images`, `videos`, `audio`.'
          schema:
            type: string
        - name: action2
          in: path
          required: true
          description: >-
            Sub-action matching the resource type. For `images`: `generations`,
            `kolors-virtual-try-on`. For `videos`: `text2video`, `image2video`,
            `motion-control`, `lip-sync`, `effects`, `multi-image2video`,
            `multi-elements`. For `audio`: `text-to-audio`, `video-to-audio`.
          schema:
            type: string
        - name: task_id
          in: path
          required: true
          description: Task ID
          schema:
            type: string
      responses:
        '200':
          description: Current Kling task state.
          content:
            application/json:
              schema:
                description: >-
                  A query can return the task object directly or inside the
                  standard response envelope. Normalize both shapes before
                  reading task fields.
                oneOf:
                  - $ref: '#/components/schemas/KlingTask'
                  - $ref: '#/components/schemas/KlingTaskEnvelope'
              examples:
                Immediate submitted:
                  summary: Task returned directly immediately after creation
                  value:
                    task_id: <task_id>
                    task_status: submitted
                    task_info: {}
                    created_at: 1781080355827
                    updated_at: 1781080355827
                Processing:
                  summary: Task still rendering
                  value:
                    code: 0
                    message: SUCCEED
                    request_id: <request_id>
                    data:
                      task_id: <task_id>
                      task_status: processing
                      task_info: {}
                      task_result: {}
                      created_at: 1781080355827
                      updated_at: 1781080362336
                Succeed:
                  summary: Finished task with video result
                  value:
                    code: 0
                    message: SUCCEED
                    request_id: <request_id>
                    data:
                      task_id: <task_id>
                      task_status: succeed
                      task_info: {}
                      created_at: 1781074110938
                      updated_at: 1781074171088
                      task_result:
                        videos:
                          - id: <video_id>
                            url: https://media.example.com/<file_id>.mp4
                            duration: '6.4'
                      final_unit_deduction: <value>
                      final_balance_deduction:
                        quota: <value>
                        list_price: <value>
                Failed:
                  summary: Task reached a failed terminal state
                  value:
                    code: 0
                    message: SUCCEED
                    request_id: <request_id>
                    data:
                      task_id: <task_id>
                      task_status: failed
                      task_status_msg: The task could not be completed.
                      task_info: {}
                      task_result: {}
                      created_at: 1781074110938
                      updated_at: 1781074171088
      x-codeSamples:
        - lang: Shell
          label: Default
          source: >
            curl "https://api.cometapi.com/kling/v1/videos/text2video/<task_id>"
            \
              -H "Authorization: Bearer $COMETAPI_KEY"
        - lang: Shell
          label: Poll until done
          source: >
            curl "https://api.cometapi.com/kling/v1/videos/text2video/<task_id>"
            \
              -H "Authorization: Bearer $COMETAPI_KEY"
        - lang: Python
          label: Default
          source: |
            import os
            import requests

            task_id = "<task_id>"

            response = requests.get(
                f"https://api.cometapi.com/kling/v1/videos/text2video/{task_id}",
                headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
            )

            payload = response.json()
            task = payload.get("data", payload)
            print(task["task_status"])
        - lang: Python
          label: Poll until done
          source: |
            import os
            import time
            import requests

            task_id = "<task_id>"
            headers = {"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]}

            while True:
                payload = requests.get(
                    f"https://api.cometapi.com/kling/v1/videos/text2video/{task_id}", headers=headers
                ).json()
                task = payload.get("data", payload)
                print(task["task_status"])
                if task["task_status"] in ("succeed", "failed"):
                    break
                time.sleep(30)

            if task["task_status"] == "succeed":
                print(task["task_result"])
        - lang: JavaScript
          label: Default
          source: >
            const taskId = "<task_id>";


            const response = await
            fetch(`https://api.cometapi.com/kling/v1/videos/text2video/${taskId}`,
            {
                headers: { Authorization: `Bearer ${process.env.COMETAPI_KEY}` },
            });


            const payload = await response.json();

            const task = payload.data ?? payload;

            console.log(task.task_status);
        - lang: JavaScript
          label: Poll until done
          source: >
            const taskId = "<task_id>";

            const headers = { Authorization: `Bearer
            ${process.env.COMETAPI_KEY}` };


            let task;

            while (true) {
                const payload = await (await fetch(`https://api.cometapi.com/kling/v1/videos/text2video/${taskId}`, { headers })).json();
                task = payload.data ?? payload;
                console.log(task.task_status);
                if (task.task_status === "succeed" || task.task_status === "failed") break;
                await new Promise((resolve) => setTimeout(resolve, 30000));
            }


            if (task.task_status === "succeed") console.log(task.task_result);
        - lang: Shell
          label: Motion Control
          source: >
            curl
            "https://api.cometapi.com/kling/v1/videos/motion-control/<task_id>"
            \
              -H "Authorization: Bearer $COMETAPI_KEY"
        - lang: Python
          label: Motion Control
          source: |
            import os
            import requests

            task_id = "<task_id>"
            response = requests.get(
                f"https://api.cometapi.com/kling/v1/videos/motion-control/{task_id}",
                headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
            )

            payload = response.json()
            task = payload.get("data", payload)
            print(task["task_status"])
        - lang: JavaScript
          label: Motion Control
          source: |
            const taskId = "<task_id>";
            const response = await fetch(
              `https://api.cometapi.com/kling/v1/videos/motion-control/${taskId}`,
              {
                headers: { Authorization: `Bearer ${process.env.COMETAPI_KEY}` },
              },
            );

            const payload = await response.json();
            const task = payload.data ?? payload;
            console.log(task.task_status);
components:
  schemas:
    KlingTask:
      type: object
      required:
        - task_id
        - task_status
      properties:
        task_id:
          type: string
          description: Kling task ID.
        task_status:
          type: string
          description: >-
            Current task state. Compatible Motion Control tasks use `submitted`,
            `processing`, `succeed`, or `failed`.
        task_status_msg:
          type: string
          description: Failure or status detail when returned.
        task_info:
          type: object
          description: Additional task metadata. The object can be empty.
          additionalProperties: true
        task_result:
          type: object
          description: >-
            Absent on an initial submitted task, commonly empty while processing
            or after failure, and populated when a task succeeds.
          properties:
            videos:
              type: array
              description: Generated videos when the workflow returns video output.
              items:
                $ref: '#/components/schemas/KlingTaskVideo'
          additionalProperties: true
        watermark_info:
          type: object
          description: Watermark information when returned by a compatible workflow.
          properties:
            enabled:
              type: boolean
              description: Boolean value returned in `watermark_info`.
          additionalProperties: false
        created_at:
          type: integer
          format: int64
          description: Task creation timestamp in milliseconds.
        updated_at:
          type: integer
          format: int64
          description: Last task update timestamp in milliseconds.
        final_unit_deduction:
          type: string
          description: Final unit deduction value, when returned.
        final_balance_deduction:
          $ref: '#/components/schemas/KlingFinalBalanceDeduction'
    KlingTaskEnvelope:
      type: object
      required:
        - code
        - message
        - request_id
        - data
      properties:
        code:
          type: integer
          description: Kling response code. 0 indicates that the query was accepted.
        message:
          type: string
          description: Kling response message.
        request_id:
          type: string
          description: Identifier for this query request.
        data:
          $ref: '#/components/schemas/KlingTask'
    KlingTaskVideo:
      type: object
      properties:
        id:
          type: string
          description: Generated video ID.
        url:
          type: string
          format: uri
          description: Generated video delivery URL.
        watermark_url:
          type: string
          format: uri
          description: Watermarked video delivery URL when the task returns one.
        duration:
          type: string
          description: Video duration in seconds.
    KlingFinalBalanceDeduction:
      type: object
      description: Final balance deduction values, when returned.
      required:
        - quota
        - list_price
      properties:
        quota:
          type: string
          description: Final quota value.
        list_price:
          type: string
          description: Final list-price value.
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication. Use your CometAPI key.

````