MaaS_KeLing_3.0接口文档

请求协议

http

Header

文生视频

创建任务

请求URL

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

请求方法

POST

请求参数

字段	类型	必填	默认值	描述
model_name	string	可选	kling-v1	模型名称● 枚举值：, MaaS_KeLing_V2.1_master, MaaS_KeLing_V2.5_turbo, MaaS_KeLing_V2.6, MaaS_KeLing_3.0_video
multi_shot	boolean	可选	false	是否生成多镜头视频 ● 当前参数为 true 时，prompt 参数无效 ● 当前参数为 false 时，shot_type 参数及 multi_prompt 参数无效
shot_type	string	可选	空	分镜方式 ● 枚举值：customize, intelligence ● 当 multi_shot 参数为 true 且 shot_type 参数为 customize 时，当前参数必须填写
prompt	string	可选	空	文本提示词，可包含正向描述和负向描述 ● 可将提示词模板化来满足不同的视频生成需求 ● 不能超过2500个字符Omni模型可通过Prompt与主体、图片、视频等内容实现多种能力： 1. 通过 <<<>>> 的格式来指定某个主体、图片、视频，如：<<<element_1>>>、<<<image_1>>>、<<<video_1>>> ● 当 multi_shot 参数为 false 或 shot_type 参数为 intelligence 时，当前参数必须填写
multi_prompt	array	可选	空	各分镜提示词，可包含正向描述和负向描述 ● 通过 index、prompt、duration 参数定义分镜序号及相应提示词和时长，其中：  ○ 最多支持6个分镜，最小支持1个分镜   ○ 每个分镜相关内容的最大长度不超过512   ○ 每个分镜的时长不大于当前任务的总时长，不小于1   ○ 所有分镜的时长之和等于当前任务的总时长 ● 用 key:value 承载，如下： "multi_prompt":[ { "index":int, "prompt": "string", "duration": "5" }, { "index":int, "prompt": "string", "duration": "5" } ] ● 当 multi_shot 参数为 true 且 shot_type 参数为 customize 时，当前参数不得为空
negative_prompt	string	可选	空	负向文本提示词 ● 建议将负向提示词用否定描述的方式写入正向提示词中 ● 不能超过2500个字符
sound	string	可选	off	生成视频时是否同时生成声音 ● 枚举值：on, off 仅V2.6及以上版本模型支持当前参数
mode	string	可选	std	生成视频的模式 ● 枚举值：std, pro ● 其中 std：标准模式（标准），基础模式，生成720P视频，性价比高 ● 其中 pro：专家模式（高品质），高表现模式，生成1080P视频，视频质量更佳 不同模型版本支持能力范围不同，详见上文能力地图
aspect_ratio	string	可选	16:9	生成视频的画面纵横比（宽:高） ● 枚举值：16:9, 9:16, 1:1
duration	string	可选	5	生成视频时长，单位s ● 枚举值：3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 不同模型版本支持能力范围不同，详见上文能力地图
watermark_info	array	可选	空	是否同时生成含水印的结果 ● 通过 enabled 参数定义，用 key:value 承载，如下： "watermark_info": { "enabled": boolean // true 为生成，false 为不生成 } ● 暂不支持自定义水印
external_task_id	string	可选	无	自定义任务ID● 用户自定义任务ID，传入不会覆盖系统生成的任务ID，但支持通过该ID进行任务查询● 请注意，单用户下需要保证唯一性

请求示例

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": "史诗般的BBC自然纪录片风格，4k超高清画质。非洲大草原的暮色中，尘土飞扬，一场残酷的生存之战正在上演。一头体型庞大的雄狮鬃毛凌乱，张开血盆大口发出震慑的咆哮，肌肉线条在夕阳下清晰可见，它正在挥舞利爪击退围攻。周围是十几只凶狠狡猾的斑鬣狗，它们龇牙咧嘴，目光贪婪，采取包围战术，灵活地在狮子周围跳跃、试探和撕咬。画面充满了野性的张力，捕捉到了飞溅的唾液、飘扬的尘埃以及动物皮毛的真实质感，光影极具戏剧性。",
    "mode": "pro",
    "sound": "on",
    "aspect_ratio": "16:9",
    "duration": "5"
}'

返回值示例

{
    "code": 0, //错误码；具体定义见错误码
    "message": "SUCCEED",
    "data": {
        "task_id": "788869215599472732",//任务ID，系统生成 
        "task_status": "submitted",//任务状态，枚举值:submitted(已提交)、processing(处理中)、succeed(成功)、failed(失败)
        "created_at": 1756109596262,//任务创建时间，Unix时间戳、单位ms
        "updated_at": 1756109596262,//任务更新时间，Unix时间戳、单位ms
        "task_info": {
            "external_task_id": null //客户自定义任务ID 
        }
    },
    "request_id": "6eafac7a-cd8a-4155-9f95-8a2844cb917b" //请求ID，系统生成，用于跟踪请求、排查问题
}

