Skip to content

MaaS_KL Interface Documentation

Request Protocol

Http

Parameter Name Type Description
Authorization string Authentication

Text to Video

Create Task

Request URL

https://genaiapi.cloudsway.net/v1/ai/{endpoinPath}/kling/videos/text2video

Request Method

POST

Request Body

Field Type Required Default Description
model_name string Optional kling-v1 Model name, enum values: MaaS_KL_V1.6，MaaS_KL_V2.1_Master，MaaS_KeLing_V2.6
prompt string Required None Positive text prompt, cannot exceed 2500 characters
sound string Optional off Enumeration value for whether to generate sound simultaneously when generating a video: on, off. Only the MaaS_KeLing_V2.6 model and its subsequent versions support this parameter.
negative_prompt string Optional Empty Negative text prompt, cannot exceed 2500 characters
cfg_scale float Optional 0.5 Freedom of video generation; higher value means less model freedom and stronger correlation with user input prompt, range: [0, 1].MaaS_KL_V2.1，MaaS_KL_V2.1_Master，MaaS_KeLing_V2.6 does not support this parameter.
mode string Optional std Video generation mode - enum values: std, pro. std: standard mode (standard), basic mode, cost-effective; pro: expert mode (high quality), high-performance mode, better video quality. Different model versions and video modes support different ranges. MaaS_KL_V2.1_Master does not support this parameter，MaaS_KeLing_V2.6 is currently only available for Pro.
camera_control object Optional Empty Protocol for controlling camera movement (if not specified, the model will intelligently match based on input text/image). Different model versions and video modes support different ranges
camera_control - type string Optional None Predefined camera movement type - enum values: "simple", "down_back", "forward_up", "right_turn_forward", "left_turn_forward". simple: simple camera movement, choose one of six in "config" for this type; down_back: camera moves down and back ➡ down and away, no config parameters needed; forward_up: camera moves forward and up ➡ push forward and up, no config parameters needed; right_turn_forward: first turn right then move forward ➡ right turn and push, no config parameters needed; left_turn_forward: first turn left then move forward ➡ left turn and push, no config parameters needed
camera_control - config object Optional None Contains six fields to specify camera movement or changes in different directions. Required when camera movement type is set to simple, not filled for other types. Choose 1 out of 6 parameters, i.e., only one parameter can be non-zero, the rest must be zero
camera_control - horizontal float Optional None Horizontal camera movement, controls camera movement in horizontal direction (along x-axis), range: [-10, 10], negative values indicate left movement, positive values indicate right movement
camera_control - vertical float Optional None Vertical camera movement, controls camera movement in vertical direction (along y-axis), range: [-10, 10], negative values indicate downward movement, positive values indicate upward movement
camera_control - pan float Optional None Horizontal pan, controls camera rotation in horizontal plane (around y-axis), range: [-10, 10], negative values indicate left rotation around y-axis, positive values indicate right rotation around y-axis
camera_control - tilt float Optional None Vertical tilt, controls camera rotation in vertical plane (along x-axis), range: [-10, 10], negative values indicate downward rotation around x-axis, positive values indicate upward rotation around x-axis
camera_control - roll float Optional None Camera roll, controls camera roll amount (rotation around z-axis), range: [-10, 10], negative values indicate counterclockwise rotation around z-axis, positive values indicate clockwise rotation around z-axis
camera_control - zoom float Optional None Zoom, controls camera focal length change, affecting field of view, range: [-10, 10], negative values indicate longer focal length and smaller field of view, positive values indicate shorter focal length and larger field of view
camera_control - aspect_ratio string Optional 16:9 Aspect ratio of generated video (width:height), enum values: 16:9, 9:16, 1:1
duration string Optional 5 Generated video duration, unit: seconds, enum values: 5, 10
external_task_id string Optional None Custom task ID - User-defined task ID, input will not override system-generated task ID, but supports task query through this ID. Please note, must be unique within a single user

Request Example

curl --location 'https://genaiapi.cloudsway.net/v1/ai/XXX/kling/videos/text2video' \ 
--header 'Authorization: Bearer XXX' \ 
--header 'Content-Type: application/json' \ 
--data '{ "model_name":"kling-v1", 
"prompt":"A dog running on the grass"
}'

Response Body

