> ## Documentation Index
>
> Fetch the complete documentation index at: https://kling.ai/document-api/llms.txt
> Use this file to discover all available pages before exploring further.

# Omni Video Generation

> Source: https://kling.ai/document-api/api/video/4-0/video-omni
> Locale: en
> Current Tab: Omni Video Generation
> Sibling Tabs: Text to Video / Image to Video / Omni Video Generation / Element Management / Voice Management
> This content is optimized for LLMs. In-page tabs are expanded and UI-only controls are omitted.

---

## Create Task

### API Overview

- Method: `POST`
- Path: `/omni-video/kling-4.0`
- Auth: `Authorization: Bearer <API_KEY>`
- Content-Type: `application/json`

### Headers

| Field | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `Content-Type` | string | Yes | `application/json` | - | Data Exchange Format |
| `Authorization` | string | Yes | - | - | Authentication information, refer to API authentication |

### Request Body

| Field Path | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `contents` | array | Yes | - | - | Reference input collection, including prompt, images, videos, Elements and voice |
| `contents[].type` | string | Yes | - | `prompt`, `first_frame`, `middle_frame`, `last_frame`, `refer_image`, `feature_video`, `base_video`, `element`, `voice` | Input type. Supports: prompt, images, videos, Element and voice |
| `settings` | object | No | - | - | Output configuration-related parameters, such as resolution, duration, etc |
| `settings.resolution` | string | No | `1080p` | `720p`, `1080p` | The resolution of the generated video |
| `settings.aspect_ratio` | string | No | `adaptive` | `21:9`, `16:9`, `9:16`, `1:1`, `adaptive` | The aspect ratio (width:height) of the generated video frames |
| `settings.duration` | int | No | `10` | `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `17`, `18`, `19`, `20`, `21`, `22`, `23`, `24`, `25`, `26`, `27`, `28`, `29`, `30` | Video length, unit: s (seconds) |
| `options` | object | No | - | - | General configurations, such as callback address, whether to include watermark, etc |
| `options.callback_url` | string | No | - | - | Callback notification URL for task result |
| `options.external_task_id` | string | No | - | - | Customized Task ID |
| `options.watermark_info` | object | No | - | - | Whether to generate watermarked results simultaneously |
| `options.watermark_info.enabled` | boolean | No | `false` | - | true: generate watermarked result; false: do not generate |

#### Request Body Field Notes

- `contents`: The reference format is as follows, with detailed parameter descriptions provided below:
- `contents`: ```json
  "contents": [
    {
      "type": "prompt",
      "text": "string"
    },
    {
      "type": "first_frame",
      "url": "string",
      "id": "string"
    },
    {
      "type": "middle_frame",
      "url": "string",
      "id": "string"
    },
    {
      "type": "last_frame",
      "url": "string",
      "id": "string"
    },
    {
      "type": "refer_image",
      "url": "string",
      "id": "string"
    },
    {
      "type": "feature_video",
      "url": "string",
      "id": "string"
    },
    {
      "type": "base_video",
      "url": "string",
      "id": "string"
    },
    {
      "type": "element",
      "element_id": "string",
      "id": "string"
    },
    {
      "type": "voice",
      "voice_id": "string",
      "id": "string"
    }
  ]
  ```
- `contents[].type.prompt`: English-only input supports up to 26,000 characters, and non-English-only input supports up to 11,000 characters. Mixed input must satisfy E / 26000 + N / 11000 <= 1, where E is the number of English characters and N is the number of non-English characters.
- `contents[].type.prompt`: Defined in JSON format, as follows:
- `contents[].type.prompt`: ```json
  {
    "type": "prompt", // Input type, fixed parameter value: prompt; required
    "text": "string" // Text prompt content; required
  }
  ```
- `contents[].type.prompt`: > **The Kling 4.0 API supports multi-reference video generation and video editing through prompts that describe reference roles, scene content, event sequences, and audio requirements.**
  >
  > 
  > 1. **Reference input materials using custom IDs.** When defining an image, video, or element object in `contents`, assign it an `id` and use `@id` to reference it in the prompt. For example, set `"id": "image_1"` on a `refer_image` object, then reference it as `@image_1`. IDs must be unique within the same task.
  >
  > 
  > 2. **Specify the purpose and scope of each reference.** For example: “Preserve the person’s facial features, hairstyle, and clothing from `@image_1`” or “Follow the movement rhythm in `@video_1` without using its background.” If a material is referenced without an explicit purpose, the model will infer how to use it, which may produce results that differ from your intent.
  >
  > 
  > 3. **Organize prompts around reference roles, overall settings, event sequences, and audio requirements.** Describe the scene, visual style, camera movement, action sequence, dialogue, ambient sounds, music, and sound effects as needed. For video editing, explicitly specify what to change and what to preserve. For more details, see the [Kling 4.0 User Guide](https://kling.ai/quickstart/kling-4-model-user-guide).
- `contents[].type.first_frame / middle_frame / last_frame / refer_image`: Images can be used as reference images for scenes, styles, etc., and can also be used as keyframes to generate videos.
- `contents[].type.first_frame / middle_frame / last_frame / refer_image`: Defined in JSON format, as follows:
- `contents[].type.first_frame / middle_frame / last_frame / refer_image`: ```json
  {
    "type": "string", // Image input identifier. Must match enum values: first_frame, middle_frame, last_frame, refer_image; required
    "url": "string", // The input content can be provided through URL or base64; required
    "id": "string" // Reference ID for this input, used to reference it in the prompt (for example, @image_1); must be unique within the task
  }
  ```
- `contents[].type.first_frame / middle_frame / last_frame / refer_image`: Image format: .jpg, .jpeg, .png.
- `contents[].type.first_frame / middle_frame / last_frame / refer_image`: The size of the image file cannot exceed 30MB.
- `contents[].type.first_frame / middle_frame / last_frame / refer_image`: The width and height dimensions of the image should not be less than 300px, and the aspect ratio of the image should be between 2:5 and 5:2.
- `contents[].type.first_frame / middle_frame / last_frame / refer_image`: The id field is required when multiple middle_frame or refer_image inputs are provided.
- `contents[].type.first_frame / middle_frame / last_frame / refer_image`: Maximum number of images: 10.
- `contents[].type.first_frame / middle_frame / last_frame / refer_image`: The combined number of images, videos, Elements and voices must not exceed 15.
- `contents[].type.feature_video / base_video`: feature_video is a feature reference video, and base_video is a video to be edited.
- `contents[].type.feature_video / base_video`: Defined in JSON format, as follows:
- `contents[].type.feature_video / base_video`: ```json
  {
    "type": "string", // Video input identifier. Must match enum values: feature_video, base_video; required
    "url": "string", // input content can be provided through URLs; required
    "id": "string" // Reference ID for this input, used to reference it in the prompt (for example, @video_1); must be unique within the task; optional
  }
  ```
- `contents[].type.feature_video / base_video`: Video format: .mp4, .mov.
- `contents[].type.feature_video / base_video`: The video file size cannot exceed 300MB.
- `contents[].type.feature_video / base_video`: The duration of each video and the total video duration must both be between 3 seconds (inclusive) and 30 seconds (inclusive). The total duration includes feature_video, base_video and video character Elements.
- `contents[].type.feature_video / base_video`: The width and height dimensions of the video should be between 700px (inclusive) and 4553px (inclusive), with a total pixel area not exceeding 8294400. The aspect ratio of the video should be between 2:5 and 5:2.
- `contents[].type.feature_video / base_video`: Supported input frame rate: 24–60 fps. Generated videos use 24 fps.
- `contents[].type.feature_video / base_video`: Reference video limits:
    - Without video character Elements, up to 5 reference videos are supported.
    - With video character Elements, the combined number of reference videos and video character Elements must not exceed 5.
    - At most 1 base_video is supported.
- `contents[].type.feature_video / base_video`: The combined number of images, videos, Elements and voices must not exceed 15.
- `contents[].type.element`: Defined in JSON format, as follows:
- `contents[].type.element`: ```json
  {
    "type": "element", // Input type, fixed parameter value: element; required
    "element_id": "string", // The element ID, generated by the system, is returned by querying the element related API; required
    "id": "string" // Reference ID for this input, used to reference it in the prompt (for example, @element_1); must be unique within the task; required
  }
  ```
- `contents[].type.element`: Elements are divided into video character Elements (customized from video) and multi-image Elements (customized from images). Their applicable scopes differ.
- `contents[].type.element`: Element limits:
    - Up to 7 Elements are supported, including no more than 3 video character Elements.
    - With video character Elements, the combined number of video character Elements and reference videos must not exceed 5.
- `contents[].type.element`: The combined number of images, videos, Elements and voices must not exceed 15.
- `contents[].type.element`: For more information about the official Element, please refer to the [Kling Element Library User Guide](https://kling.ai/quickstart/klingai-element-library-3-user-guide).
- `contents[].type.voice`: Defined in JSON format, as follows:
- `contents[].type.voice`: ```json
  {
    "type": "voice", // Input type, fixed parameter value: voice; required
    "voice_id": "string", // Voice ID, generated by the system, is returned through custom voice API; required
    "id": "string" // Reference ID for this input, used to reference it in the prompt (for example, @1); must be unique within the task; required
  }
  ```
- `contents[].type.voice`: At most 3 voices can be referenced.
- `contents[].type.voice`: The voice_id is returned by the Custom Voice API, or you can use a system preset voice. See [Voice Customization](https://kling.ai/document-api/api/video/3-0-omni/voice-customization) for details.
- `settings.resolution`: 720p: output video with a resolution of 720P
- `settings.resolution`: 1080p: output video with a resolution of 1080P
- `settings.aspect_ratio`: When an explicit aspect ratio is provided, the specified ratio takes precedence.
- `settings.aspect_ratio`: When this parameter is omitted or set to adaptive, the model detects and follows the aspect ratio intent in the Prompt, for example, "Generate a 9:16 vertical video."
- `settings.aspect_ratio`: If no explicit aspect ratio intent is detected in the Prompt, the output ratio is determined in order from the base_video, keyframe images, and other input videos. If none apply, the default ratio of 16:9 is used. When multiple keyframes are provided, the first-frame ratio takes precedence; if no first frame is provided, the ratio of the first keyframe image is used.
- `settings.duration`: When this parameter is provided, the specified duration takes precedence.
- `settings.duration`: When this parameter is omitted, the model detects and follows the duration intent in the Prompt, for example, "Generate a 15-second video."
- `settings.duration`: If no explicit duration intent is detected in the Prompt, the duration of the base_video takes precedence; if no base_video is provided, the default duration of 10 seconds is used.
- `options.callback_url`: If configured, the server will actively notify when the task status changes
- `options.callback_url`: For specific message schema, see [Callback Protocol](https://kling.ai/document-api/api/get-started/callbacks)
- `options.external_task_id`: Will not overwrite the system-generated task ID, but can be used for task queries
- `options.external_task_id`: Must be unique within a single user account
- `options.watermark_info`: Defined through the enabled parameter:
  ```json
  "watermark_info": {
    "enabled": false // true: generate watermarked result; false: do not generate; default: false
  }
  ```
- `options.watermark_info`: Custom watermarks are not currently supported

### Request Example

```bash
curl --location 'https://api-singapore.klingai.com/omni-video/kling-4.0' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${KLING_API_KEY}" \
  --data '{
    "contents": [
      {
        "type": "prompt",
        "text": "Change the color of the parrot’s feathers to match the reference image. Keep all other elements of the video unchanged."
      },
      {
        "type": "first_frame",
        "url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-tob-release_note/image_7.1.png",
        "id": "image_1"
      },
      {
        "type": "refer_image",
        "url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-tob-release_note/image_7.1.png",
        "id": "image_2"
      }
    ],
    "settings": {
      "resolution": "1080p",
      "duration": 10,
      "aspect_ratio": "adaptive"
    },
    "options": {
      "callback_url": "https://xxx/callback",
      "external_task_id": ""
    }
  }'
