MaaS_KeLing_3.0 Interface Documentation

Request Protocol

http

Header

Text-to-Video

Create Task

Request URL

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

Request Method

POST

Request Parameters

Field	Type	Required	Default Value	Description
model_name	string	Optional	kling-v1	Model Enum Values：kling-v1, kling-v1-5, kling-v2-master, kling-v2-1-master, kling-v2-5-turbo, kling-v2-6, kling-v3
multi_shot	boolean	Optional	false	Whether to generate a multi-shot video ● When the current parameter is true, the prompt parameter is invalid ● When the current parameter is false, the shot_type parameter and the multi_prompt parameter are invalid
shot_type	string	Optional	Empty	Storyboard Method ● Enumerated values: customize, intelligence ● When the multi_shot parameter is true and the shot_type parameter is customize, the current parameter must be filled in
prompt	string	Optional	Empty	Text prompt, which can include positive and negative descriptions ● Prompts can be templated to meet different video generation needs ● Must not exceed 2500 characters. The Omni model can achieve various capabilities through Prompt with content such as subjects, images, and videos: 1. Specify a certain subject, image, or video in the format of <<<>>>, for example: <<<element_1>>>, <<<image_1>>>, <<<video_1>>> ● When the multi_shot parameter is false or the shot_type parameter is intelligence, the current parameter must be filled in
multi_prompt	array	Optional	Empty	Each shot prompt may include positive and negative descriptions ● Define the shot number, corresponding prompt, and duration through the index, prompt, and duration parameters, where: ○ Supports up to 6 shots and at least 1 shot ○ The maximum length of each shot-related content does not exceed 512 ○ The duration of each shot is no greater than the total duration of the current task and no less than 1 ○ The sum of the durations of all storyboards equals the total duration of the current task ● Use key:value to carry, as follows: "multi_prompt":[ { "index":int, "prompt": "string", "duration": "5" }, { "index":int, "prompt": "string", "duration": "5" } ] ● When the multi_shot parameter is true and the shot_type parameter is customize, the current parameter must not be empty
negative_prompt	string	Optional	Empty	Negative text prompt ● It is recommended to incorporate negative prompts into positive prompts using negative descriptions. ● Must not exceed 2,500 characters
sound	string	Optional	off	Whether to generate sound simultaneously when generating a video ● Enumerated values:on, off Only models of version V2.6 and above support the current parameters
mode	string	Optional	std	Mode of generating videos ● Enumerated values:std, pro ● Among them, std: Standard Mode (Standard), basic mode, generates 720P video, with high cost-effectiveness ● Among them, pro: Expert Mode (High Quality), High Performance Mode, generates 1080P videos with better video quality Different model versions support different ranges of capabilities, see the above Capability Map for details
aspect_ratio	string	Optional	16:9	Aspect ratio (width:height) of the generated video ● Enumerated values:16:9, 9:16, 1:1
duration	string	Optional	5	Generated video duration, unit: s ● Enumerated values: 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 Different model versions support different ranges of capabilities, see the above capabilities map for details
watermark_info	array	Optional	Empty	Whether to generate watermarked results simultaneously ● Defined by the enabled parameter, carried with key:value, as follows: "watermark_info": { "enabled": boolean // true for generation, false for no generation } ● Custom watermark is not currently supported
external_task_id	string	Optional	None	Custom Task ID● User-defined task ID. Passing it in will not overwrite the system-generated task ID, but it supports task query via this ID● Please note that uniqueness needs to be ensured for a single user

Request Example

curl --location 'https://genaiapi.cloudsway.net/v1/ai/${Your Endpoint}/kling/videos/text2video' \
--header 'Authorization: Bearer ${Your AK}' \
--header 'Content-Type: application/json' \
--data '{
    "model_name": "kling-v3",
    "prompt": "Epic BBC nature documentary style, 4k ultra-high definition. On the savannah at dusk, dust flies as a brutal struggle for survival unfolds. A massive male lion, with a disheveled mane and muscles clearly defined in the sunset light, lets out a thunderous roar with his mouth wide open, swinging his claws to fend off an encirclement. Surrounding him are over a dozen cunning and ferocious spotted hyenas, baring their fangs with greedy eyes, employing an encircling tactic as they nimbly leap, probe, and bite around the lion. The frame is filled with wild tension, capturing flying saliva, swirling dust, and the realistic texture of animal fur, with dramatic lighting effects.",
    "mode": "pro",
    "sound": "on",
    "aspect_ratio": "16:9",
    "duration": "5"
}'

Return Value Example