{
"request_id": "string", // Request ID, system-generated, used for tracking requests and troubleshooting
"code": 0, // Error code; see specific definitions in error codes
"message": "string", // Error message
"data": {
"task_id": "string", // Task ID, system-generated
"task_info": {
// Task creation parameter information
"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
}
}

Query Task

Request URL

https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/kling/videos/text2video/{id}

Request Method

GET

Request Path Parameters

Field Type Required Default Description
task_id string Optional None Text-to-video task ID, request path parameter, directly fill the value in the request path, choose one between this and external_task_id
external_task_id string Optional None Custom task ID for text-to-video, filled in when creating the task, choose one between this and task_id

Response Body

{
"code": 0, // Error code; see specific definitions in error codes
"message": "string", // Error message
"request_id": "string", // Request ID, system-generated, used for tracking requests and troubleshooting
"data":{
"task_status": "string", // Task status, enum values: submitted, processing, succeed, failed
"task_status_msg": "string", // Task status information, displays failure reason when task fails (e.g., triggering platform's content risk control)
"task_info": { // Task creation parameter information
"task_id": "string", // Task ID, system-generated
"external_task_id": "string" // Customer-defined task ID
},
"task_result":{
"videos":[
{
"id": "string", // Generated video ID; globally unique
"url": "string", // Generated video URL, e.g., https://p1.a.kwimgs.com/bs2/upload-ylab-stunt/special-effect/
"duration": "string" // Total video duration, unit s
}
],
"created_at": 1722769557708, // Task creation time, Unix timestamp, unit ms
"updated_at": 1722769557708 // Task update time, Unix timestamp, unit ms
}
}

Image to Video

Create Task

Request URL

https://genaiapi.cloudsway.net/v1/ai/{endpoinPath}/kling/videos/image2video

Request Method

POST

Request Body

Field Type Required Default Description
model_name string Optional kling-v1 Model name, enum values: MaaS_KL_V1.6, MaaS_KL_V2.1，MaaS_KL_V2.1_Master，MaaS_KeLing_V2.6
image string Required Empty Reference image - Supports image Base64 encoding or image URL (ensure accessibility). Note: If using base64, ensure all image data parameters are correctly Base64 encoded, i.e., provide only the Base64 encoded string part, without the data: prefix. Supported image formats: .jpg / .jpeg / .png, image file size cannot exceed 10MB, image resolution not less than 300*300px. At least one of image or image_tail parameters must be provided, they cannot both be empty. The support range for image + image_tail parameters, dynamic_masks/static_mask parameters, and camera_control varies for different model versions and video modes, see the current document 3-0 capability map for details
image_tail string Optional Empty Reference image - Tail frame control. Supports image Base64 encoding or image URL (ensure accessibility), parameter format requirements same as image. Supported image formats: .jpg / .jpeg / .png, image file size cannot exceed 10MB, image resolution not less than 300*300px. At least one of image or image_tail parameters must be provided, they cannot both be empty. The support range for image + image_tail parameters, dynamic_masks/static_mask parameters, and camera_control varies for different model versions and video modes
sound string Optional off Enumeration value for whether to generate sound simultaneously when generating a video: on, off. Only the MaaS_KeLing_V2.6 model and its subsequent versions support this parameter.
prompt string Optional None Positive text prompt, cannot exceed 2500 characters
negative_prompt string Optional Empty Negative text prompt, cannot exceed 2500 characters
cfg_scale float Optional 0.5 Freedom of video generation; higher value means less model freedom and stronger correlation with user input prompt, range: [0, 1]
mode string Optional std Video generation mode - enum values: std, pro. std: standard mode (standard), basic mode, cost-effective; pro: expert mode (high quality), high-performance mode, better video quality. Different model versions and video modes support different ranges.MaaS_KL_V2.1_Master does not support this parameter，MaaS_KeLing_V2.6 is currently only available for Pro.
static_mask string Optional None Static brush smear area (mask image smeared by user using motion brush). "Motion brush" capability includes "dynamic brush dynamic_masks" and "static brush static_mask". Supports image Base64 encoding or image URL (ensure accessibility, format requirements same as image). Supported image formats: .jpg / .jpeg / .png, image aspect ratio must be the same as the input image (i.e., image field), otherwise the task fails. The resolution of static_mask and dynamic_masks.mask must be consistent. Different model versions and video modes support different ranges
dynamic_masks array Optional None Dynamic brush configuration list, can configure multiple groups (up to 6), each group includes "smear area mask" and "motion trajectory trajectories"
dynamic_masks - mask string Optional None Dynamic brush smear area (mask image smeared by user using motion brush). Supports image Base64 encoding or image URL (ensure accessibility, format requirements same as image). Supported image formats: .jpg / .jpeg / .png, image aspect ratio must be the same as the input image (i.e., image field), otherwise the task fails. The resolution of static_mask and dynamic_masks.mask must be consistent
dynamic_masks - trajectories array Optional None Motion trajectory coordinate sequence. For generating 5s video, trajectory length should not exceed 77, i.e., coordinate count range: [2, 77]. Trajectory coordinate system, with the bottom left corner of the image as the coordinate origin. Note 1: More trajectory points result in more accurate trajectory depiction, if only 2 trajectory points are provided, it will be a line connecting these two points. Note 2: Trajectory direction is based on the order of input, with the first input coordinate as the trajectory start point, connecting in sequence
dynamic_masks - trajectories - x int Optional None Trajectory point x-coordinate (pixel coordinate in 2D coordinate system with the bottom left of the input image as the origin)
dynamic_masks - trajectories - y int Optional None Trajectory point y-coordinate (pixel coordinate in 2D coordinate system with the bottom left of the input image as the origin)
camera_control object Optional Empty Protocol for controlling camera movement (if not specified, the model will intelligently match based on input text/image). Different model versions and video modes support different ranges
camera_control - type string Optional None Predefined camera movement type - enum values: "simple", "down_back", "forward_up", "right_turn_forward", "left_turn_forward". simple: simple camera movement, choose one of six in "config" for this type; down_back: camera moves down and back ➡ down and away, no config parameters needed; forward_up: camera moves forward and up ➡ push forward and up, no config parameters needed; right_turn_forward: first turn right then move forward ➡ right turn and push, no config parameters needed; left_turn_forward: first turn left then move forward ➡ left turn and push, no config parameters needed
camera_control - config object Optional None Contains six fields to specify camera movement or changes in different directions. Required when camera movement type is set to simple, not filled for other types. Choose 1 out of 6 parameters, i.e., only one parameter can be non-zero, the rest must be zero
camera_control - horizontal float Optional None Horizontal camera movement, controls camera movement in horizontal direction (along x-axis), range: [-10, 10], negative values indicate left movement, positive values indicate right movement
camera_control - vertical float Optional None Vertical camera movement, controls camera movement in vertical direction (along y-axis), range: [-10, 10], negative values indicate downward movement, positive values indicate upward movement
camera_control - pan float Optional None Horizontal pan, controls camera rotation in horizontal plane (around y-axis), range: [-10, 10], negative values indicate left rotation around y-axis, positive values indicate right rotation around y-axis
camera_control - tilt float Optional None Vertical tilt, controls camera rotation in vertical plane (along x-axis), range: [-10, 10], negative values indicate downward rotation around x-axis, positive values indicate upward rotation around x-axis
camera_control - roll float Optional None Camera roll, controls camera roll amount (rotation around z-axis), range: [-10, 10], negative values indicate counterclockwise rotation around z-axis, positive values indicate clockwise rotation around z-axis
camera_control - zoom float Optional None Zoom, controls camera focal length change, affecting field of view, range: [-10, 10], negative values indicate longer focal length and smaller field of view, positive values indicate shorter focal length and larger field of view
duration string Optional 5 Generated video duration, unit: seconds, enum values: 5, 10
external_task_id string Optional None Custom task ID - User-defined task ID, input will not override system-generated task ID, but supports task query through this ID. Please note, must be unique within a single user

Request Example

curl --location 'https://genaiapi.cloudsway.net/v1/ai/xxx/kling/videos/image2video' \ 
--header 'Authorization: Bearer xxx' \ 
--header 'Content-Type: application/json' \ 
--data '{ "model_name":"kling-v1", 
"image":"https://pic1.zhimg.com/v2-0cbb2efa5a55f2e716eebe2d6a6eef67_r.jpg?source=12a79843", 
"prompt":"Nezha practicing martial arts"
}'

Response Body

{
"code": 0, // Error code; see specific definitions in error codes
"message": "string", // Error message
"request_id": "string", // Request ID, system-generated, used for tracking requests and troubleshooting
"data": {
"task_id": "string", // Task ID, system-generated
"task_info": {
// Task creation parameter information
"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
}
}

Query Task

Request URL

https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/kling/videos/image2video/{id}

Request Method

GET

Request Path Parameters

Field Type Required Default Description
task_id string Optional None Image-to-video task ID
Request path parameter, directly fill the value in the request path, choose one between this and external_task_id
external_task_id string Optional None Custom task ID for image-to-video
Filled in when creating the task, choose one between this and task_id

Response Body

{
"code": 0, // Error code; see specific definitions in error codes
"message": "string", // Error message
"request_id": "string", // Request ID, system-generated, used for tracking requests and troubleshooting
"data":{
"task_id": "string", // Task ID, system-generated
"task_status": "string", // Task status, enum values: submitted, processing, succeed, failed
"task_status_msg": "string", // Task status information, displays failure reason when task fails (e.g., triggering platform's content risk control)
"task_info": { // Task creation parameter information
"external_task_id": "string" // Customer-defined task ID
},
"task_result":{
"videos":[
{
"id": "string", // Generated video ID; globally unique
"url": "string", // Generated video URL, e.g., https://p1.a.kwimgs.com/bs2/upload-ylab-stunt/special-effect/
"duration": "string" // Total video duration, unit s
}
]
}
"created_at": 1722769557708, // Task creation time, Unix timestamp, unit ms
"updated_at": 1722769557708, // Task update time, Unix timestamp, unit ms
}
}

Video Extension

Create Task

Request URL

https://genaiapi.cloudsway.net/v1/ai/{endpoinPath}/kling/videos/video-extend

Request Method:

POST

Request Body

Video ID

  • Supports video IDs generated by the text-to-video interface (Versions 2.1 do not support this.)
  • Supports video IDs generated by the image-to-video interface (Versions 2.1 do not support this.)
  • Supports video IDs generated by the video extension interface (note: cannot exceed 3 minutes)
Field Type Required Default Description
video_id string Required None Video ID
- Supports video IDs generated by the text-to-video interface (Versions 2.1 do not support this.)
- Supports video IDs generated by the image-to-video interface (Versions 2.1 do not support this.)
- Supports video IDs generated by the video extension interface (note: cannot exceed 3 minutes)
Please note that based on the current cleanup strategy, videos will be cleaned up after 30 days of generation, and cannot be extended after that
prompt string Optional None Positive text prompt
Cannot exceed 2500 characters

Request Example

curl --location 'https://genaiapi.cloudsway.net/v1/ai/xxx/kling/videos/video-extend' \
--header 'Authorization: Bearer xxx' \
--header 'Content-Type: application/json' \
--data '{
"video_id": "51bc9fb8-8068-44af-9e35-121212",
"prompt": "Nezha pulls out a red-marked spear from behind, standing on the wind-fire wheels"
}'

Response Body

{
"code": 0, //Error code; see specific definitions in error codes
"message": "string", //Error message
"request_id": "string", //Request ID, system-generated, used for tracking requests and troubleshooting
"data": {
"task_id": "string", //Task ID, system-generated
"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
}
}

Query Task

Request URL

https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/kling/videos/video-extend/{task_id}

Request Method:

GET

Request Path Parameters

Field Type Required Default Description
task_id string Required None Video extension task ID
Request path parameter, directly fill the value in the request path

Response Body

{
"code": 0, //Error code; see specific definitions in 1.1 error codes
"message": "string", //Error message; see specific definitions in 1.1 error codes
"request_id": "string", //Request ID, system-generated, used for tracking requests and troubleshooting; globally unique
"data":{
"task_id": "string", //Task ID, system-generated; globally unique
"task_status": "string", //Task status, enum values: submitted, processing, succeed, failed
"task_status_msg": "string", //Task status information, displays failure reason when task fails (e.g., triggering platform's content risk control)
"task_info":{ //Task creation parameter information
"parent_video": {
"id": "string", //Video ID before extension; globally unique
"url": "string", //URL of the video before extension (Please note, for information security, generated images/videos will be cleaned up after 30 days, please transfer them in time)
"duration": "string" //Total duration of the video before extension, unit s
}
}, //Detailed information filled by the user when creating the task
"task_result":{
"videos":[ //Array is for maintaining extensibility, in case of future support for n
{
"id": "string", //Complete video ID after extension; globally unique
"url": "string", //URL of the video after extension
"duration": "string" //Total video duration, unit s
}
]
}
"created_at": 1722769557708, //Task creation time, Unix timestamp, unit ms
"updated_at": 1722769557708, //Task update time, Unix timestamp, unit ms
}
}

Multi-Image Reference to Video

Supported model: MaaS_KeLing_V1.6

Create Task

Request URL

https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/kling/videos/multi-image2video

Request Method

POST

Request Parameters

Field Type Required Default Value Description
model_name string Optional MaaS_KeLing_V1.6 Enumerated value of model name: MaaS_KeLing_V1.6
image_list array Required Empty Supports up to 4 images, carried by key:value.
There is no cropping logic on the API side, please upload directly.
Images after selecting the subject support passing in image Base64 encoding or image URL (ensure accessibility). Please note that if you use base64, ensure all your image data parameters are in Base64 encoding format. When submitting data, do not add any prefix to the Base64 encoded string; the correct parameter format should be the Base64 encoded string directly for the system to process and parse your data correctly.
Supported image formats: .jpg / .jpeg / .png
Image file size cannot exceed 10MB, image width and height are not less than 300px, and the aspect ratio is between 1:2.5 and 2.5:1
prompt string Required None Positive text prompt cannot exceed 2500 characters
negative_prompt string Optional Empty Negative text prompt cannot exceed 2500 characters
mode string Optional std Enumerated values for video generation mode: std, pro. std: standard mode (basic), cost-effective. pro: expert mode (high quality), high-performance mode, generating better quality videos. The support range varies by model version and video mode, see "3-0 Capability Map" in the current document
duration string Optional 5 Generated video duration, unit: s. Enumerated values: 5, 10
aspect_ratio string Optional 16:09 Aspect ratio of the generated image (width:height). Enumerated values: 16:9, 9:16, 1:1
callback_url string None Callback notification address for the task result. If configured, the server will actively notify when the task status changes. See "Callback Protocol" for the specific notification message schema
external_task_id string Optional None Custom task ID. User-defined task ID, which will not overwrite the system-generated task ID but supports task query through this ID. Please note that uniqueness must be ensured under a single user

Request Example

curl 'https://genaiapi.cloudsway.net/v1/ai/${Your endpoint}/kling/videos/multi-image2video' \
-H 'Authorization: Bearer ${Your AK}' \
-H 'Content-Type: application/json' \
-d '{
    "model_name": "MaaS_KeLing_V1.6",
    "image_list": [
        {
            "image": "${Your image1}"
        },
        {
            "image": "${Your image2}"
        },
        {
            "image": "${Your image3}"
        },
        {
            "image": "${Your image4}"
        }
    ],
    "prompt": "${Your prompt}",
    "negative_prompt": "No negative energy content",
    "mode": "std",
    "duration": "10",
    "aspect_ratio": "9:16",
    "external_task_id": "xiaosuvideo03013018412"
}'

