Request parameters
|
Text-to-video
Supported models: kling/kling-v3-omni-video-generation and kling/kling-v3-video-generation. # The URL below is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID.
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "kling/kling-v3-video-generation",
"input": {
"prompt": "A kitten runs under the moonlight"
},
"parameters": {
"mode": "std",
"aspect_ratio": "16:9",
"duration": 5,
"audio": false,
"watermark": true
}
}'
Text-to-video (custom shot division)
Supported models: kling/kling-v3-omni-video-generation and kling/kling-v3-video-generation. # The URL below is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID.
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "kling/kling-v3-video-generation",
"input": {
"prompt": "",
"multi_shot": true,
"shot_type": "customize",
"multi_prompt": [
{
"index": 1,
"prompt": "Wuling Town is smaller than it appears on the map. Mountain mist, like cotton fluff, blocks the street entrance. Behind the post office, there are indeed three locust trees. The soil by the roots of the third tree has been disturbed.",
"duration": 5
},
{
"index": 2,
"prompt": "Lin Che squats down and digs up an iron box. Inside, besides a rusty key, is an old cassette tape. The tape recorder was borrowed from the post office. When the play button is pressed, his father's voice emerges from the static: 'If you are hearing this, it means you have walked the path I once walked.'",
"duration": 5
}
],
"media": [],
"element_list": []
},
"parameters": {
"mode": "pro",
"duration": 10,
"audio": true,
"aspect_ratio": "9:16",
"watermark": true
}
}'
Image-to-video (from a first frame)
Supported models: kling/kling-v3-omni-video-generation and kling/kling-v3-video-generation. # The URL below is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID.
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "kling/kling-v3-omni-video-generation",
"input": {
"prompt": "Animate the person in the picture, with their hair blowing in a gentle breeze",
"media": [
{
"type": "first_frame",
"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260121/zlpocv/wan-i2v-haigui.webp"
}
]
},
"parameters": {
"mode": "std",
"duration": 5,
"audio": false,
"watermark": true
}
}'
Image-to-video (from first and last frames)
Supported models: kling/kling-v3-omni-video-generation and kling/kling-v3-video-generation. # The URL below is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID.
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "kling/kling-v3-omni-video-generation",
"input": {
"prompt": "Realistic style, a small black cat looks up at the sky curiously. The camera starts at eye level, gradually rises, and ends with a top-down shot of its curious eyes.",
"media": [
{
"type": "first_frame",
"url": "https://wanx.alicdn.com/material/20250318/first_frame.png"
},
{
"type": "last_frame",
"url": "https://wanx.alicdn.com/material/20250318/last_frame.png"
}
]
},
"parameters": {
"mode": "std",
"duration": 5,
"audio": false,
"watermark": true
}
}'
Video editing
Supported model: kling/kling-v3-omni-video-generation. # The URL below is for the China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID.
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
-H 'X-DashScope-Async: enable' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "kling/kling-v3-omni-video-generation",
"input": {
"prompt": "<<<element_1>>> background, <<<image_2>>> and <<<image_1>>> shake hands and talk, <<<video_1>>> a detective in a black trench coat stands on the roof of an apartment building, observing the street with binoculars",
"multi_shot": false,
"shot_type": "intelligence",
"multi_prompt": [],
"media": [
{
"url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/lip_sync_5s.mp4",
"type": "base",
"keep_original_sound": "yes"
},
{
"type": "refer",
"url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/zem_test/yangmi01.jpg"
},
{
"type": "refer",
"url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/human_2.JPG"
}
],
"element_list": [
{
"element_id": 171
}
]
},
"parameters": {
"mode": "pro",
"duration": 10,
"audio": false,
"aspect_ratio": "1:1",
"watermark": true
}
}'
|
Headers
|
|
Content-Type string (Required)
The content type of the request. Must be application/json.
|
|
Authorization string (Required)
Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.
|
|
X-DashScope-Async string (Required)
Enables asynchronous processing. HTTP requests support only asynchronous calls. Must be enable.
Important
If this request header is missing, the error "current user api does not support synchronous calls" is returned.
|
Request Body
|
|
model string (Required)
The model name.
Valid values:
|
|
input object (Required)
Basic input information, such as prompts and media assets.
Properties
prompt string (Conditionally required)
The text prompt describes the desired elements and visual features in the generated video.
Chinese and English are supported. Each Chinese character or letter counts as one character. The maximum length is 2,500 characters. Exceeding the limit will result in an error.
Logic:
-
When shot_type=intelligence, this parameter is required.
-
When shot_type=customize, this parameter is ignored. Use multi_prompt instead.
The Omni model can use the prompt with entities, images, and videos to achieve various capabilities:
-
Supported model: kling/kling-v3-omni-video-generation.
-
Applicable task: reference-to-video.
-
Reference format: Use the <<<>>> format to specify an entity, image, or video, such as <<<element_1>>>, <<<image_1>>>, or <<<video_1>>>.
-
Reference order: Define the reference order in the prompt according to the order in the media array.
-
Example: A <<<element_1>>> runs under the moonlight.
media array (Optional)
You do not need to specify this parameter for text-to-video tasks.
A list of media assets used to specify image or video materials.
Different models support different combinations of media assets:
Asset combination rules
kling/kling-v3-video-generation
Only the following media asset combinations are supported. Invalid combinations will cause an error.
kling/kling-v3-omni-video-generation
Only the following media asset combinations are supported. Invalid combinations will cause an error.
-
Image-to-video from a first frame: first_frame.
-
Image-to-video from first and last frames: first_frame+last_frame.
-
Reference-to-video: The following media combinations are supported.
-
If only feature is passed: 1 video must be passed.
-
If only refer is passed: The sum of reference images and multi-image entities (the length of the element_list array) cannot exceed 7.
-
If feature+refer is passed: 1 video must be passed, and the sum of reference images and multi-image entities (the length of the element_list array) cannot exceed 4.
-
If feature+first_frame is passed: 1 video and 1 first frame must be passed.
-
Video editing: The following media combinations are supported.
-
If only base is passed: 1 video must be passed.
-
If base+refer is passed: 1 video must be passed, and the sum of reference images and multi-image entities (the length of the element_list array) cannot exceed 4.
Properties
type string (Required)
The type of media asset. The valid values depend on the selected model:
kling/kling-v3-video-generation
Valid values:
For restrictions on combinations of different media assets, see "Asset combination rules" under the media parameter.
kling/kling-v3-omni-video-generation
Valid values:
-
first_frame: The first frame image.
-
last_frame: The last frame image.
-
refer: The reference image.
-
base: The video to be edited.
-
feature: The feature reference video.
For restrictions on combinations of different media assets, see "Asset combination rules" under the media parameter.
url string (Required)
The URL of the media asset. Assets include images and videos.
Pass an image (type=first_frame, last_frame, or refer)
The image URL.
Image restrictions:
-
Format: JPEG, JPG, or PNG (alpha channels are not supported).
-
Resolution: The width and height must be between 300 and 8000 pixels.
-
Aspect ratio: Between 1:2.5 and 2.5:1.
-
File size: No more than 10 MB.
Pass a video (type=base or feature)
The URL of the video file.
Video restrictions:
-
Format: MP4 or MOV.
-
Duration: 3 to 10 seconds.
-
Resolution: The width and height must be between 720 and 2160 pixels.
-
File size: No more than 200 MB.
-
Frame rate: 24 to 60 fps.
keep_original_sound string (Optional)
Supported model: kling/kling-v3-omni-video-generation.
Effective condition: This parameter takes effect only when a video is passed (type=base or feature).
Specifies whether to keep the original video's sound.
multi_shot boolean (Optional)
Specifies whether to enable multi-shot generation.
shot_type string (Conditionally required)
Required when multi_shot=true. The type of multi-shot mode.
multi_prompt array (Conditionally required)
Required when shot_type=customize. A list of segments for the custom multi-shot mode.
Properties
index integer (Required)
The index of the shot segment. The number of shots can be from 1 to 6. The index starts from 1.
prompt string (Required)
The prompt for the corresponding segment. Chinese and English are supported. The maximum length is 512 characters. Excess characters are automatically truncated.
duration integer (Required)
The duration of the corresponding segment, in seconds.
The value must be an integer between 1 and parameters.duration.
element_list array (Optional)
A list of entities to be included in the video.
Properties
element_id integer (Conditionally required)
Required when passing element_list. It represents the entity ID. Retrieve the entity ID from the Kling - Entity ID List.
Entity count limit (element_list array length limit):
-
Image-to-video from a first frame: Supports up to 3 entities.
-
Image-to-video from first and last frames: Supports up to 3 entities.
-
Reference-to-video (type=refer): The sum of reference images and multi-image entities cannot exceed 7.
-
Reference-to-video (type=feature+refer): The sum of reference images and multi-image entities cannot exceed 4.
|
|
parameters object (Optional)
Video generation parameters. You can set the generation mode, aspect ratio, video duration, and whether to generate audio.
Properties
mode string (Optional)
The video generation mode.
-
pro: Default value. Professional mode. The output video resolution is 1080p.
-
std: Standard mode. The output video resolution is 720p.
-
4k: 4K mode. The output video resolution is 4K.
aspect_ratio string (Conditionally required)
The aspect ratio of the generated video.
Valid values:
-
16:9: Default value.
-
9:16
-
1:1
This must be specified in the following scenarios:
-
Text-to-video: Must be set.
-
Reference-to-video (type=feature, type=feature+refer, type=refer): Must be set.
You do not need to set this in other scenarios
-
Image-to-video from a first frame: The aspect ratio of the first frame is used. You do not need to specify this.
-
Image-to-video from first and last frames: The aspect ratio of the first frame is used. You do not need to specify this.
-
Reference-to-video (type=feature+first_frame): The aspect ratio of the first frame is used. You do not need to specify this.
-
Video editing: The aspect ratio of the input video is used. You do not need to specify this.
duration integer (Optional)
Important
The duration directly affects the cost. Billing is based on seconds. The longer the duration, the higher the cost. Go to the Model Studio console to view prices.
The duration of the generated video, in seconds.
-
kling/kling-v3-omni-video-generation: The value must be an integer between 3 and 15. The default value is 5.
-
kling/kling-v3-video-generation: The value must be an integer between 3 and 15. The default value is 5.
Example: 5.
audio boolean (Optional)
Specifies whether to generate a video with sound. If enabled, the model automatically generates matching background music or sound effects based on the video content.
Note: When a video is passed in (type=base or feature), audio can only be set to false.
watermark boolean (Optional)
Specifies whether to simultaneously generate a watermarked version of the video. The watermark is located in the lower-right corner and displays "Kling AI". When set to true, the response will additionally return the watermark_video_url field.
|