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

# Kling 3.0

Generate high-quality videos with advanced multi-shot capabilities and element references using Kling 3.0 AI.

Kling 3.0 is an advanced video generation model that supports both single-shot and multi-shot video creation with element references. It offers multiple generation modes with different resolution options and supports sound effects for enhanced video output.

## Key Features

* **Multiple Generation Modes**: Choose between `std` (standard resolution), `pro` (higher resolution), and `4K` (ultra-high resolution) modes.
* **Multi-Shot Support**: Create videos with multiple shots, each with its own prompt and duration.
* **Element Reference**: Use the `@element_name` syntax to reference image, video, or audio elements within prompts.
* **Sound Effects**: Optionally add sound effects to enhance video output.
* **Flexible Aspect Ratios**: Supports `16:9`, `9:16`, and `1:1` aspect ratios.
* **Configurable Duration**: Create videos with durations from 3 to 15 seconds.

## Resolution Mappings

The resolution depends on both the `mode` and `aspect_ratio` parameters.

### Standard Mode (`std`)

| Aspect Ratio | Resolution |
| ------------ | ---------- |
| `16:9`       | `1280×720` |
| `9:16`       | `720×1280` |
| `1:1`        | `720×720`  |

### Pro Mode (`pro`)

| Aspect Ratio | Resolution  |
| ------------ | ----------- |
| `16:9`       | `1920×1080` |
| `9:16`       | `1080×1920` |
| `1:1`        | `1080×1080` |

### 4K Mode (`4K`)

| Aspect Ratio | Resolution  |
| ------------ | ----------- |
| `16:9`       | `3840×2160` |
| `9:16`       | `2160×3840` |
| `1:1`        | `2160×2160` |

<Info>
  4K mode provides higher resolution output but may take longer to generate and consume more credits.
</Info>

## Single-Shot vs Multi-Shot Mode

### Single-Shot Mode (`multi_shots: false`)

* Uses the main `prompt` field for video generation.
* Supports first and last frame images via `image_urls`.
* Sound effects are optional.

### Multi-Shot Mode (`multi_shots: true`)

* Uses the `multi_prompt` array to define multiple shots.
* Each shot has its own prompt and duration of **1–12 seconds**.
* Only supports the first frame image via `image_urls[0]`.
* Sound effects are enabled by default.
* The maximum number of characters per shot is **500**.

## Aspect Ratio Auto-Adaptation

When you provide `image_urls` for the first and/or last frame images, the `aspect_ratio` parameter becomes optional.

The system automatically adapts the aspect ratio based on the uploaded images, so you don't need to specify it manually.

<Info>
  If you upload reference images, you can omit the `aspect_ratio` parameter and let the system automatically match the aspect ratio of your images.
</Info>

## Element References

You can reference element in your prompts using the `@element_name` syntax. Define elements in the `kling_elements` array:

**Image Elements:** Provide **2–4 image URLs**.

Supported formats:

* `JPG`
* `PNG`

Each image can be up to **10 MB**.

**Video Elements:** Provide up to **1 video URL**.

Supported formats:

* `MP4`
* `MOV`

Requirements:

* The video duration must be at least **3 seconds**.
* The effective segment length should be between **3 and 8 seconds**.

**Audio Reference:** Provide up to **1 audio URL**.

Requirements:

* The audio duration must be between **5 and 30 seconds**.

<Info>
  Use descriptive element names and ensure the element name in `kling_elements` matches the name used in your prompt (without the @ symbol). A single task can reference a maximum of 3 elements, and each `@element` will occupy 37 characters.
</Info>

### Request Body

| Field   | Type   | Required | Description                                     |
| ------- | ------ | -------- | ----------------------------------------------- |
| `model` | string | Yes      | The model used for video generation.            |
| `input` | object | Yes      | Input parameters for the video generation task. |

<ParamField body="model" type="string" required>
  Must be `kling-3.0/video`.
</ParamField>