Response

{
    "code": 0,
    "message": "SUCCEED",
    "data": {
        "task_id": "xiaoshuvideo03013018412",
        "task_status": "submitted",
        "created_at": 1761532694501,
        "updated_at": 1761532694501,
        "task_info": {
            "external_task_id": "xiaoshuvideo03013018412"
        }
    },
    "request_id": "ba150df0-c007-4938-9a47-24ea2b561d6d"
}

Query Task (Single) Interface

Request URL

https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/kling/videos/multi-image2video/{task_id}

Request Method

GET

Request Example

curl 'https://genaiapi.cloudsway.net/v1/ai/${Your endpoint}/kling/videos/multi-image2video/xiaoshuvideo03013018412' \
-H 'Authorization: Bearer ${Your AK}' \
-H 'Content-Type: application/json'

Response

{
    "code": 0,
    "message": "SUCCEED",
    "data": {
        "task_id": "xiaoshuvideo03013018412",
        "task_status": "succeed",
        "created_at": 1761532694501,
        "updated_at": 1761532868356,
        "task_status_msg": "",
        "task_info": {
            "external_task_id": "xiaoshuvideo03013018412"
        },
        "task_result": {
            "videos": [
                {
                    "id": "$videoId",
                    "url": "$videoUrl",
                    "duration": "10.433"
                }
            ]
        }
    },
    "request_id": "7b9cf699-3f13-4727-93da-a64faf0e1ab4"
}

Lip Sync

Face Recognition

Create Task

Request URL

https://genaiapi.cloudsway.net/v1/ai/${Your endpoint}/kling/videos/identify-face

Request Method

POST

Request Parameters

Field Type Required Default Value Description
video_id string Optional None ID of the video generated by Kling AI
Used to specify the video and determine if it can be used for lip-sync service. Choose one between video_id and video_url parameters, cannot be both empty or both have values.
Only supports videos generated within 30 days with duration not exceeding 60 seconds
video_url string Optional None URL for obtaining the uploaded video
Used to specify the video and determine if it can be used for lip-sync service.
Choose one between video_id and video_url parameters, cannot be both empty or both have values.
Video files support .mp4/.mov, file size not exceeding 100MB, video duration not exceeding 60s and not less than 2s, only supports 720p and 1080p, with both length and width between 512px and 2160px. If the above verification fails, error codes and other information will be returned.
The system will verify the video content, and if there is a problem, error codes and other information will be returned

Request Example

curl 'https://genaiapi.cloudsway.net/v1/ai/${Your endpoint}/kling/videos/identify-face' \
-H 'Authorization: Bearer ${Your AK}' \
-H 'Content-Type: application/json' \
-d '{
    "video_id": "811673266024099926"
}'

Response

{
    "code": 0,
    "message": "SUCCEED",
    "data": {
        "session_id": "811680659520897082",
        "face_data": [
            {
                "face_id": "0",
                "face_image": "https://p2-kling.klingai.com/bs2/upload-ylab-stunt/3d61a7fe-6ec2-51c7-976c-a35605783479.jpg?x-kcdn-pid=112452",
                "start_time": 0,
                "end_time": 5300
            }
        ]
    },
    "request_id": "91d74957-cdbc-4a85-b51a-c5da7d274203"
}

Lip Sync - Create Task

Request URL

https://genaiapi.cloudsway.net/v1/ai/${Your endpoint}/kling/videos/advanced-lip-sync

Request Method

POST

Request Parameters