查询任务

请求URL

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

请求方法

GET

查询示例

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

返回值示例

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

图生视频

创建任务

请求URL

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

请求方法

POST

请求参数

字段	类型	必填	默认值	描述
model_name	string	可选	kling-v1	模型名称 ● 枚举值：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	可选	空	参考图片 ● 支持传入图片 Base64 编码或图片 URL（确保可访问） ● 图片格式支持 .jpg / .jpeg / .png ● 图片文件大小不能超过 10MB ● 图片宽高尺寸不小于 300px ● 图片宽高比要在 1:2.5 \~ 2.5:1 之间 ● image 参数与 image_tail 参数二选一，二者不能同时为空 ● 不同模型版本支持能力范围不同，详见上文能力地图
image_tail	string	可选	空	参考图片：尾帧图 ● 支持传入图片 Base64 编码或图片 URL（确保可访问） ● 图片格式支持 .jpg / .jpeg / .png ● 图片文件大小不能超过 10MB ● 图片宽高尺寸不小于 300px ● 图片宽高比要在 1:2.5 \~ 2.5:1 之间 ● image 参数与 image_tail 参数二选一，二者不能同时为空 ● 不同模型版本支持能力范围不同，详见上文能力地图
multi_shot	boolean	可选	false	是否生成多镜头视频 ● 当前参数为 true 时，prompt 参数无效 ● 当前参数为 false 时，shot_type 参数及 multi_prompt 参数无效
shot_type	string	可选	空	分镜方式 ● 枚举值：customize, intelligence ● 当 multi_shot 参数为 true 且 shot_type 参数为 customize 时，当前参数必须填写
prompt	string	可选	空	文本提示词，可包含正向描述和负向描述 ● 可将提示词模板化来满足不同的视频生成需求 ● 不能超过2500个字符Omni模型可通过Prompt与主体、图片、视频等内容实现多种能力： 1. 通过 <<<>>> 的格式来指定某个主体、图片、视频，如：<<<element_1>>>、<<<image_1>>>、<<<video_1>>> ● 用 <<<voice_id>>> 来指定音色，序号同 voice_list 参数所引用音色的排列顺序 ● 一次视频生成任务至多引用2个音色，指定音色时，sound 参数值必须为 on ● 语法结构越简单越好，如：男人 <<<voice_id>>> 说：“你好” ● 当 voice_list 参数不为空且 prompt 参数中引用音色ID时，视频生成任务按“有指定音色”计量计费 ● 当 multi_shot 参数为 false 或 shot_type 参数为 intelligence 时，当前参数必须填写
multi_prompt	array	可选	空	各分镜提示词，可包含正向描述和负向描述 ● 通过 index、prompt、duration 参数定义分镜序号及相应提示词和时长，其中：   ○ 最多支持6个分镜，最小支持1个分镜   ○ 每个分镜相关内容的最大长度不超过512   ○ 每个分镜的时长不大于当前任务的总时长，不小于1   ○ 所有分镜的时长之和等于当前任务的总时长 ● 用 key:value 承载，如下： "multi_prompt":[ { "index":int, "prompt": "string", "duration": "5" }, { "index":int, "prompt": "string", "duration": "5" } ] ● 当 multi_shot 参数为 true 且 shot_type 参数为 customize 时，当前参数不得为空
negative_prompt	string	可选	空	负向文本提示词 ● 建议将负向提示词用否定描述的方式写入正向提示词中 ● 不能超过2500个字符
element_list	array	可选	空	参考主体列表 ● 基于主体库中主体的 ID 配置，用 key:value 承载，如下： "element_list":[ { "element_id":long }, { "element_id":long } ] ● 参考主体数量与参考图片数量有关，参考主体数量和参考图片数量之和不得超过 10
sound	string	可选	off	生成视频时是否同时生成声音 ● 枚举值：on, off 仅V2.6及以上版本模型支持当前参数
mode	string	可选	std	生成视频的模式 ● 枚举值：std, pro ● 其中 std：标准模式（标准），基础模式，生成720P视频，性价比高 ● 其中 pro：专家模式（高品质），高表现模式，生成1080P视频，视频质量更佳 不同模型版本支持能力范围不同，详见上文能力地图
aspect_ratio	string	可选	16:9	生成视频的画面纵横比（宽:高） ● 枚举值：16:9, 9:16, 1:1
duration	string	可选	5	生成视频时长，单位s ● 枚举值：3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 不同模型版本支持能力范围不同，详见上文能力地图
watermark_info	array	可选	空	是否同时生成含水印的结果 ● 通过 enabled 参数定义，用 key:value 承载，如下： "watermark_info": { "enabled": boolean // true 为生成，false 为不生成 } ● 暂不支持自定义水印
external_task_id	string	可选	无	自定义任务ID ● 用户自定义任务ID，传入不会覆盖系统生成的任务ID，但支持通过该ID进行任务查询 ● 请注意，单用户下需要保证唯一性

请求示例

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": "好莱坞顶级特效大片质感，8k超高分辨率。在霓虹闪烁的暴雨城市夜景中，金刚与哥斯拉爆发激烈死斗。金刚咆哮着挥舞重拳，手臂肌肉线条暴起，哥斯拉张开巨口，背鳍亮起耀眼的原子蓝光准备喷射。双方碰撞瞬间激起巨大的冲击波，周围建筑物玻璃震碎，无数碎石与火花飞溅，雨水在怪兽皮肤上震荡化为水雾，画面充满毁天灭地的史诗级压迫感和破坏力。",
    "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"
}'