<ParamField body="input" type="object" required>
  ## Input Parameters

  The `input` object contains the parameters used to generate the video.

  <ParamField body="prompt" type="string" required>
    The `prompt` for generating a video. Used when `multi_shots` is set to `false`.
  </ParamField>

  <ParamField body="image_url" type="string[]">
    First and last frame image URLs.

    This field is required when elements are referenced in the prompt using the `@element_name` syntax.

    #### Single-Shot Mode (`multi_shots: false`)

    * When the array contains **2 images**:
      * `image_urls[0]` is the first frame.
      * `image_urls[1]` is the last frame.
    * When the array contains **1 image**:
      * The image is used as the first frame.

    #### Multi-Shot Mode (`multi_shots: true`)

    Only the first frame is supported.
  </ParamField>

  <ParamField body="duration" type="string">
    Use `duration` to specify the length of the total video duration in seconds.

    Supported values:

    * `"3"` to `"15"`

    Default value: `"5"`
  </ParamField>

  <ParamField body="sound" type="boolean">
    **Default:** `false`

    Controls whether sound effects are enabled for the generated video.

    * `true` — Enables sound effects.
    * `false` — Disables sound effects.

    > When `multi_shots` is set to `true`, this field defaults to `true`.
  </ParamField>

  <ParamField body="aspect_ratio" default="16:9" type="string" required>
    Specifies the aspect ratio of the generated video.

    #### Allowed Values

    * `16:9`
    * `9:16`
    * `1:1`

    > When `image_urls` containing first and/or last frame images is provided, this parameter becomes optional. The system automatically adapts the aspect ratio based on the uploaded images.

    **Default:** `16:9`
  </ParamField>

  <ParamField body="multi_shots" default="false" type="boolean" required>
    Whether to use multi-shot mode. `true` enables multi-shot mode, while `false` enables single-shot mode.
  </ParamField>

  <ParamField body="multi_prompt" type="object[]" required>
    Shot prompts. Takes effect when `multi_shots` is `true`.

    Used to describe the text and duration of each shot. Supports up to **5 shots**. Each shot duration is **1–12 seconds**.

    ### Array Item Properties

    Each item in `multi_prompt` contains the following required properties.

    <ParamField body="prompt" type="string" required>
      Prompt text for this shot.

      **Maximum length:** 500 characters

      Each `@element` will occupy **37 characters**.
    </ParamField>

    <ParamField body="duration" type="number" required>
      Duration of this shot in seconds.

      | Constraint | Value |
      | ---------- | ----: |
      | Minimum    |   `1` |
      | Maximum    |  `12` |

      **Range:** `1–12` seconds
    </ParamField>
  </ParamField>

  <ParamField body="kling_elements" type="object[]" required>
    Referenced elements. Detailed information about elements referenced in the prompt. A single task can reference a maximum of three elements.

    **Maximum items:** 3

    ### Element Object

    Each element in the `kling_elements` array supports the following properties.

    <ParamField body="name" type="string" required>
      Element name used in the prompt with an `@` prefix.

      For example, if the element name is `element_dog`, reference it in the prompt as:

      ```text theme={null}
      @element_dog
      ```
    </ParamField>

    <ParamField body="description" type="string" required>
      Description of the element.
    </ParamField>

    <ParamField body="element_input_urls" type="string[]" required>
      Image or video URLs used as the source material for the element.

      * **2–4 URLs are required.**
      * Accepted image formats: `JPG`, `PNG`.
      * Maximum file size: `10 MB` per image.
    </ParamField>

    <ParamField body="element_input_audio_urls" type="string[]">
      Optional list of audio material URLs for characters.

      The audio duration must be between **5 and 30 seconds**.
    </ParamField>

    <ParamField body="start_time" type="number">
      Start time for video character material capture, specified in **milliseconds**.

      This parameter is only effective when uploading videos through `element_input_urls`.

      If no value is provided, it defaults to `0`.
    </ParamField>

    <ParamField body="end_time" type="number">
      End time for video character material capture, specified in **milliseconds**.

      This parameter is only effective when uploading videos through `element_input_urls`.

      The following requirements apply:

      * `end_time` must be greater than `start_time`.
      * The difference between `end_time` and `start_time` must be between **3000 and 8000 milliseconds**.
    </ParamField>
  </ParamField>