Field Type Required Default Value Description
session_id string Required None Session ID, generated based on the lip-sync face recognition interface
face_choose array Required None Specify the face for lip-sync
Including face ID, lip reference, etc.
Temporarily only supports specifying a single person for lip-sync
face_choose
face_id		 string Required None Face ID returned by the face recognition interface
face_choose
audio_id		 string Optional Empty ID of the audio generated by the audition interface
Only supports audio generated within 30 days with duration not less than 2 seconds and not more than 60 seconds
Choose one between audio_id and sound_file parameters, cannot be both empty or both have values
face_choose
sound_file		 string Optional Empty Audio file
Supports passing in audio Base64 encoding or audio URL (ensure accessibility)
Audio files support .mp3/.wav/.m4a, file size not exceeding 5MB. Mismatched format or too large file will return error codes and other information.
Only supports audio with duration not less than 2 seconds and not more than 60 seconds.
Choose one between audio_id and sound_file parameters, cannot be both empty or both have values.
The system will verify the audio content, and if there is a problem, error codes and other information will be returned
face_choose
sound_start_time		 long Required None Audio clipping start point
Time is based on the start time of the original audio, starting at 0 minutes and 0 seconds, unit: ms
Audio before the start point will be clipped, and the clipped audio must not be shorter than 2 seconds
face_choose
sound_end_time		 long Required None Audio clipping end time
Based on the start time of the original audio, starting at 0 minutes and 0 seconds, unit: ms
Audio after the end point will be clipped, the clipped audio must not be shorter than 2 seconds, and the end time must not be later than the total duration of the original audio
face_choose
sound_insert_time		 long Required None Insertion time of the clipped audio is based on the start time of the video, with the video start time being 0 minutes and 0 seconds, unit: ms
The time range for inserting the audio must overlap with the lip-syncable time interval of the face by at least 2 seconds, the start time of inserting the audio must not be earlier than the video start time, and the end time of inserting the audio must not be later than the video end time
face_choose
sound_volume		 float Optional 1 Audio volume; the larger the value, the louder the volume
Value range: [0, 2]
face_choose
original_audio_volume		 float Optional 1 Original video volume; the larger the value, the louder the volume
Value range: [0, 2]
This parameter has no effect when the original video is silent
external_task_id string Optional None Custom task ID
User-defined task ID, which will not overwrite the system-generated task ID but supports task query through this ID.
Please note that uniqueness must be ensured under a single user
callback_url string Optional None Callback notification address for the task result. If configured, the server will actively notify when the task status changes.
See "Callback Protocol" for the specific notification message schema

Request Example

curl 'https://genaiapi.cloudsway.net/v1/ai/${Your endpoint}/kling/videos/advanced-lip-sync' \
-H 'Authorization: Bearer ${Your AK}' \
-H 'Content-Type: application/json' \
-d '{
    "session_id": "811981745335054341",
    "face_choose": [{
        "face_id": "0",
        "audio_id": "811982203088818203",
        "sound_start_time": 0,
        "sound_end_time": 5000,
        "sound_insert_time": 0,
        "sound_volume": 1,
        "original_audio_volume": 1
    }]
    ,"external_task_id": "xiaosuvideo12315"
}'

Response

{
    "code": 0,
    "message": "SUCCEED",
    "data": {
        "task_id": "xiaosuvideo12315",
        "task_status": "submitted",
        "created_at": 1761622385339,
        "updated_at": 1761622385339,
        "task_info": {
            "external_task_id": "xiaosuvideo12315"
        }
    },
    "request_id": "76edcdda-dfe0-496d-9e22-d52d59def11d"
}

Query Task (Single) Interface

Request URL

https://genaiapi.cloudsway.net/v1/ai/${Your endpoint}/kling/videos/advanced-lip-sync/{task_id}

Request Method

GET

Request Example

curl 'https://genaiapi.cloudsway.net/v1/ai/${Your endpoint}/kling/videos/advanced-lip-sync/xiaosuvideo12315' \
-H 'Authorization: Bearer ${Your AK}' \
-H 'Content-Type: application/json'

Response

{
    "code": 0,
    "message": "SUCCEED",
    "data": {
        "task_id": "xiaosuvideo12315",
        "task_status": "succeed",
        "created_at": 1761622385339,
        "updated_at": 1761622537187,
        "task_status_msg": "",
        "task_info": {
            "external_task_id": "xiaosuvideo12315",
            "parent_video": {
                "id": "811980644103909440",
                "url": "https://v2-kling.kechuangai.com/bs2/upload-ylab-stunt/special-effect/output/KLingMuse_2647d5b9-1732-4001-a61a-b02cd0b4a98f/-9118050841457038821/outputxzsta.mp4?x-kcdn-pid=112452",
                "duration": "5.041"
            }
        },
        "task_result": {
            "videos": [
                {
                    "id": "811991528977109066",
                    "url": "https://v1-kling.kechuangai.com/bs2/upload-ylab-stunt/special-effect/output/KLingMuse_bdbb1df5-aa71-435a-9cb7-c47e06018e73/-9211525537420341420/outputeuog5.mp4?x-kcdn-pid=112452",
                    "duration": "4.966"
                }
            ]
        }
    },
    "request_id": "2f4952ad-c67a-4828-89e1-094b1d7d368f"
}

MaaS_KeLing_O1_video

Create Subject

Request URL

https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/kling/general/custom-elements

Request Method

POST

Request Parameters

Field Type Required Default Value Description
element_name string Required None The subject name cannot exceed 20 characters
element_description string Required None The subject description cannot exceed 100 characters
element_frontal_image string Required None Front reference image of the subject
Supports passing image Base64 encoding or image URL (ensure accessibility)
Supported image formats: .jpg / .jpeg / .png
Image file size cannot exceed 10MB, image width and height are not less than 300px, and the aspect ratio is between 1:2.5 ~ 2.5:1
element_refer_list array Required None Other reference list of the subject
Define the subject's appearance by uploading multiple reference images from different angles
Upload at least 1 reference image and up to 3 reference images
Carried by key:value, as follows: "element_refer_list":[ {"image_url":"image_url_1"}, {"image_url":"image_url_2"}, {"image_url":"image_url_3"} ]

Request Example

curl 'https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/kling/general/custom-elements' \
-H 'Authorization: Bearer {Your AK}' \
-H 'Content-Type: application/json' \
-d '{
    "element_name": "test1215",
    "element_description": "主体1215",
    "element_frontal_image": "https://h2.inkwai.com/bs2/upload-ylab-stunt/se/ai_portal_queue_mmu_image_upscale_aiweb/3214b798-e1b4-4b00-b7af-72b5b0417420_raw_image_0.jpg",
    "element_refer_list": [{"image_url": "https://pic.rmb.bdstatic.com/bjh/bc1f43c8145/250803/b54dfc3bfc76b6f83a11662e34199d4f.jpeg"}]
}'

Return Value Example

{
  "code": 0, //Error code; see error code for specific definition
  "message": "string", //Error message
  "request_id": "string", //Request ID, generated by the system, used to track requests and troubleshoot problems
  "data":{
    "element_id": long,
    "element_name": "string",
    "element_description": "string",
    "element_frontal_image":"image_url_0",
    "element_refer_list":[
      {"image_url":"image_url_1"},
      {"image_url":"image_url_2"},
      {"image_url":"image_url_3"}
    ],
    "owned_by": "kling" // Subject source, "kling" for official subject library, numbers for creator ID
  }
}

Query Personal Subject List

Request URL

https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/kling/general/custom-elements?pageNum=1&pageSize=30

Request Method

GET

Query Parameters

Field Type Required Default Value Description
pageNum int Optional 1 Page number range: [1,1000]
pageSize int Optional 30 Page size range: [1,500]

Return Value Example

{
  "code": 0, //Error code; see error code for specific definition
  "message": "string", //Error message
  "request_id": "string", //Request ID, generated by the system, used to track requests and troubleshoot problems
  "data":[
    {
      "element_id": long,
      "element_name": "string",
      "element_description": "string",
      "element_frontal_image":"image_url_0",
      "element_refer_list":[
        {"image_url":"image_url_1"},
        {"image_url":"image_url_2"},
        {"image_url":"image_url_3"}
      ],
      "owned_by": "kling" // Subject source, "kling" for official subject library, others for creator ID
    }
  ]
}

