> ## 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 Omni Image to Video

## Authentication

All API requests require a Bearer Token.

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Create a Video Generation Task

Submit an image-to-video generation task using the endpoint below.

```http theme={null}
POST /api/v1/jobs/createTask
```

## Request Body

### Root Parameters

| Parameter | Type   | Required | Description                                       |
| --------- | ------ | -------- | ------------------------------------------------- |
| `model`   | string | Yes      | Must be `kling-3.0-omni/image-to-video`.          |
| `input`   | object | Yes      | Generation input. Supports the input modes below. |

<ParamField body="model" type="string" required>
  Must be `kling-3.0-omni/image-to-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. It must not be empty after leading and trailing whitespace is removed.

    **Maximum length:** `3,072` characters.
  </ParamField>

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

    Use the first image URL as the required first frame and the second image URL as the last frame of the video, with a smooth and natural transition between them.

    * 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.

    Supported image formats:

    * `image/jpeg`
    * `image/png`
    * `image/jpg`

    Maximum file size: `50 MB` Aspect ratio must be between `0.4` and `2.5`.
  </ParamField>

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

    Supported values:

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

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

  <ParamField body="resolution" type="string">
    Use `resolution` to specify the output video resolution.

    Supported values:

    * `720p`
    * `1080p`
    * `4k`
  </ParamField>

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

    Supported values:

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

    > `16:9`, `9:16`, and `1:1` are available only when `customize_multi_shots` is enabled. Otherwise, use `auto`.
  </ParamField>

  <ParamField body="customize_multi_shots" default="false" type="boolean">
    Set to `true` to define custom shots using `multi_prompt`.
  </ParamField>

  <ParamField body="prefer_multi_shots" default="false" type="boolean">
    Enables intelligent shot planning.

    > `prefer_multi_shots` and `customize_multi_shots` are mutually exclusive.
  </ParamField>

  <ParamField body="multi_prompt" type="object[]" required>
    When `customize_multi_shots=true`, this field is required.

    Used to describe the text and duration of each shot. Supports up to **6 shots**. Each shot duration is **1–15 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:** 512 characters
    </ParamField>

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

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

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

  <ParamField body="elements" type="object[]" required>
    The `elements` array defines one-time subject assets.

    Each subject is automatically identified as either a multi-image subject or a video character subject based on `element_input_urls`.

    **Maximum subjects:** `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>
      Subject description
    </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>

# Complete Request Examples

## Example 1: Single First Frame

```json theme={null}
{
  "model": "kling-3.0-omni/image-to-video",
  "input": {
    "prompt": "A happy golden retriever running across a grassy field",
    "image_urls": [
      "https://example.com/first-frame.jpg"
    ],
    "customize_multi_shots": true,
    "audio": false,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "duration": 5,
    "elements": []
  }
}
```

## Example 2: First and Last Frames

```json theme={null}
{
  "model": "kling-3.0-omni/image-to-video",
  "input": {
    "prompt": "A happy golden retriever running across a grassy field",
    "image_urls": [
      "https://example.com/first-frame.jpg",
      "https://example.com/last-frame.jpg"
    ],
    "customize_multi_shots": false,
    "audio": false,
    "resolution": "720p",
    "aspect_ratio": "auto",
    "duration": 5,
    "elements": []
  }
}
```

## Response

### Success Response

<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>

## Query Task Status

After submitting a task, you can check task progress and retrieve generation results through the unified task-details endpoint.

<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.                     |