{
    "code": 0, //Error Code; see error code for specific definition
    "message": "SUCCEED",
    "data": {
        "task_id": "788869215599472732",//Task ID, system-generated
        "task_status": "submitted",//Task Status, Enum Value:submitted、processing、succeed、failed
        "created_at": 1756109596262,//Task Creation Time, Unix Timestamp in milliseconds
        "updated_at": 1756109596262,//Task Update Time, Unix Timestamp in milliseconds
        "task_info": {
            "external_task_id": null //Customer-defined Task ID
        }
    },
    "request_id": "6eafac7a-cd8a-4155-9f95-8a2844cb917b" //Request ID, system-generated for tracking and troubleshooting
}

Query Task

Request URL

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

Request Method

GET

Query Example

curl --location 'https://genaiapi.cloudsway.net/v1/ai/${Your Endpoint}/kling/videos/text2video/788832073707958348' \
--header 'Authorization: Bearer ${Your AK}' \
--header 'Content-Type: application/json'

Return Value Example

{
    "code": 0,
    "message": "SUCCEED",
    "data": {
        "task_id": "788832073707958348",
        "task_status": "processing",
        "created_at": 1756100740946,
        "updated_at": 1756100742814,
        "task_status_msg": "",
        "task_info": {
            "external_task_id": null
        },
        "task_result": {
            "videos": null
        }
    },
    "request_id": "1e532f66-c222-471e-b2c0-88edcd106e9c"
}

Image-to-Video

Create Task

Request URL

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

Request Method

POST

Request Parameters

