MaaS_KL Interface Documentation
Request Protocol
Http
Header
| Parameter Name | Type | Description |
|---|---|---|
| Authorization | string | Authentication |
Video Generation - 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.5, MaaS_KL_V1.6, MaaS_KL_V1 |
| prompt | string | Required | 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, see current document 3-0 capability map for details |
| 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, see current document 3-0 capability map for details |
| 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
}
}
Video Generation - Text to Video - 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
}
}
Video Generation - 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.5, MaaS_KL_V1.6, MaaS_KL_V1 |
| 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, see the current document 3-0 capability map for details |
| 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, see current document 3-0 capability map for details |
| 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, see current document 3-0 capability map for details |
| 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, see current document 3-0 capability map for details |
| 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
}
}
Video Generation - Image to Video - 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 Generation - 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 (only supports V1.0 model, not V1.5 model)
- Supports video IDs generated by the image-to-video interface (only supports V1.0 model, not V1.5 model)
- 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 (only supports V1.0 model, not V1.5 model) - Supports video IDs generated by the image-to-video interface (only supports V1.0 model, not V1.5 model) - 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
Here's the English translation of the content, maintaining the original format:
{
"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
}
}
Video Generation - Video Extension - 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
}
}