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

# Text to Video

> Source: https://kling.ai/document-api/api/video/2-1-master/text-to-video
> Locale: en
> Current Tab: Text to Video
> Sibling Tabs: Text to Video / Image to Video
> This content is optimized for LLMs. In-page tabs are expanded and UI-only controls are omitted.

---

> This model or capability will be retired on September 15, 2026. Please migrate to a currently supported Kling AI model or service before this date.

## Create Task

### API Overview

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

### Description

> Please note that in order to maintain naming consistency, the original model field has been changed to model_name, so in the future, please use this field to specify the version of the model that needs to be called.
>
> At the same time, we keep the behavior forward-compatible. If you continue to use the original model field, it will not have any impact on the interface call, there will not be any exception, which is equivalent to the default behavior when model_name is empty (i.e., call the V1 model).

### Headers

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

### Request Body

| Field Path | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `model_name` | string | No | `kling-v1` | `kling-v1`, `kling-v1-6`, `kling-v2-master`, `kling-v2-1-master`, `kling-v2-5-turbo`, `kling-v2-6`, `kling-v3` | Model Name |
| `multi_shot` | boolean | No | `false` | - | Whether to generate multi-shot video |
| `shot_type` | string | No | - | `customize`, `intelligence` | Storyboard method |
| `prompt` | string | No | - | - | Positive text prompt |
| `multi_prompt` | array | No | - | - | Each storyboard cue can include both positive and negative descriptions |
| `negative_prompt` | string | No | - | - | Negative text prompt |
| `sound` | string | No | `off` | `on`, `off` | Is sound generated simultaneously when generating videos |
| `cfg_scale` | float | No | `0.5` | - | The degree of freedom for generating video; the larger the value, the smaller the degree of freedom of the model |
| `mode` | string | No | `std` | `std`, `pro`, `4k` | Video generation mode |
| `camera_control` | object | No | - | - | Terms of controlling camera movement (if not specified, the model will intelligently match based on the input text/images) |
| `camera_control.type` | string | No | - | `simple`, `down_back`, `forward_up`, `right_turn_forward`, `left_turn_forward` | Predefined camera movements type |
| `camera_control.config` | object | No | - | - | Contains 6 fields, used to specify the camera's movement or change in different directions |
| `camera_control.config.horizontal` | float | No | - | - | Horizontal, controls the camera's movement along the horizontal axis (translation along the x-axis) |
| `camera_control.config.vertical` | float | No | - | - | Vertical, controls the camera's movement along the vertical axis (translation along the y-axis) |
| `camera_control.config.pan` | float | No | - | - | Pan, controls the camera's rotation in the horizontal plane (rotation around the y-axis) |
| `camera_control.config.tilt` | float | No | - | - | Tilt, controls the camera's rotation in the vertical plane (rotation around the x-axis) |
| `camera_control.config.roll` | float | No | - | - | Roll, controls the camera's roll (rotation around the z-axis) |
| `camera_control.config.zoom` | float | No | - | - | Zoom, controls the camera's focal length change, affecting the distance of the field of view |
| `aspect_ratio` | string | No | `16:9` | `16:9`, `9:16`, `1:1` | The aspect ratio of the generated video frame (width:height) |
| `duration` | string | No | `5` | `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15` | Video Length, unit: s (seconds) |
| `watermark_info` | object | No | - | - | Whether to generate watermarked results simultaneously |
| `callback_url` | string | No | - | - | Callback notification URL for this task result. If configured, the server will actively notify when the task status changes |
| `external_task_id` | string | No | - | - | Customized Task ID |

#### Request Body Field Notes