Field	Type	Required	Default Value	Description
model_name	string	Optional	kling-v1	Model Name ● value：kling-v1, kling-v1-5, kling-v1-6, kling-v2-master, kling-v2-1-master, kling-v2-5-turbo, kling-v2-6, kling-v3
image	string	Optional	Empty	Reference Image ● Supports passing in Base64-encoded images or image URLs (ensure they are accessible) ● Image formats supported:.jpg /.jpeg /.png ● Image file size cannot exceed 10MB ● Image width and height dimensions are not less than 300px ● The aspect ratio of the image should be between 1:2.5 and 2.5:1 ● Either the image parameter or the image_tail parameter must be selected, and they cannot both be empty at the same time ● Different model versions support different capabilities; for details, see the capabilities map above.
image_tail	string	Optional	Empty	Reference Image: Final Frame Image ● Supports passing in Base64-encoded images or image URLs (ensure they are accessible) ● Image formats supported:.jpg /.jpeg /.png ● Image file size cannot exceed 10MB ● Image width and height dimensions are not less than 300px ● The aspect ratio of the image should be between 1:2.5 and 2.5:1 ● Either the image parameter or the image_tail parameter must be selected, and they cannot both be empty at the same time ● Different model versions support different capabilities; for details, see the capabilities map above.
multi_shot	boolean	Optional	false	Whether to generate a multi-shot video ● When the current parameter is true, the prompt parameter is invalid ● When the current parameter is false, the shot_type parameter and the multi_prompt parameter are invalid
shot_type	string	Optional	Empty	Storyboard Method ● Enumerated values: customize, intelligence ● When the multi_shot parameter is true and the shot_type parameter is customize, the current parameter must be filled in
prompt	string	Optional	Empty	Text prompt, which can include positive and negative descriptions ● Prompt templates can be used to meet different video generation requirements ● Must not exceed 2500 characters. The Omni model can achieve various capabilities through Prompt with content such as subjects, images, and videos: 1. Specify a certain subject, image, or video in the format of <<<>>>, for example: <<<element_1>>>, <<<image_1>>>, <<<video_1>>> ● Use <<<voice_id>>> to specify the voice timbre, with the sequence number corresponding to the order of the voice timbres referenced by the voice_list parameter ● A single video generation task may reference at most 2 timbres. When specifying a timbre, the value of the sound parameter must be on. ● The simpler the grammatical structure, the better, e.g., \<<<voice_id>>> says: "Hello" ● When the voice_list parameter is not empty and the prompt parameter references a voice ID, the video generation task is billed based on "specified voice". ● When the multi_shot parameter is false or the shot_type parameter is intelligence, the current parameter must be filled in
multi_prompt	array	Optional	Empty	Each shot prompt may include positive and negative descriptions ● Define the shot number, corresponding prompt, and duration through the index, prompt, and duration parameters, where: ○ Supports up to 6 shots and at least 1 shot ○ The maximum length of each shot-related content does not exceed 512 ○ The duration of each shot is no greater than the total duration of the current task and no less than 1 ○ The sum of the durations of all storyboards equals the total duration of the current task ● Use key:value to carry, as follows: "multi_prompt":[ { "index":int, "prompt": "string", "duration": "5" }, { "index":int, "prompt": "string", "duration": "5" } ] ● When the multi_shot parameter is true and the shot_type parameter is customize, the current parameter must not be empty
negative_prompt	string	Optional	Empty	Negative text prompt ● It is recommended to incorporate negative prompts into positive prompts using negative descriptions. ● Must not exceed 2,500 characters
element_list	array	Optional	Empty	Reference Subject List ● Based on the ID configuration of the entities in the entity library, it is carried by key:value, as follows: "element_list":[ { "element_id":long }, { "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 the number of reference images must not exceed 10
sound	string	Optional	off	Whether to generate sound simultaneously when generating a video ● Enumerated values:on, off Only models of version V2.6 and above support the current parameters
mode	string	Optional	std	Mode of generating videos ● Enumerated values:std, pro ● Among them, std: Standard Mode (Standard), basic mode, generates 720P video, with high cost-effectiveness ● Among them, pro: Expert Mode (High Quality), High Performance Mode, generates 1080P videos with better video quality Different model versions support different ranges of capabilities, see the above Capability Map for details
aspect_ratio	string	Optional	16:9	Aspect ratio (width:height) of the generated video ● Enumerated values:16:9, 9:16, 1:1
duration	string	Optional	5	Generated video duration, unit: s ● Enumerated values: 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 Different model versions support different ranges of capabilities, see the above Capability Map for details
watermark_info	array	Optional	Empty	Whether to simultaneously generate watermarked results ● Defined by the enabled parameter, carried with key:value, as follows: "watermark_info": { "enabled": boolean // true for generation, false for no generation } ● Custom watermark is not currently supported
external_task_id	string	Optional	None	Custom Task ID ● User-defined task ID. Passing it in will not overwrite the system-generated task ID, but it supports task query via this ID. ● Please note that uniqueness must be ensured under single-user mode

Request Example

curl --location 'https://genaiapi.cloudsway.net/v1/ai/${Your Endpoint}/kling/videos/image2video' \
--header 'Authorization: Bearer ${Your AK}' \
--header 'Content-Type: application/json' \
--data '{
    "model_name": "kling-v2.6",
    "prompt": "Hollywood top-tier special effects blockbuster quality, 8k ultra-high resolution. In a rain-soaked city night illuminated by neon lights, Kong and Godzilla engage in a fierce battle to the death. Kong roars as he swings his heavy fists, the muscles in his arms bulging, while Godzilla opens his massive jaws, his dorsal fins glowing with dazzling blue atomic light, ready to unleash his breath. The moment they collide unleashes a massive shockwave, shattering the glass of surrounding buildings, sending countless debris and sparks flying. The rain on the monsters' skin turns to mist upon impact, creating an epic sense of overwhelming pressure and destructive power.",
    "image": "https://img2.baidu.com/it/u=2688005144,1651821809&fm=253&fmt=auto&app=120&f=JPEG?w=666&h=500",
    "mode": "pro",
    "sound": "on",
    "aspect_ratio": "16:9",
    "duration": "5",
    "external_task_id": "external_task_id"
}'

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 Task

Request URL

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

Request Method

GET

Query Example

curl --location 'https://genaiapi.cloudsway.net/v1/ai/${Your Endpoint}/kling/videos/image2video/788872612687921228' \
--header 'Authorization: Bearer ${Your AK}' \
--header 'Content-Type: application/json'

Return Value Example

{
    "code": 0,
    "message": "SUCCEED",
    "data": {
        "task_id": "788872612687921228",
        "task_status": "succeed",
        "created_at": 1756110406193,
        "updated_at": 1756110582022,
        "task_status_msg": "",
        "task_info": {
            "external_task_id": null
        },
        "task_result": {
            "videos": [
                {
                    "id": "788872612838903850",
                    "url": "https://v2-kling.kechuangai.com/bs2/upload-ylab-stunt/7612b751-0c5f-4d34-b6aa-7faf22642612-18KmyW5sziVWOTkCGlBFbw-outputvw158.mp4?x-kcdn-pid=112452",
                    "duration": "5.041",
                    "watermark_url": "string" // Watermarked Video Download URL, anti-leech link format
                }
            ]
        }
    },
    "request_id": "6e5e6654-17ec-4d29-90c5-35c6ccaeb6f0"
}

Image Generation

Create Task

Request URL

https://genaiapi.cloudsway.net/v1/ai/{endpoinPath}/kling/images/generations

Request Method

POST

Request Parameters

Field	Type	Required	Default Value	Description
model_name	string	Optional	kling-v1	Model Name ● Enumerated values: kling-v1, kling-v1-5, kling-v2, kling-v2-new, kling-v2-1, kling-v3
prompt	string	must	None	Text prompt, which can include positive and negative descriptions ● Must not exceed 2,500 characters
negative_prompt	string	Optional	Empty	Negative text prompt cannot exceed 2500 characters It is recommended to incorporate negative prompts into positive prompts using negative descriptions Note: Negative prompts are not supported in the image-to-image scenario (i.e., when the image field is not empty)
image	string	Optional	Empty	Reference Image Supports passing in Base64-encoded images or image URLs (ensure they are accessible) Please note that if you use the base64 method, ensure that all image data parameters you pass 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 directly the Base64-encoded string. Example: Correct Base64 encoding parameter: iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg== Invalid Base64 encoding parameter (containing the data: prefix): data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg== Please provide only the Base64-encoded string part so that the system can correctly process and parse your data. Image formats supported:.jpg /.jpeg /.png The size of the image file cannot exceed 10MB, the width and height of the image must be no less than 300px, and the aspect ratio of the image must be between 1:2.5 and 2.5:1. When the image_reference parameter is not empty, the current parameter is required
element_list	array	Optional	Empty	Subject Reference List Based on the ID configuration of the entities in the entity library, it is carried by key:value, as follows: "element_list":[ { "element_id":long }, { "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 the number of reference images shall not exceed 10
resolution	string	Optional	1k	Clarity of the generated image Enumerated values: 1k, 2k 1k: 1K Standard Definition 2K: 2K High Definition Different model versions support different ranges; for details, see the official documentation's capabilities map
n	int	Optional	1	Number of Generated Images Value range: [1,9]
aspect_ratio	string	Optional	16:9	The aspect ratio (width:height) of the generated image Enum values: 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9 Different model versions support different ranges; for details, see the official documentation's capabilities map
watermark_info	array	Optional	Empty	Whether to simultaneously generate watermarked results Defined by the enabled parameter, carried by key:value, as follows: "watermark_info": { "enabled": boolean // true 为生成，false 为不生成 } Custom watermarks are not currently supported
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 message schema of the specific notification
external_task_id	string	Optional	None	Custom Task ID User-defined task ID. Passing it in will not overwrite the system-generated task ID, but it supports task querying via this ID Please note that uniqueness must be ensured under single-user mode

Request Example

curl --location 'https://genaiapi.cloudsway.net/v1/ai/${Your Endpoint}/kling/images/generations' \
--header 'Authorization: Bearer ${Your AK}' \
--header 'Content-Type: application/json' \
--data '{
    "model_name": "kling-v3",
    "prompt": "Generate images with numbers 1-9",
    "element_list": [
        {
            "element_id": "160"
        },
        {
            "element_id": "161"
        },
        {
            "element_id": "159"
        }
    ],
    "image": "xxx",
    "resolution": "2k",
    "n": "9",
    "aspect_ratio": "3:2",
    "external_task_id": "",
    "callback_url": ""
}'

Return Value Example

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

Query Task (Single)

Request URL

https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/kling/images/generations/{taskId}

Request Method

GET

Query Example

curl --location 'https://genaiapi.cloudsway.net/v1/ai/${Your Endpoint}/kling/images/generations/858114895710539873' \
--header 'Authorization: Bearer ${Your AK}' \
--header 'Content-Type: application/json'

Return Value Example

{
    "code": 0,
    "message": "SUCCEED",
    "data": {
        "task_id": "788872612687921228",
        "task_status": "succeed",
        "created_at": 1756110406193,
        "updated_at": 1756110582022,
        "task_status_msg": "string", //Task Status Information; displays the reason for failure when the task fails (e.g., triggered platform content moderation, etc.)
        "final_unit_deduction": "string", // Final deduction amount of credits for the task
        "watermark_info": {
            "enabled": boolean // Should be a specific boolean value, e.g., true/false
        },
        "task_info": {
            "external_task_id": null
        },
        "task_result": {
            "images": [
                {
                    "index": 1, //Image Number, 0-9
                    "url": "string" //Generated image URL, e.g.:https://h1.inkwai.com/bs2/upload-ylab-stunt/1fa0ac67d8ce6cd55b50d68b967b3a59.png(Please note: To ensure information security, generated images/videos will be deleted after 30 days. Please save them promptly.)
                    "watermark_url": "string", // Watermarked Video Download URL, anti-leech link format
                }
            ]
        }
    },
    "request_id": "6e5e6654-17ec-4d29-90c5-35c6ccaeb6f0"
}