```

### Response Example

```json
{
  "code": 0, // Error code. See Error Codes for details
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system
  "data": {
    "id": "string", // The task ID generated by the system
    "status": "string", // Task status, Enum values: submitted, processing, succeeded, failed
    "create_time": 1781080778802, // Task creation time, Unix timestamp, unit ms
    "update_time": 1781080794151, // Task update time, Unix timestamp, unit ms
    "external_id": "string" // The custom task ID for this task (if any)
  }
}
```

## More Scenario Examples

### Feature Reference Video

```cURL
curl --location --request POST \
  'https://api-singapore.klingai.com/omni-video/kling-4.0' \
  --header "Authorization: Bearer ${KLING_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "contents": [
      {
        "type": "prompt",
        "text": "Reference the fighting movements and attack rhythm from @video_1, and use @image_1 and @image_2 for the character designs."
      },
      {
        "type": "feature_video",
        "url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-tob-release-note/ch12_2_fight_motion_source.mp4",
        "id": "video_1"
      },
      {
        "type": "refer_image",
        "url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-tob-release-note/ch12_2_dark_hair_fighter_ref.png",
        "id": "image_1"
      },
      {
        "type": "refer_image",
        "url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-tob-release-note/ch12_2_silver_hair_fighter_ref.png",
        "id": "image_2"
      }
    ],
    "settings": {
      "duration": 15,
      "resolution": "1080p",
      "aspect_ratio": "adaptive"
    }
  }'