- `multi_shot`: When true: the prompt parameter is invalid, and the first/end frame generation is not supported.
- `multi_shot`: When false: the shot_type and multi_prompt parameters are invalid
- `shot_type`: When multi_shot is true, this parameter is required
- `prompt`: > The Omni model can achieve various capabilities through Prompt with elements, images, videos, and other content:
  > - Specify elements/images/videos using <<<>>> format, e.g.: <<<element_1>>>, <<<image_1>>>, <<<video_1>>>
  > - For detailed capabilities, see: [KLING Omni Model User Guide](https://kling.ai/quickstart/klingai-video-o1-user-guide), [Kling VIDEO 3.0 Omni Model User Guide](https://kling.ai/quickstart/klingai-video-3-omni-model-user-guide)
- `prompt`: Cannot exceed 2500 characters
- `prompt`: Use <<<voice_1>>> to specify voice, same sequence as voice_list. Up to 2 voices; when specifying voice, sound must be on. Simpler grammar is better. For example: The man <<<voice_1>>> said, "Hello.". 
  - When voice_list is not empty and prompt references voice ID, task is billed as "with voice generation".
- `prompt`: When multi_shot is false or shot_type is intelligence, this parameter must not be empty.
- `prompt`: > The support range for different model versions and video modes varies. For details, see [Capability Map](https://kling.ai/document-api/guides/capability-map/video)
- `multi_prompt`: Define the shot sequence number, corresponding prompt word, and duration through the index, prompt, and duration parameters, where:
  - Supports up to 6 storyboards, with a minimum of 1 storyboard.
  - The maximum length of the prompt for each storyboard 512 characters.
  - The duration of each storyboard should not exceed the total duration, but should not be less than 1.
  - The sum of the durations of all storyboards equals the total duration of the current task.
- `multi_prompt`: Load with key:value format as follows:
  ```json
  "multi_prompt":[
  {"index":int,"prompt":"string","duration":"5"},
  {"index":int,"prompt":"string","duration":"5"}
  ]
  ```
- `multi_prompt`: When multi_shot is true and shot_type is customize, this parameter is required.
- `negative_prompt`: Cannot exceed 2500 characters
- `negative_prompt`: It is recommended to supplement negative prompt via negative sentences within positive prompts
- `sound`: > The support range for different model versions and video modes varies. For details, see [Capability Map](https://kling.ai/document-api/guides/capability-map/video)
- `cfg_scale`: Value range: [0, 1]
- `cfg_scale`: > kling-v2.x models do not support this parameter
- `mode`: `std`: Standard Mode, basic mode, cost-effective. The output video resolution is 720P.
  - `pro`: Professional Mode, generates videos use longer duration but higher quality video output. The output video resolution is 1080P.
  - `4k`: 4K Mode, generates videos use longer duration but higher quality video output. The output video resolution is 4K.
- `mode`: > The support range for different model versions and video modes varies. For details, see [Capability Map](https://kling.ai/document-api/guides/capability-map/video)
- `camera_control`: > The support range for different model versions and video modes varies. For details, see [Capability Map](https://kling.ai/document-api/guides/capability-map/video)
- `camera_control.type`: simple: Simple camera movement, you can choose one of six options in "config"
- `camera_control.type`: down_back: Camera descends and moves backward ➡️ Pan down and zoom out. The config parameter must be set to "None" under this type.
- `camera_control.type`: forward_up: Camera moves forward and tilts up ➡️ Zoom in and pan up. The config parameter must be set to "None" under this type.
- `camera_control.type`: right_turn_forward: Rotate right then move forward ➡️ Rotate right and advance. The config parameter must be set to "None" under this type.
- `camera_control.type`: left_turn_forward: Rotate left then move forward ➡️ Rotate left and advance. The config parameter must be set to "None" under this type.
- `camera_control.config`: Required when type is simple, not required for other types
- `camera_control.config`: Choose 1 of the following 6 parameters, only one can be non-zero, others must be 0
- `camera_control.config.horizontal`: Value range: [-10, 10]
- `camera_control.config.horizontal`: Negative value indicates a translation to the left, positive value indicates a translation to the right
- `camera_control.config.vertical`: Value range: [-10, 10]
- `camera_control.config.vertical`: Negative value indicates a downward translation, positive value indicates an upward translation
- `camera_control.config.pan`: Value range: [-10, 10]
- `camera_control.config.pan`: Negative value indicates rotation to the left around y-axis, positive value indicates rotation to the right around y-axis
- `camera_control.config.tilt`: Value range: [-10, 10]
- `camera_control.config.tilt`: Negative value indicates rotation down around x-axis, positive value indicates rotation up around x-axis
- `camera_control.config.roll`: Value range: [-10, 10]
- `camera_control.config.roll`: Negative value indicates counterclockwise rotation around z-axis, positive value indicates clockwise rotation around z-axis
- `camera_control.config.zoom`: Value range: [-10, 10]
- `camera_control.config.zoom`: Negative value indicates longer focal length, smaller field of view; positive value indicates shorter focal length, larger field of view
- `duration`: > The support range for different model versions and video modes varies. For details, see [Capability Map](https://kling.ai/document-api/guides/capability-map/video)
- `watermark_info`: Defined by the enabled parameter, format: 
  ```json
    "watermark_info": { "enabled": boolean } 
  ```
- `watermark_info`: true: generate watermarked result, false: do not generate
- `watermark_info`: Custom watermarks are not currently supported
- `callback_url`: For specific message schema, see [Callback Protocol](https://kling.ai/document-api/api/get-started/callbacks)
- `external_task_id`: Users can provide a customized task ID, which will not overwrite the system-generated task ID but can be used for task queries
- `external_task_id`: Must be unique within a single user account

### Request Example

```bash
curl --request POST \
  --url https://api-singapore.klingai.com/v1/videos/text2video \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model_name": "kling-v2-6",
    "prompt": "A cute little rabbit wearing glasses, sitting at a table, reading a newspaper, with a cup of cappuccino on the table",
    "negative_prompt": "",
    "duration": "5",
    "mode": "pro",
    "sound": "on",
    "aspect_ratio": "1:1",
    "callback_url": "",
    "external_task_id": ""
  }'
```

### Response Example

```json
{
  "code": 0, // Error codes; Specific definitions can be found in "Error Code"
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system
  "data": {
    "task_id": "string", // Task ID, generated by the system
    "task_info": { // Task creation parameters
      "external_task_id": "string" // Customer-defined task ID
    },
    "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed
    "created_at": 1722769557708, // Task creation time, Unix timestamp, unit ms
    "updated_at": 1722769557708 // Task update time, Unix timestamp, unit ms
  }
}
```

## More Scene Invocation Examples

### Text to Video with Multiple Shot

```Bash
curl --location 'https://xxx/v1/videos/text2video' \
--header 'Authorization: Bearer xxx' \
--header 'Content-Type: application/json' \
--data '{
    "model_name": "kling-v3",
    "prompt": "",
    "multi_prompt": [
        {
            "index": 1,
            "prompt": "Two friends talking under a streetlight at night.  Warm glow, casual poses, no dialogue.",
            "duration": "2"
        },
        {
            "index": 2,
            "prompt": "A runner sprinting through a forest, leaves flying.  Low-angle shot, focus on movement.",
            "duration": "3"
        },
        {
            "index": 3,
            "prompt": "A woman hugging a cat, smiling.  Soft sunlight, cozy home setting, emphasize warmth.",
            "duration": "3"
        },
        {
            "index": 4,
            "prompt": "A door creaking open, shadowy hallway.  Dark tones, minimal details, eerie mood.",
            "duration": "3"
        },
        {
            "index": 5,
            "prompt": "A man slipping on a banana peel, shocked expression.  Exaggerated pose, bright colors.",
            "duration": "3"
        },
        {
            "index": 6,
            "prompt": "A sunset over mountains, small figure walking away.  Wide angle, peaceful atmosphere.",
            "duration": "1"
        }
    ],
    "multi_shot": true,
    "shot_type": "customize",
    "duration": "15",
    "mode": "pro",
    "sound": "on",
    "aspect_ratio": "9:16",
    "callback_url": "",
    "external_task_id": ""
}'
```

---

## Query Task (Single)

### API Overview

- Method: `GET`
- Path: `/v1/videos/text2video/{id}`
- 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 |

### Path Params

| Field | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `task_id` | string | No | - | - | Task ID for text-to-video. Fill the value directly in the request path. Choose either task_id or external_task_id for querying. |
| `external_task_id` | string | No | - | - | Customized Task ID for text-to-video. Fill the value directly in the request path. Choose either task_id or external_task_id for querying. |

### Request Example

```bash
curl --request GET \
  --url https://api-singapore.klingai.com/v1/videos/text2video/{task_id} \
  --header 'Authorization: Bearer <token>'
```

### Response Example

```json
{
  "code": 0, // Error codes; Specific definitions can be found in "Error Code"
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system, is used to track requests and troubleshoot problems
  "data": {
    "task_id": "string", // Task ID, generated by the system
    "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed
    "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.)
    "task_info": { // Task creation parameters
      "external_task_id": "string" // Customer-defined task ID
    },
    "task_result": {
      "videos": [
        {
          "id": "string", // Generated video ID; globally unique
          "url": "string", // URL for generating videos (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.)
          "watermark_url": "string", // Watermarked video download URL, anti-leech format
          "duration": "string" // Total video duration, unit: s (seconds)
        }
      ]
    },
    "watermark_info": {
      "enabled": boolean
    },
    "final_unit_deduction": "string", // The deduction units of task
    "final_balance_deduction": { // Balance deduction information
      "quota": "string", // Balance deduction discount price
      "list_price": "string" // Balance deduction list price
    },
    "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
    "updated_at": 1722769557708 // Task update time, Unix timestamp, unit: ms
  }
}
```

---

## Query Task (List)

### API Overview

- Method: `GET`
- Path: `/v1/videos/text2video`
- 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 |

### Query Params

| Field | Type | Required | Default | Enum | Description |
|---|---|---:|---|---|---|
| `pageNum` | int | No | `1` | - | Page number |
| `pageSize` | int | No | `30` | - | Number of items per page |

#### Query Params Field Notes

- `pageNum`: Value range: [1, 1000]
- `pageSize`: Value range: [1, 500]

### Request Example

```bash
curl --request GET \
  --url 'https://api-singapore.klingai.com/v1/videos/text2video?pageNum=1&pageSize=30' \
  --header 'Authorization: Bearer <token>'
```

### Response Example

```json
{
  "code": 0, // Error codes; Specific definitions can be found in Error codes
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system, to track requests and troubleshoot problems
  "data": [
    {
      "task_id": "string", // Task ID, generated by the system
      "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed
      "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.)
      "task_info": { // Task creation parameters
        "external_task_id": "string" // Customer-defined task ID
      },
      "task_result": {
        "videos": [
          {
            "id": "string", // Generated video ID; globally unique
            "url": "string", // URL for generating videos (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.)
            "watermark_url": "string", // Watermarked video download URL, anti-leech format
            "duration": "string" // Total video duration, unit: s (seconds)
          }
        ]
      },
      "watermark_info": {
        "enabled": boolean
      },
      "final_unit_deduction": "string", // The deduction units of task
      "final_balance_deduction": { // Balance deduction information
        "quota": "string", // Balance deduction discount price
        "list_price": "string" // Balance deduction list price
      },
      "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
      "updated_at": 1722769557708 // Task update time, Unix timestamp, unit: ms
    }
  ]
}
```