Query Official Subject List

Request URL

https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/kling/general/presets-elements?pageNum=1&pageSize=30

Request Method

GET

Query Parameters

Field Type Required Default Value Description
pageNum int Optional 1 Page number range: [1,1000]
pageSize int Optional 30 Page size range: [1,500]

Return Value Example


{
  "code": 0, //Error code; see error code for specific definition
  "message": "string", //Error message
  "request_id": "string", //Request ID, generated by the system, used to track requests and troubleshoot problems
  "data":[
    {
      "element_id": long,
      "element_name": "string",
      "element_description": "string",
      "element_frontal_image":"image_url_0",
      "element_refer_list":[
        {"image_url":"image_url_1"},
        {"image_url":"image_url_2"},
        {"image_url":"image_url_3"}
      ],
      "tag_list":[
        {
          "id": "o_101",
          "name": "animal",
          "description": "The content of description."
        },
        {
          "id": "o_102",
          "name": "animal",
          "description": "The content of description."
        }
      ],
       "owned_by": "kling" // Subject source, "kling" for official subject library, others for creator ID
    }
  ]
}

Create Video Generation Task Interface

Request URL

https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/kling/videos/omni-video

Request Method

GET

Request Parameters

Field Type Required Default Value Description
prompt string Required None Text prompt, which can include positive and negative descriptions. The prompt can be templated to meet different video generation needs and cannot exceed 2500 characters. Specify a subject, image, or video in the format of <<<>>>, such as: <<>>, <<>>, <<>>
image_list array Optional Empty Reference image list, including reference images for subjects, scenes, styles, etc., and can also be used as the first or last frame to generate videos; when used as the first or last frame to generate videos: Define whether the image is the first/last frame through the type parameter: "first_frame" for the first frame, "end_frame" for the last frame. Only the last frame is not supported temporarily, i.e., if there is a last frame image, there must be a first frame image. When generating videos with the first frame or first and last frames, video editing functions cannot be used. Carried by key:value, as follows: "image_list":[ { "image_url":"image_url", "type":"first_frame" }, { "image_url":"image_url", "type":"end_frame" } ]. Supports passing image Base64 encoding or image URL (ensure accessibility). Supported image formats: .jpg / .jpeg / .png. Image file size cannot exceed 10MB, image width and height are not less than 300px, and the aspect ratio is between 1:2.5 ~ 2.5:1. When there are reference videos, the number of reference images shall not exceed 4; when there are no reference videos, the number of reference images shall not exceed 7. When there are more than 2 images in the array, setting the last frame is not supported
element_list array Optional Empty Subject reference list, configured based on the ID of the subject in the subject library, carried by key:value, as follows: "element_list":[ { "element_id":long } ]. The number of reference subjects is related to the presence of reference videos and the number of reference images, among which: When there are reference videos, the sum of the number of reference images and reference subjects shall not exceed 4; when there are no reference videos, the sum of the number of reference images and reference subjects shall not exceed 7
video_list array Optional Empty Reference video, obtained through URL. Can be used as a feature reference video or a video to be edited, default is the video to be edited; the original sound of the video can be optionally retained. Distinguish the type of reference video through the refer_type parameter: "feature" for feature reference video, "base" for video to be edited. When the reference video is a video to be edited, the first and last frames of the video cannot be defined. Select whether to retain the original sound of the video through the keep_original_sound parameter: "yes" to retain, "no" to not retain; this parameter is also valid for feature reference videos ("feature"). Carried by key:value, as follows: "video_list":[ { "video_url":"video_url", "refer_type":"base", "keep_original_sound":"yes" } ]. Supported video formats: MP4/MOV only. Only videos with duration ≥3 seconds and ≤10 seconds are supported. Video width and height must be between 720px (inclusive) and 2160px (inclusive). Video frame rate is based on 24fps～60fps, and the generated video will be output as 24fps. Only 1 video can be uploaded at most, and the video size shall not exceed 200MB
mode string Optional pro Video generation mode, enumeration values: std, pro
std: Standard mode (standard), basic mode with high cost performance
pro: Pro mode (high quality), high-performance mode with better video generation quality
aspect_ratio string Optional Empty Aspect ratio (width:height) of the generated video, enumeration values: 16:9, 9:16, 1:1.
This parameter is required when the first frame reference or video editing function is not used
duration string Optional 5 Duration of the generated video, unit: s, enumeration values: 3, 4, 5, 6, 7, 8, 9, 10. Among them: When using text-to-video, first-frame image-to-video, or first-and-last-frame image-to-video, only 5s and 10s are supported. When using the video editing function ("refer_type":"base"), the output result has the same duration as the incoming video, and this parameter is invalid at this time; at this time, the billing is calculated by rounding up the duration of the input video to the nearest integer
callback_url string Optional Empty Callback notification address for the result of this task. If configured, the server will actively notify when the task status changes.
See "Callback Protocol" for the specific message schema of the notification
external_task_id string Optional Empty Custom task ID. The custom task ID passed in will not overwrite the task ID generated by the system, but querying tasks through this ID is supported. Please note that uniqueness must be guaranteed under a single user

Request Example

curl --location --request POST 'https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/kling/videos/omni-video' \
--header 'Authorization: Bearer {Your AK}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "prompt": "Based on <<<element_1>>>, generate a shot of the character in the picture moving forward, with a faint Buddha light shining in the distant sky",
    "mode": "pro",
    "aspect_ratio":"16:9",
    "element_list": [
        {
            "element_id": 829376081165181009
        }
    ]
}'

Return Value Example


{
  "code": 0, //Error code
  "message": "string", //Error message
  "request_id": "string", //Request ID, generated by the system, used to track requests and troubleshoot problems
  "data":{
        "task_id": "string", //Task ID, generated by the system
        "task_info":{ //Parameter information when the task was created
            "external_task_id": "string"//Custom task ID of the customer
        }, 
    "task_status": "string", //Task status, enumeration values: submitted (submitted), processing (processing), succeed (succeeded), failed (failed)
    "created_at": 1722769557708, //Task creation time, Unix timestamp, unit: ms
    "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms
  }
}

Query Video Task Interface

Request URL

https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/kling/videos/omni-video/{id}

Request Method

GET

Request Parameters

Field Type Required Default Value Description
task_id string Optional None Task ID of text-to-video, request path parameter, fill the value directly in the request path. Choose one of the two query methods: task_id and external_task_id
external_task_id string Optional None Custom task ID of text-to-video, the external_task_id filled in when creating the task. Choose one of the two query methods: task_id and external_task_id

Return Value Example

{
  "code": 0, //Error code; see error code for specific definition
  "message": "string", //Error message
  "request_id": "string", //Request ID, generated by the system, used to track requests and troubleshoot problems
  "data":{
          "task_id": "string", //Task ID, generated by the system 
    "task_status": "string", //Task status, enumeration values: submitted (submitted), processing (processing), succeed (succeeded), failed (failed)
    "task_status_msg": "string", //Task status information, showing the failure reason when the task fails (such as triggering the platform's content risk control, etc.)
    "task_info": { //Parameter information when the task was created
      "external_task_id": "string"//Custom task ID of the customer
    },
    "task_result":{
      "videos":[
        {
           "id": "string", //Generated video ID; globally unique
           "url": "string", //URL of the generated video, anti-leech format (please note that to ensure information security, generated images/videos will be deleted after 30 days, please save them in a timely manner)
           "duration": "string" //Total duration of the video, unit: s
        }
      ]
    },
    "created_at": 1722769557708, //Task creation time, Unix timestamp, unit: ms
    "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms
  }
}

MaaS_KeLing_O1_image

Create Image Generation Task Interface

Request URL

https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/kling/images/omni-image