</ParamField>

## Usage Examples

### Single-Shot Video with Element Reference

```json theme={null}
{
  "model": "kling-3.0/video",
  "input": {
    "prompt": "In a bright rehearsal room, sunlight streams through the window @element_dog",
    "image_urls": [
      "https://example.com/demo/input-image.png"
    ],
    "sound": true,
    "duration": "5",
    "aspect_ratio": "16:9",
    "mode": "pro",
    "multi_shots": false,
    "kling_elements": [
      {
        "name": "element_dog",
        "description": "dog",
        "element_input_urls": [
          "https://example.com/demo/dog-1.jpg",
          "https://example.com/demo/dog-2.png"
        ]
      }
    ]
  }
}
```

### Multi-Shot Video

```json theme={null}
{
  "model": "kling-3.0/video",
  "input": {
    "multi_shots": true,
    "image_urls": [
      "https://example.com/demo/input-image.png"
    ],
    "duration": "5",
    "aspect_ratio": "16:9",
    "mode": "pro",
    "multi_prompt": [
      {
        "prompt": "A happy dog running with @element_cat",
        "duration": 3
      },
      {
        "prompt": "A happy dog playing with @element_cat",
        "duration": 3
      }
    ],
    "kling_elements": [
      {
        "name": "element_cat",
        "description": "cat",
        "element_input_urls": [
          "https://example.com/demo/cat-1.jpg",
          "https://example.com/demo/cat-2.png"
        ]
      },
      {
        "name": "element_dog",
        "description": "dog",
        "element_input_urls": [
          "https://example.com/demo/dog-1.jpg",
          "https://example.com/demo/dog-2.png"
        ]
      }
    ]
  }
}
```

## Response

### Successful Response

A successful request returns a task ID.

<ResponseField name="code" type="number">
  Response status code.
</ResponseField>

<ResponseField name="msg" type="string">
  Response message. Contains the error description when the request fails.

  **Example:** `success`
</ResponseField>

<ResponseField name="data" type="object" required>
  The task data object containing task id.

  <ResponseField name="taskId" type="string" required>
    The unique identifier for this task.

    **Example:** `task_123456`
  </ResponseField>
</ResponseField>

Use the returned `taskId` with the Get Task Details endpoint to check task progress and retrieve the generation results.

## Query Task Status

After submitting a task, use the unified query endpoint to check the task progress and retrieve the generated results.

<Card title="Get Task Details" icon="search" href="/get-task-detail">
  Check task status, monitor generation progress, and retrieve results.
</Card>

### Error Response

```json theme={null}
{
  "code": 500,
  "msg": "Server Error - An unexpected error occurred while processing the request",
  "data": null
}
```

## Response Codes

|  Code | Meaning                                                                   |
| ----: | ------------------------------------------------------------------------- |
| `200` | Success — the request was successfully processed.                         |
| `401` | Unauthorized — authentication credentials are missing or invalid.         |
| `402` | Insufficient Credits — the account does not have enough credits.          |
| `404` | Not Found — the requested resource or interface does not exist.           |
| `408` | Upstream service issue — no result has been returned for over 10 minutes. |
| `422` | Validation Error — request parameters failed validation.                  |
| `429` | Rate Limited — request frequency limit has been exceeded.                 |
| `433` | Request Limit — sub-key usage exceeded the limit.                         |
| `455` | Service Unavailable — system is undergoing maintenance.                   |
| `500` | Server Error — an unexpected error occurred while processing the request. |
| `501` | Generation Failed — content generation failed.                            |
| `505` | Feature Disabled — the requested feature is disabled.                     |