返回值示例

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

查询任务

请求URL

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

请求方法

GET

查询示例

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

返回值示例

{
    "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" // 含水印视频下载URL，防盗链格式
                }
            ]
        }
    },
    "request_id": "6e5e6654-17ec-4d29-90c5-35c6ccaeb6f0"
}

图像生成

创建任务

请求URL

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

请求方法

POST

请求参数

字段	类型	必填	默认值	描述
model_name	string	可选	kling-v1	模型名称 ● 枚举值：kling-v1, kling-v1-5, kling-v2, kling-v2-new, kling-v2-1, kling-v3
prompt	string	必须	无	文本提示词，可包含正向描述和负向描述 ● 不能超过2500个字符
negative_prompt	string	可选	空	负向文本提示词 不能超过2500个字符 建议将负向提示词用否定描述的方式写入正向提示词中 注：图生图（即image字段不为空时）场景下，不支持负向提示词
image	string	可选	空	参考图片 支持传入图片Base64编码或图片URL（确保可访问） 请注意，若您使用base64的方式，请确保您传递的所有图像数据参数均采用Base64编码格式。在提交数据时，请不要在Base64编码字符串前添加任何前缀，例如data:image/png;base64,。正确的参数格式应该直接是Base64编码后的字符串。 示例： 正确的Base64编码参数： iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg== 错误的Base64编码参数（包含data:前缀）： data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg== 请仅提供Base64编码的字符串部分，以便系统能够正确处理和解析您的数据。 图片格式支持.jpg / .jpeg / .png 图片文件大小不能超过10MB，图片宽高尺寸不小于300px，图片宽高比介于1:2.5 ~ 2.5:1之间 image_reference参数不为空时，当前参数必填
element_list	array	可选	空	主体参考列表 基于主体库中主体的ID配置，用key:value承载，如下： "element_list":[ { "element_id":long }, { "element_id":long } ] 参考主体数量与参考图片数量有关，参考主体数量和参考图片数量之和不得超过10
resolution	string	可选	1k	生成图片的清晰度 枚举值：1k, 2k 1k：1K标清 2k：2K高清 不同模型版本支持范围不同，详见官方文档能力地图
n	int	可选	1	生成图片数量 取值范围：[1,9]
aspect_ratio	string	可选	16:9	生成图片的画面纵横比（宽:高） 枚举值：16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9 不同模型版本支持范围不同，详见官方文档能力地图
watermark_info	array	可选	空	是否同时生成含水印的结果 通过enabled参数定义，用key:value承载，如下： "watermark_info": { "enabled": boolean // true 为生成，false 为不生成 } 暂不支持自定义水印
callback_url	string	可选	无	本次任务结果回调通知地址，如果配置，服务端会在任务状态发生变更时主动通知 具体通知的消息schema见“Callback协议”
external_task_id	string	可选	无	自定义任务ID 用户自定义任务ID，传入不会覆盖系统生成的任务ID，但支持通过该ID进行任务查询 请注意，单用户下需要保证唯一性

请求示例

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

返回值示例

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

查询任务（单个）

请求URL

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

请求方法

GET

查询示例

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

返回值示例

{
    "code": 0,
    "message": "SUCCEED",
    "data": {
        "task_id": "788872612687921228",
        "task_status": "succeed",
        "created_at": 1756110406193,
        "updated_at": 1756110582022,
        "task_status_msg": "string", //任务状态信息，当任务失败时展示失败原因（如触发平台的内容风控等）
        "final_unit_deduction": "string", // 任务最终扣减积分数值
        "watermark_info": {
            "enabled": boolean // 应该是一个具体的布尔值，如 true/false
        },
        "task_info": {
            "external_task_id": null
        },
        "task_result": {
            "images": [
                {
                    "index": 1, //图片编号，0-9
                    "url": "string" //生成图片的URL，例如：https://h1.inkwai.com/bs2/upload-ylab-stunt/1fa0ac67d8ce6cd55b50d68b967b3a59.png（请注意，为保障信息安全，生成的图片/视频会在30天后被清理，请及时转存）
                    "watermark_url": "string", // 含水印视频下载URL，防盗链格式
                }
            ]
        }
    },
    "request_id": "6e5e6654-17ec-4d29-90c5-35c6ccaeb6f0"
}