```

### Video Editing

```cURL
curl --location --request POST \
  'https://api-singapore.klingai.com/omni-video/kling-4.0' \
  --header "Authorization: Bearer ${KLING_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "contents": [
      {
        "type": "prompt",
        "text": "Edit @video_1. When the box is opened again at the end of the video, @element_1 is sleeping inside. Replace the final line “Ah, it'\''s all old stuff.” with “Why is there a pig here?”"
      },
      {
        "type": "base_video",
        "url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-tob-release-note/ch12_6_box_source.mp4",
        "id": "video_1"
      },
      {
        "type": "element",
        "element_id": "164",
        "id": "element_1"
      }
    ],
    "settings": {
      "duration": 10,
      "resolution": "1080p",
      "aspect_ratio": "adaptive"
    }
  }'
```

### Voice Reference

```cURL
curl --location 'https://api-singapore.klingai.com/omni-video/kling-4.0' \
  --header "Authorization: Bearer ${KLING_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "contents": [
      {
        "type": "prompt",
        "text": "Use @image_1 as the character reference. A girl sits by the window on a moving train, quietly gazing outside with a melancholic expression. After a few moments, the camera slowly pulls back, revealing more of the train carriage and other passengers. The girl stands up from her seat and carefully walks down the aisle. As she passes another passenger, she turns slightly and politely says in English using @1: \"Excuse me.\" Natural body movements, realistic facial expressions, accurate lip synchronization, cinematic lighting, continuous camera movement."
      },
      {
        "type": "refer_image",
        "url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-tob-release_note/image_25.png",
        "id": "image_1"
      },
      {
        "type": "voice",
        "voice_id": "829826751244537879",
        "id": "1"
      }
    ],
    "settings": {
      "resolution": "1080p",
      "duration": 5,
      "aspect_ratio": "9:16"
    },
    "options": {
      "watermark_info": {
        "enabled": false
      }
    }
  }'