Request Method

POST

Request Parameters

Field Type Required Default Value Description
prompt string Required None Text prompt, which can include positive and negative descriptions. The prompt can be templated to meet different image generation needs and cannot exceed 2500 characters. Specify an image in the format of <<<>>>, such as: <<>>
image_list array Optional Empty Reference image list, carried by key:value, as follows: "image_list":[ { "image":"image_url", } ]
Supports passing image Base64 encoding or image URL (ensure accessibility)
Supported image formats: .jpg / .jpeg / .png
Image file size cannot exceed 10MB,
image width and height are not less than 300px,
aspect ratio is between 1:2.5 ~ 2.5:1
Number of images shall not exceed 10
element_list array Optional Empty Subject reference list, configured based on the ID of the subject in the subject library, carried by key:value, as follows: "element_list":[ { "element_id":long } ]
The number of reference subjects is related to the number of reference images, and the sum of the number of reference subjects and reference images shall not exceed 10
resolution string Optional 1k Clarity of the generated image, enumeration values: 1k, 2k
1k: 1K standard definition
2k: 2K high definition
n int Optional 1 Number of generated images, value range: [1,9]
aspect_ratio string Optional auto Aspect ratio (width:height) of the generated image, enumeration values: 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9, auto.
Among them: "auto" means intelligently generate according to the incoming content. When generating a new image with reference to the aspect ratio of the original image, this parameter is invalid
callback_url string Optional None Callback notification address for the result of this task. If configured, the server will actively notify when the task status changes.
See "Callback Protocol" for the specific message schema of the notification

Request Example

curl --location --request POST 'https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/kling/videos/omni-image' \
--header 'Authorization: Bearer {Your AK}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "prompt": "Two pink koi fish swim gracefully side by side",
    "n": 1
}'

Return Value Example

{
    "code": 0,
    "message": "SUCCEED",
    "data": {
        "task_id": "788872612687921228",
        "task_status": "submitted",
        "created_at": 1756110406193,
        "updated_at": 1756110406193,
        "task_info": {
            "external_task_id": null
        }
    },
    "request_id": "227483a7-2a00-4028-ba42-21fc8bff3ffb"
}

Query Image Task Interface

Request URL

https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/kling/images/omni-image/{id}

Request Method

GET

Request Parameters

Field Type Required Default Value Description
task_id string Required None Task ID of image generation, request path parameter, fill the value directly in the request path

Return Value Example

{
  "code": 0, //Error code; see error code for specific definition
  "message": "string", //Error message
  "request_id": "string", //Request ID, generated by the system, used to track requests and troubleshoot problems
  "data":{
    "task_id": "string", //Task ID, generated by the system
    "task_status": "string", //Task status, enumeration values: submitted (submitted), processing (processing), succeed (succeeded), failed (failed)
    "task_status_msg": "string", //Task status information, showing the failure reason when the task fails (such as triggering the platform's content risk control, etc.)
    "task_info": { //Parameter information when the task was created
        "external_task_id": "string"//Custom task ID of the customer
    },
    "task_result":{
            "images":[
              {
                "index": int, //Image number, 0-9
                "url": "string" //URL of the generated image, anti-leech format (please note that to ensure information security, generated images/videos will be deleted after 30 days, please save them in a timely manner)
              }
            ]
    },
    "created_at": 1722769557708, //Task creation time, Unix timestamp, unit: ms
    "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms
  }
}

Digital Human

Create Task

Request URL

https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/kling/videos/avatar/image2video

Request Method

POST

Request Parameters

Field Type Required Default Value Description
image string Required None Digital human reference image
  • Supports passing image Base64 encoding or image URL (ensure accessibility)
Please note that if you use the base64 method, ensure that all your image data parameters are in Base64 encoding format. When submitting data, do not add any prefixes before the Base64 encoded string, such as data:image/png;base64,. The correct parameter format should be the Base64 encoded string directly. Example: Correct Base64 encoded parameter:
1
iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==
Incorrect Base64 encoded parameter (contains data: prefix):
1
data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==
Please provide only the Base64 encoded string part so that the system can process and parse your data correctly.
  • Supported image formats: .jpg / .jpeg / .png
  • Image file size cannot exceed 10MB, image width and height are not less than 300px, and the aspect ratio is between 1:2.5 ~ 2.5:1
audio_id string Optional Empty Audio ID generated through the audition interface
  • Only supports audio generated within 30 days, with a duration of no less than 2 seconds and no more than 300 seconds
  • One of the audio_id and sound_file parameters must be selected; they cannot be empty at the same time, nor can they have values at the same time
sound_file string Optional Empty Audio file
  • Supports passing audio Base64 encoding or audio URL (ensure accessibility)
  • Supported audio formats: .mp3/.wav/.m4a/.aac (standard audio/aac format). Files that do not match the format or are too large will return error codes and other information. The file size cannot exceed 5MB.
  • Only supports audio with a duration of no less than 2 seconds and no more than 300 seconds
  • One of the audio_id and sound_file parameters must be selected; they cannot be empty at the same time, nor can they have values at the same time
  • The system will verify the audio content, and return error codes and other information if there are any issues
prompt string Optional Empty Positive text prompt
  • Can define digital human movements, emotions, camera movements, etc.
  • Cannot exceed 2500 characters
mode string Optional std Generated video mode
  • Enumerated values: std, pro
  • std: Standard mode (basic mode), cost-effective
  • pro: Pro mode (high quality), high-performance mode, generates videos with better quality
callback_url string Optional None Callback notification address for the results of this task. If configured, the server will actively notify when the task status changes
  • See "Callback Protocol" for the specific notification message schema
external_task_id string Optional Empty Custom task ID
  • User-defined task ID. Passing it in will not overwrite the task ID generated by the system, but querying tasks through this ID is supported
  • Please note that uniqueness must be guaranteed under a single user

Request Example

curl --location --request POST 'https://genaiapi.cloudsway.net/v1/ai/{Your endpoint}/kling/videos/avatar/image2video' \
--header 'Authorization: Bearer {YOUR_AK}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "prompt": "An ancient-style girl singing an ancient-style song",
    "image": "https://p4-fdl.klingai.com/ksc2/TYBZGeCy2X-AlFG2BzHJ99DxeGPQbOjXamDu3v9Ecq_e1eVlu7H6D_7IaorVJr3aH2UyymnOb_3CRnbu2QnLT3C1hFoLUFPb3j6cJSPP_PIcVEtEEDaSrmRLy50znof-z86Vbg9peLFFbQd9aXFM4h3q3DjVzXP22cgxCkJKzJ-GxXn9qQOm8P_Qd-rVy_CbUL6j_X5lriXPkG9YE1WUaQ.png?cacheKey=ChtzZWN1cml0eS5rbGluZy5tZXRhX2VuY3J5cHQSsAEAMvnTk2zeXWfHeE0x9-pJh5qSzTyipQE_qi7aNWPgsddpyhPpG1XOFZN8VC6pYGtcInKWCqBjsY_Zl1MnQaGffyadf_kRG2g781a0d3ikEVHJeZiCt0gJrQCv6mWm8HgW53FZ1UXtupVe1FJnkLMa5JCneEIJbHkXnms2Y2UwuMl4n9fzbdM6MhKVFmIkwu2saYsguXLHUBAkSspuTQa2_S00cGfMA68qPJQeFlgp5BoSiLisQ3JW5QwpPz64VCCZ6-c0IiAUG1fwWBGOMfuSHLam2QirUp0YC0HTBFqFSZnYSqQIgSgFMAE&x-kcdn-pid=112757&pkey=AAX9eJQ7p7gVFmiSYauqc3rcObOQZTQe4Z-HxAnAq7xbot2_iV48hlKJKUvAsvHQVak75dca3mJ5SippG1VL4HWbOJmksckSyffvVHVKk-p-q19Vkc1JZ9sK2aaYeDFVLBI",
    "sound_file":"https://cdn.mureka.ai/cos-prod/open/song/20251229/113366463152129-9DDrRrRu26n4iifY3Rgbyb.mp3"
}'

