Text to Video

Create Task

POST/v1/videos/text2video

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": ""
  }'

200

{
  "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
  }
}

💡

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

Request Header

Content-TypestringRequiredDefault to application/json

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authorization

Request Body

model_namestringOptionalDefault to kling-v1

Model Name

Enum values：kling-v1kling-v1-6kling-v2-masterkling-v2-1-masterkling-v2-5-turbokling-v2-6kling-v3

multi_shotbooleanOptionalDefault to false

Whether to generate multi-shot video

When true: the prompt parameter is invalid, and the first/end frame generation is not supported.

When false: the shot_type and multi_prompt parameters are invalid

shot_typestringOptional

Storyboard method

Enum values：customizeintelligence

When multi_shot is true, this parameter is required

promptstringOptional

Positive text 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, Kling VIDEO 3.0 Omni Model User Guide

Cannot exceed 2500 characters

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

When multi_shot is false or shot_type is intelligence, this parameter must not be empty.

The support range for different model versions and video modes varies. For details, see Capability Map

multi_promptarrayOptional

Each storyboard cue can include both positive and negative descriptions

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.

Load with key:value format as follows:

"multi_prompt":[
{"index":int,"prompt":"string","duration":"5"},
{"index":int,"prompt":"string","duration":"5"}
]

When multi_shot is true and shot_type is customize, this parameter is required.

negative_promptstringOptional

Negative text prompt

Cannot exceed 2500 characters

It is recommended to supplement negative prompt via negative sentences within positive prompts

soundstringOptionalDefault to off

Is sound generated simultaneously when generating videos

Enum values：onoff

The support range for different model versions and video modes varies. For details, see Capability Map

cfg_scalefloatOptionalDefault to 0.5

The degree of freedom for generating video; the larger the value, the smaller the degree of freedom of the model

Value range: [0, 1]

kling-v2.x models do not support this parameter

modestringOptionalDefault to std

Video generation mode

Enum values：stdpro

std: Standard mode, basic mode, cost-effective

pro: Expert mode (high quality), high performance mode, better video quality

The support range for different model versions and video modes varies. For details, see Capability Map

camera_controlobjectOptional

Terms of controlling camera movement (if not specified, the model will intelligently match based on the input text/images)

The support range for different model versions and video modes varies. For details, see Capability Map

▾Hide child attributes

typestringOptional

Predefined camera movements type

Enum values：simpledown_backforward_upright_turn_forwardleft_turn_forward

simple: Simple camera movement, you can choose one of six options in "config"

down_back: Camera descends and moves backward ➡️ Pan down and zoom out. The config parameter must be set to "None" under this 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.

right_turn_forward: Rotate right then move forward ➡️ Rotate right and advance. The config parameter must be set to "None" under this type.

left_turn_forward: Rotate left then move forward ➡️ Rotate left and advance. The config parameter must be set to "None" under this type.

configobjectOptional

Contains 6 fields, used to specify the camera's movement or change in different directions

Required when type is simple, not required for other types

Choose 1 of the following 6 parameters, only one can be non-zero, others must be 0

▾Hide child attributes

horizontalfloatOptional

Horizontal, controls the camera's movement along the horizontal axis (translation along the x-axis)

Value range: [-10, 10]

Negative value indicates a translation to the left, positive value indicates a translation to the right

verticalfloatOptional

Vertical, controls the camera's movement along the vertical axis (translation along the y-axis)

Value range: [-10, 10]

Negative value indicates a downward translation, positive value indicates an upward translation

panfloatOptional

Pan, controls the camera's rotation in the horizontal plane (rotation around the y-axis)

Value range: [-10, 10]

Negative value indicates rotation to the left around y-axis, positive value indicates rotation to the right around y-axis

tiltfloatOptional

Tilt, controls the camera's rotation in the vertical plane (rotation around the x-axis)

Value range: [-10, 10]

Negative value indicates rotation down around x-axis, positive value indicates rotation up around x-axis

rollfloatOptional

Roll, controls the camera's roll (rotation around the z-axis)

Value range: [-10, 10]

Negative value indicates counterclockwise rotation around z-axis, positive value indicates clockwise rotation around z-axis

zoomfloatOptional

Zoom, controls the camera's focal length change, affecting the distance of the field of view

Value range: [-10, 10]

Negative value indicates longer focal length, smaller field of view; positive value indicates shorter focal length, larger field of view

aspect_ratiostringOptionalDefault to 16:9

The aspect ratio of the generated video frame (width:height)

Enum values：16:99:161:1

durationstringOptionalDefault to 5

Video Length, unit: s (seconds)

Enum values：3456789101112131415

The support range for different model versions and video modes varies. For details, see Capability Map

watermark_infoobjectOptional

Whether to generate watermarked results simultaneously

Defined by the enabled parameter, format:

  "watermark_info": { "enabled": boolean } 

true: generate watermarked result, false: do not generate

Custom watermarks are not currently supported

callback_urlstringOptional

Callback notification URL for this task result. If configured, the server will actively notify when the task status changes

For specific message schema, see Callback Protocol

external_task_idstringOptional

Customized 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

Must be unique within a single user account

cURL
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": ""
  }'
200
{
  "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

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)

GET/v1/videos/text2video/{id}

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

200

{
  "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
    "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
    "updated_at": 1722769557708 // Task update time, Unix timestamp, unit: ms
  }
}

Request Header

Content-TypestringRequiredDefault to application/json

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

Path Parameters

task_idstringOptional

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_idstringOptional

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.

cURL
curl --request GET \
  --url https://api-singapore.klingai.com/v1/videos/text2video/{task_id} \
  --header 'Authorization: Bearer <token>'
200
{
  "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
    "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
    "updated_at": 1722769557708 // Task update time, Unix timestamp, unit: ms
  }
}

Query Task (List)

GET/v1/videos/text2video

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

200

{
  "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
      "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
      "updated_at": 1722769557708 // Task update time, Unix timestamp, unit: ms
    }
  ]
}

Request Header

Content-TypestringRequiredDefault to application/json

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

Query Parameters

pageNumintOptionalDefault to 1

Page number

Value range: [1, 1000]

pageSizeintOptionalDefault to 30

Number of items per page

Value range: [1, 500]

cURL
curl --request GET \
  --url 'https://api-singapore.klingai.com/v1/videos/text2video?pageNum=1&pageSize=30' \
  --header 'Authorization: Bearer <token>'
200
{
  "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
      "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
      "updated_at": 1722769557708 // Task update time, Unix timestamp, unit: ms
    }
  ]
}