```

---

## Query Task (By task ID)

### API Overview

- Method: `GET`
- Path: `/tasks`
- Auth: `Authorization: Bearer <API_KEY>`
- Content-Type: `application/json`

### Description

> Note: The API currently supports querying async tasks only

### Headers

| Field | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `Content-Type` | string | Yes | `application/json` | - | Data Exchange Format |
| `Authorization` | string | Yes | - | - | Authentication information, refer to API authentication |

### Query Params

| Field | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `task_ids` | string | No | - | - | The task ID defined by the system that needs to be queried |
| `external_task_ids` | string | No | - | - | The custom task ID that needs to be queried |

#### Query Params Field Notes

- `task_ids`: Query parameter; provide the value in the URL query string
- `task_ids`: When querying a task, you can choose between two query methods: task_ids and external_task_ids, but you cannot use them simultaneously
- `task_ids`: Support batch queries, separated by ","
- `external_task_ids`: Query parameter; provide the value in the URL query string
- `external_task_ids`: When querying a task, you can choose between two query methods: task_ids and external_task_ids, but you cannot use them simultaneously
- `external_task_ids`: Support batch queries, separated by ","

### Request Example

```bash
curl --location 'https://api-singapore.klingai.com/tasks?external_task_ids=123' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${KLING_API_KEY}"
```

### Response Example

```json
{
  "code": 0, // Error code. See Error Codes for details
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system, is used to track requests and troubleshoot problems
  "data": [
    {
      "id": "893605946402811985", // The task ID being queried
      "status": "string", // Task status, Enum values: submitted, processing, succeeded, failed
      "message": "string", // Task status information, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.)
      "create_time": 1781080778802, // Task creation time, Unix timestamp, unit ms
      "update_time": 1781080794151, // Task update time, Unix timestamp, unit ms
      "external_id": "string", // The custom task ID for this task (if any)
      "outputs": [
        {
          "type": "video", // When the generated result is "video", the return value and related fields vary by content type. Enum values: image, video, audio, element, voice
          "id": "string", // Video ID, generated by the system
          "url": "string", // Generated result URL with hotlink protection. (Generated results are retained for 30 days; save them promptly.)
          "watermark_url": "string", // URL for generating result with watermark, hotlink protection format
          "duration": "string" // The duration of the generated video, in seconds
        },
        {
          "type": "image", // When the generated result is "image", the return value and related fields vary by content type. Enum values: image, video, audio, element, voice
          "url": "string", // Generated result URL with hotlink protection. (Generated results are retained for 30 days; save them promptly.)
          "watermark_url": "string", // Image download URL with watermark, protected URL
          "group_id": "string" // Only appears when generating grouped images, used to mark grouping relationships
        },
        {
          "type": "audio", // When the generated result is "audio", the return value and related fields vary by content type. Enum values: image, video, audio, element, voice
          "id": "string", // Audio ID, generated by the system
          "mp3_url": "string", // Generated MP3 URL with hotlink protection. (Generated results are retained for 30 days; save them promptly.)
          "wav_url": "string", // Generated WAV URL with hotlink protection. (Generated results are retained for 30 days; save them promptly.)
          "mp3_duration": "string", // The duration of the generated MP3 format audio, in seconds
          "wav_duration": "string" // The duration of the generated WAV format audio, in seconds
        },
        {
          "type": "voice", // When the generated result is "voice", the return value and related fields vary by content type. Enum values: image, video, audio, element, voice
          "id": "string", // Voice ID, generated by the system
          "name": "string", // Voice name
          "url": "string", // Material download link
          "owned_by": "string", // Voice source, kling is the official voice library, and the number is the creator ID
          "status": "succeeded" // Voice status. Enum values: succeeded, deleted
        },
        {
          "type": "element", // When the generated result is "element", the return value and related fields vary by content type. Enum values: image, video, audio, element, voice
          "id": "string", // Element ID, generated by the system
          "name": "string", // Element name
          "description": "string", // Element description
          "element_type": "string", // Element type, divided into video character element and multi-image element, enumeration values are: video_character_elements and multi_image_elements
          "references": [ // Related materials of element
            {
              "type": "image", // When returning 'image' materials, the enumeration values for each content type are: image, video, voice
              "role": "string", // Image reference material attributes are divided into frontal reference images and other reference images, with enumeration values of frontal and reference, respectively
              "url": "string" // Material download link
            },
            {
              "type": "video", // When returning "video" materials, the enumeration values for each content type are: image, video, voice
              "role": "refer", // Video reference material attribute, fixed value: refer
              "url": "string" // Material download link
            },
            {
              "type": "voice", // When "voice" material is returned, enumeration values of each content type: image, video, voice
              "role": "refer", // Voice reference material attribute, fixed value: refer
              "url": "string", // Material download link
              "id": "string", // Voice ID
              "name": "string", // Voice name
              "owned_by": "string" // Voice source. kling means official voice library; numbers are creator IDs
            }
          ],
          "owned_by": "string", // Element source. kling means the official Element library; numbers are creator IDs
          "status": "string", // Element status. Enum values: succeeded, deleted
          "tags": [ // Element label related information
            {
              "id": 1, // Tag ID
              "name": "string", // Tag name
              "description": "string" // Tag description
            }
          ]
        }
      ],
      "usage": { // Usage: returned only after the task ends and usage is available; otherwise omitted
        "input_duration": "8.03" // Total input video duration in seconds, as a string with two decimals; Kling 4.0 with video input only
      },
      "billing": [
        {
          "charge_type": "string", // Consumption account type: If the consumption is of balance, the parameter value is "cash"; if it is of resource package, the parameter value is "unit"
          "cash_type": "string", // Balance type, only exists in the consumption limit scenario (charge_type=cash). If the consumption is the official quota, the parameter value is balance. If the consumption is the test quota, the parameter value is test_balance
          "amount": "string", // Deduction amount; In the balance deduction situation (charge_type=cash), it represents the discount price deducted from the balance, and in the resource package deduction situation (charge_type=unit), it represents the deduction amount of units; decimal system
          "currency": "string", // Consumption unit, which only exists in the consumption balance scenario (charge_type=cash), with a fixed parameter value of CNY/USD
          "package_type": "string", // Consumable resource bundle type, which only exists in the consumable resource bundle scenario (charge_type=unit), with fixed enumeration values: video, image, audio
          "list_price": "string" // Balance deduction list price only exists in the consumption limit scenario (charge_type=cash)
        }
      ]
    }
  ]
}
```

---

## Query Task (By Cursor)

### API Overview

- Method: `POST`
- Path: `/tasks`
- Auth: `Authorization: Bearer <API_KEY>`
- Content-Type: `application/json`

### Description

> Note: The API currently supports querying async tasks only

### Headers

| Field | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `Content-Type` | string | Yes | `application/json` | - | Data Exchange Format |
| `Authorization` | string | Yes | - | - | Authentication information, refer to API authentication |

### Request Body

| Field Path | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `start_time` | string | No | `end_time - 30 days` | - | Start time for task creation filtering |
| `end_time` | string | No | `current time` | - | End time for task creation filtering |
| `cursor` | string | No | - | - | Continuation cursor, i.e. query starting point |
| `limit` | int | No | `100` | - | Query the number of tasks |
| `filters` | array | No | - | - | Query task filtering criteria, such as task status and function type |
| `filters[].key` | string | No | - | `status`, `product_type` | Filtering dimensions, currently supporting filtering based on task status and other conditions |
| `filters[].values` | array | No | - | - | Filter value |

#### Request Body Field Notes

- `start_time`: Unix timestamp, in milliseconds
- `start_time`: The default value is end_time - 30 days
- `start_time`: Start time must be earlier than end time
- `end_time`: The default value is current time
- `end_time`: Unix timestamp, in milliseconds
- `end_time`: End time must be later than start time
- `cursor`: Use the next_cursor returned by the previous query
- `cursor`: When cursor is not empty, start_time and end_time are ignored
- `limit`: Maximum value: 500
- `filters`: Load with key/value format:
  ```json
  "filters": [
    {
      "key": "status", // Filter dimension by task status, fixed value: status
      "values": ["succeeded"]
    },
    {
      "key": "product_type", // Filter dimension by function type, fixed value: product_type
      "values": ["video"]
    }
  ]
  ```
- `filters[].key`: status: filter by task status
  - product_type: filter by function type
- `filters[].values`: status: submitted, processing, succeeded, failed
- `filters[].values`: product_type: video, image, try_on

### Request Example

```bash
curl --location 'https://api-singapore.klingai.com/tasks' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${KLING_API_KEY}" \
  --data '{
    "start_time": "1781193600000",
    "end_time": "1781516352968",
    "cursor": "",
    "limit": 500,
    "filters": [
      {
        "key": "status",
        "values": ["succeeded"]
      },
      {
        "key": "product_type",
        "values": ["video"]
      }
    ]
  }'