Return Value Example

{
  "code": 0, //Error code; see error codes for specific definitions
  "message": "string", //Error message
  "request_id": "string", //Request ID, generated by the system, used to track requests and troubleshoot problems
  "data":{
    "task_id": "string", //Task ID, generated by the system
    "task_info":{ //Parameter information at task creation
       "external_task_id": "string" //Customer-defined task ID
    }, 
    "task_status": "string", //Task status, enumerated values: submitted (submitted), processing (processing), succeed (succeeded), failed (failed)
    "created_at": 1722769557708, //Task creation time, Unix timestamp, unit: ms
    "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms
  }
}

Query Task

Request URL

https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/kling/videos/avatar/image2video/{task_id}

Request Method

GET

Request Parameters

Field Type Required Default Value Description
task_id string Optional None Digital human task ID
Request path parameter, fill the value directly in the request path

Return Value Example

{
  "code": 0, //Error code; see error codes for specific definitions
  "message": "string", //Error message
  "request_id": "string", //Request ID, generated by the system, used to track requests and troubleshoot problems
  "data":{
          "task_id": "string", //Task ID, generated by the system
    "task_status": "string", //Task status, enumerated values: submitted (submitted), processing (processing), succeed (succeeded), failed (failed)
    "task_status_msg": "string", //Task status information, displays the reason for failure when the task fails (such as triggering platform content risk control, etc.)
    "task_info": { //Parameter information at task creation
      "external_task_id": "string"//Customer-defined task ID
    },
    "task_result":{
      "videos":[
        {
                "id": "string", //Generated video ID; globally unique
                      "url": "string", //URL of the generated video, e.g., https://p1.a.kwimgs.com/bs2/upload-ylab-stunt/special-effect/output/HB1_PROD_ai_web_46554461/-2878350957757294165/output.mp4 (Please note that for information security, generated images/videos will be deleted after 30 days, please transfer and save them in a timely manner)
                      "duration": "string" //Total video duration, unit: s
        }
      ]
    },
    "created_at": 1722769557708, //Task creation time, Unix timestamp, unit: ms
    "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms
  }
}

Custom Voices

Create Task

Request URL

https://genaiapi.cloudsway.net/v1/ai/{Your EndpointPath}/kling/general/custom-voices

Request Method

POST

Request Parameters

Field Type Required Default Value Description
voice_name string Yes None The text content of the voice name has a maximum length of 20 characters.

Voices that are no longer used after creation can be deleted via API.
voice_url string No Empty The access link of the voice data file
Supports audio and video files in .mp3/.wav/.mp4/.mov formats
The human voice in the audio must be clear and free of noise, with exactly one type of human voice, and the duration is not less than 5 seconds and not more than 30 seconds.
video_id string No Empty Historical work ID, audio materials can be provided by referencing historical works
Only videos that meet the following conditions can be used to customize voices:
- Videos generated using the V2.6 version model with the sound parameter set to "on"
- Videos generated via the digital human API
- Videos generated via the lip-sync API
The human voice in the audio must be clear and free of noise, with exactly one type of human voice, and the duration is not less than 5 seconds and not more than 30 seconds.
callback_url string No Empty The callback notification address for the result of this task. If configured, the server will actively notify when the task status changes.
See "Callback Protocol" for the specific message schema of the notification.
external_task_id string No Empty Custom task ID
User-defined task ID, the input will not overwrite the task ID generated by the system, but querying the task through this ID is supported.
Please note that uniqueness must be guaranteed under a single user.

Request Example

curl 'https://genaiapi.cloudsway.net/v1/ai/{Your EndpointPath}/kling/general/custom-voices' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {Your AK}' \
-d '{
    "voice_name": "test-voice",
    "voice_url": "https://v2-kling.kechuangai.com/bs2/upload-ylab-stunt/muse/740716864409964585/AUDIO/20251216/025ff2750c32f78bc8e52bc60cb236ed-bf7eb2e6-928b-4495-a6cd-9e2c3d83b446.quality.wav?x-kcdn-pid=112452"   
}'

Return Value Example

{
    "code": 0,
    "message": "SUCCEED",
    "data": {
        "task_id": "835272998948442209",
        "task_status": "submitted",
        "created_at": 1767173120352,
        "updated_at": 1767173120352
    },
    "request_id": "cfc94959-fd20-49e2-aa49-1d162a0998c8"
}

Query Task (Single)

Request URL

https://genaiapi.cloudsway.net/v1/ai/{Your EndpointPath}/kling/general/custom-voices/{id}

Request Method

GET

Query Parameters

Field Type Required Default Value Description
task_id string Yes None The text content of the voice name has a maximum length of 20 characters. Voices that are no longer used after creation can be deleted via API.

Request Example

curl 'https://genaiapi.cloudsway.net/v1/ai/{Your EndpointPath}/kling/general/custom-voices/{id}' \
-H 'Authorization: Bearer {Your AK}' \
-H 'Content-Type: application/json'

Return Value Example

{
    "code": 0,
    "message": "SUCCEED",
    "data": {
        "task_id": "835272998948442209",
        "task_status": "succeed",
        "created_at": 1767173120352,
        "updated_at": 1767173126634,
        "task_status_msg": "",
        "task_info": {},
        "task_result": {
            "voices": [
                {
                    "status": "succeed",
                    "voice_id": "835273025011847183",
                    "voice_name": "test-voice",
                    "trial_url": "https://v2-kling.kechuangai.com/bs2/upload-ylab-stunt/muse/766442945620226100/AUDIO/20251231/e84146fabb9eeb7cab43284c1759ccee-8cd6e58d-d718-406b-a88d-c50b9eac516e.quality.wav?x-kcdn-pid=112452",
                    "owned_by": "766442945620226100"
                }
            ]
        }
    },
    "request_id": "de722951-57db-40fc-89e7-4f87fcecfdd8"
}

Query Task (List)

Request URL

https://genaiapi.cloudsway.net/v1/ai/{Your EndpointPath}/kling/general/custom-voices?pageNum=1&pageSize=10

Request Method

GET

Query Parameters

Field Type Required Default Value Description
pageNum int No 1 Page number
Value range: [1,1000]
pageSize int No 30 Number of data per page
Value range: [1,500]

Request Example

curl 'https://genaiapi.cloudsway.net/v1/ai/{Your EndpointPath}/kling/general/custom-voices' \
-H 'Authorization: Bearer {Your AK}' \
-H 'Content-Type: application/json'

Return Value Example

{
    "code": 0,
    "message": "SUCCEED",
    "data": [
        {
            "task_id": "835272998948442209",
            "task_status": "succeed",
            "created_at": 1767173120352,
            "updated_at": 1767173126634,
            "task_status_msg": "",
            "task_info": {},
            "task_result": {
                "voices": [
                    {
                        "status": "succeed",
                        "voice_id": "835273025011847183",
                        "voice_name": "test-voice",
                        "trial_url": "https://v2-kling.kechuangai.com/bs2/upload-ylab-stunt/muse/766442945620226100/AUDIO/20251231/e84146fabb9eeb7cab43284c1759ccee-8cd6e58d-d718-406b-a88d-c50b9eac516e.quality.wav?x-kcdn-pid=112452",
                        "owned_by": "766442945620226100"
                    }
                ]
            }
        }
    ],
    "request_id": "017cd6d7-e23a-48a2-9948-1f1c7bc5b881"
}

Query Official Voices (List)

Request URL

https://genaiapi.cloudsway.net/v1/ai/{Your EndpointPath}/kling/general/presets-voices?pageNum=1&pageSize=10

Request Method

GET

Query Parameters

Field Type Required Default Value Description
pageNum int No 1 Page number
Value range: [1,1000]
pageSize int No 30 Number of data per page
Value range: [1,500]

Request Example

curl 'https://genaiapi.cloudsway.net/v1/ai/{Your EndpointPath}/kling/general/presets-voices' \
-H 'Authorization: Bearer {Your AK}' \
-H 'Content-Type: application/json'

Return Value Example

{
    "code": 0,
    "message": "SUCCEED",
    "data": [
        {
            "task_id": "829824269219016728",
            "task_status": "succeed",
            "created_at": 1765874041961,
            "updated_at": 1765874050974,
            "task_status_msg": "",
            "task_info": {},
            "task_result": {
                "voices": [
                    {
                        "status": "succeed",
                        "voice_id": "829824295735410756",
                        "voice_name": "Fishing-style Girlfriend",
                        "trial_url": "https://v2-kling.kechuangai.com/bs2/upload-ylab-stunt/muse/740716864409964585/AUDIO/20251216/025ff2750c32f78bc8e52bc60cb236ed-bf7eb2e6-928b-4495-a6cd-9e2c3d83b446.quality.wav?x-kcdn-pid=112452",
                        "owned_by": "kling"
                    }
                ]
            }
        }
    ],
    "request_id": "58dc8c8a-329b-417f-852c-7521208f6608"
}

Delete Custom Voice

Request URL

https://genaiapi.cloudsway.net/v1/ai/{Your EndpointPath}/kling/general/delete-voices

Request Method

POST

Request Parameters

Field Type Required Default Value Description
voice_id string Yes None The ID of the voice to be deleted, only custom voices can be deleted.

Request Example

curl 'https://genaiapi.cloudsway.net/v1/ai/{Your EndpointPath}/kling/general/delete-voices' \
-H 'Authorization: Bearer {Your AK}' \
-H 'Content-Type: application/json' \
-d '{
    "voice_id": "834903862980546647"
}'

Return Value Example

{
    "code": 0,
    "message": "SUCCEED",
    "data": {
        "task_id": "836664805456519242",
        "task_status": "succeed",
        "created_at": 1767504952883,
        "updated_at": 1767504958656,
        "task_info": {}
    },
    "request_id": "e279b45c-cf82-4827-881c-48c1fa1062fd"
}

Specify Voice in MaaS_KeLing_V2.6

Refer to the Kling Upgrade Development and Design Document for the Image-to-Video interface.

Request Example

curl 'https://genaiapi.cloudsway.net/v1/ai/{Your EndpointPath}/kling/videos/image2video' \
-H 'Authorization: Bearer {Your AK}' \
-H 'Content-Type: application/json' \
--data-raw '{
    "model_name": "kling-v2.6",
    "prompt": "Mom<<<voice_1>>> said it was written neatly, but there was a wrong character. The daughter used the eraser on the other end of the pen to erase the wrong character and said, then I will correct it",
    "image": "https://pics1.baidu.com/feed/241f95cad1c8a786003b9db123e5023271cf507c.png@f_auto?token=02598e30013d54c67fcc0f877e36adf4",
    "mode": "pro",
    "sound": "on",
    "voice_list": [{"voice_id":"836673622449741875"}],
    "aspect_ratio": "16:9",
    "duration": "5",
    "external_task_id": "xiaosuaivideo0104"
}'

Motion Control

Create Task

Request URL

https://genaiapi.cloudsway.net/v1/ai/{endpoinPath}/kling/videos/motion-control

Request Method

POST

Request Parameters

Field Type Required Default Value Description
prompt string Optional Empty Text prompt, which can include positive and negative descriptions.
Elements can be added to the frame and camera movement effects can be achieved through prompts.
Cannot exceed 2500 characters.
image_url string Required None Reference image. The characters, backgrounds and other elements in the generated video are all based on the reference image.
The video content must meet the following requirements:
The character proportion should be as consistent as possible with the reference action proportion, and try to avoid generating a half-body character driven by a full-body action.
The character needs to expose clear upper body or full body limbs and head to avoid occlusion.
Avoid extreme orientations of the character in the frame, such as handstands, lying down, etc. The proportion of the character in the frame should not be too low.
Supports real/stylized characters (including humans/human-like animals/some pure animals/some characters with human-like limb proportions) to pass.
Supports passing in image Base64 encoding or image URL (ensure accessibility).
Please note that if you use the base64 method, ensure that all your transmitted image data parameters are in Base64 encoding format. When submitting data, do not add any prefixes before the Base64 encoded string, such as data:image/png;base64,. The correct parameter format should be the Base64 encoded string directly.

Supported image formats: .jpg / .jpeg / .png.
The image file size cannot exceed 10MB, the width and height of the image are between 300px and 65536px, and the aspect ratio of the image is between 1:2.5 and 2.5:1.
video_url string Required None Acquisition link of the reference video. The character movements in the generated video are consistent with those in the reference video.
The video content must meet the following requirements: The character needs to expose clear upper body or full body limbs and head to avoid occlusion.
It is recommended to upload a video of one person's movements; for videos with two or more people, the movements of the character with the largest proportion in the frame will be used for generation.
It is recommended to use real human movements; some stylized characters/human-like limb proportions are acceptable.
The action video should be a single shot, with the character always appearing in the frame, avoiding scene cuts, camera movements, etc. Otherwise, it will be intercepted.
Movements should be avoided being too fast; relatively smooth movements will result in better generation effects.
Supported video formats: .mp4/.mov, file size cannot exceed 100MB, only the side lengths of width and height are between 340px and 3850px. If the above verification fails, error codes and other information will be returned.
The minimum video duration is not less than 3 seconds, and the maximum duration is related to the character orientation reference (character_orientation): when the character orientation is consistent with the character in the video, the maximum video duration can reach 30 seconds;
when the character orientation is consistent with the character in the image, the maximum video duration can reach 10 seconds;
If your action is relatively difficult and fast, there is a certain probability that the generated result will be shorter than the uploaded video duration, because the model can only extract the effective action duration for generation, and it can generate as long as 3s of available continuous actions are extracted. Please note that the points consumed thus cannot be refunded, so it is recommended to appropriately adjust the difficulty and speed of the action.
The system will verify the video content, and return error codes and other information if there are any problems.
keep_original_sound string Optional yes Optional to keep the original sound of the video.
Enumerated values: yes, no.
Among them, yes: keep the original sound of the video;
no: do not keep the original sound of the video.
character_orientation string Required None The orientation of the character in the generated video, which can be selected to be consistent with the image or the video.
Enumerated values: image, video, where:
image: consistent with the character orientation in the image; at this time, the duration of the reference video shall not exceed 10 seconds;
video: consistent with the character orientation in the video; at this time, the duration of the reference video shall not exceed 30 seconds.
mode string Required None Enumerated values for the generated video mode: std, pro.
Among them, std: standard mode (Standard), basic mode with high cost performance;
pro: professional mode (High Quality), high-performance mode with better generated video quality.
callback_url string Optional None Callback notification address for the result of this task. If configured, the server will actively notify when the task status changes.
external_task_id string Optional None Custom task ID.
User-defined task ID, passing it in will not overwrite the task ID generated by the system, but supports querying tasks through this ID.
Please note that uniqueness must be ensured under a single user.

Request Example

curl 'https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/kling/videos/motion-control' \
-H 'Authorization: Bearer {Your AK}' \
-H 'Content-Type: application/json' \
-d '{
    "prompt": "",
    "image_url": "",
    "video_url": "",
    "keep_original_sound": "no",
    "character_orientation": "image",
    "mode": "std"
}'

Query Task

Request URL

https://genaiapi.cloudsway.net/v1/ai/{endpoinPath}/kling/videos/motion-control/{taskId}

Request Method

GET

Request Example

curl 'https://genaiapi.cloudsway.net/v1/ai/{{endpointPath}}/kling/videos/motion-control/{{taskId}}' \
-H 'Authorization: Bearer {Your AK}' \
-H 'Content-Type: application/json'