```

### Response Example

```json
{
  "code": 0, // Error code. See Error Codes for details
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system
  "data": {
    "result": [
      {
        "id": "string", // The task ID being queried
        "status": "string", // Task status, Enum values: submitted, processing, succeeded, failed
        "message": "string", // Task status information, displaying the failure reason when the task fails
        "create_time": 1781080778802, // Task creation time, Unix timestamp, unit ms
        "update_time": 1781080794151, // Task update time, Unix timestamp, unit ms
        "external_id": "string", // The custom task ID for this task (if any)
        "outputs": [
        {
          "type": "video", // When the generated result is "video", the return value and related fields vary by content type. Enum values: image, video, audio, element, voice
          "id": "string", // Video ID, generated by the system
          "url": "string", // Generated result URL with hotlink protection. (Generated results are retained for 30 days; save them promptly.)
          "watermark_url": "string", // URL for generating result with watermark, hotlink protection format
          "duration": "string" // The duration of the generated video, in seconds
        },
        {
          "type": "image", // When the generated result is "image", the return value and related fields vary by content type. Enum values: image, video, audio, element, voice
          "url": "string", // Generated result URL with hotlink protection. (Generated results are retained for 30 days; save them promptly.)
          "watermark_url": "string", // Image download URL with watermark, protected URL
          "group_id": "string" // Only appears when generating grouped images, used to mark grouping relationships
        },
        {
          "type": "audio", // When the generated result is "audio", the return value and related fields vary by content type. Enum values: image, video, audio, element, voice
          "id": "string", // Audio ID, generated by the system
          "mp3_url": "string", // Generated MP3 URL with hotlink protection. (Generated results are retained for 30 days; save them promptly.)
          "wav_url": "string", // Generated WAV URL with hotlink protection. (Generated results are retained for 30 days; save them promptly.)
          "mp3_duration": "string", // The duration of the generated MP3 format audio, in seconds
          "wav_duration": "string" // The duration of the generated WAV format audio, in seconds
        },
        {
          "type": "voice", // When the generated result is "voice", the return value and related fields vary by content type. Enum values: image, video, audio, element, voice
          "id": "string", // Voice ID, generated by the system
          "name": "string", // Voice name
          "url": "string", // Material download link
          "owned_by": "string", // Voice source, kling is the official voice library, and the number is the creator ID
          "status": "succeeded" // Voice status. Enum values: succeeded, deleted
        },
        {
          "type": "element", // When the generated result is "element", the return value and related fields vary by content type. Enum values: image, video, audio, element, voice
          "id": "string", // Element ID, generated by the system
          "name": "string", // Element name
          "description": "string", // Element description
          "element_type": "string", // Element type, divided into video character element and multi-image element, enumeration values are: video_character_elements and multi_image_elements
          "references": [ // Related materials of element
            {
              "type": "image", // When returning 'image' materials, the enumeration values for each content type are: image, video, voice
              "role": "string", // Image reference material attributes are divided into frontal reference images and other reference images, with enumeration values of frontal and reference, respectively
              "url": "string" // Material download link
            },
            {
              "type": "video", // When returning "video" materials, the enumeration values for each content type are: image, video, voice
              "role": "refer", // Video reference material attribute, fixed value: refer
              "url": "string" // Material download link
            },
            {
              "type": "voice", // When "voice" material is returned, enumeration values of each content type: image, video, voice
              "role": "refer", // Voice reference material attribute, fixed value: refer
              "url": "string", // Material download link
              "id": "string", // Voice ID
              "name": "string", // Voice name
              "owned_by": "string" // Voice source. kling means official voice library; numbers are creator IDs
            }
          ],
          "owned_by": "string", // Element source. kling means the official Element library; numbers are creator IDs
          "status": "string", // Element status. Enum values: succeeded, deleted
          "tags": [ // Element label related information
            {
              "id": 1, // Tag ID
              "name": "string", // Tag name
              "description": "string" // Tag description
            }
          ]
        }
      ],
        "usage": { // Usage: returned only after the task ends and usage is available; otherwise omitted
          "input_duration": "8.03" // Total input video duration in seconds, as a string with two decimals; Kling 4.0 with video input only
        },
        "billing": [
          {
            "charge_type": "string", // Consumption account type: cash for balance, unit for resource package
            "cash_type": "string", // Balance type, only exists in the consumption limit scenario (charge_type=cash). If the consumption is the official quota, the parameter value is balance. If the consumption is the test quota, the parameter value is test_balance
            "amount": "string", // Deduction amount; In the balance deduction situation (charge_type=cash), it represents the discount price deducted from the balance, and in the resource package deduction situation (charge_type=unit), it represents the deduction amount of units; decimal system
            "currency": "string", // Consumption unit, which only exists in the consumption balance scenario (charge_type=cash), with a fixed parameter value of CNY/USD
            "package_type": "string", // Consumable resource bundle type, which only exists in the consumable resource bundle scenario (charge_type=unit), with fixed enumeration values: video, image, audio
            "list_price": "string" // Balance deduction list price only exists in the consumption limit scenario (charge_type=cash)
          }
        ]
      }
    ],
    "count": 1, // Number of query results
    "next_cursor": "string", // Cursor for querying subsequent results
    "has_more": true // Whether there are more results based on cursor information
  }
}
```