MaaS_KeLing_3.0接口文档

请求协议

http

参数名	类型	描述
anthorization	string	鉴权

文生视频

创建任务

请求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

查询示例

task_id

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

返回值示例

{
    "code": 0,
    "message": "SUCCEED",
    "data": {
        "task_id": "868515638699380789",
        "task_status": "succeed",
        "created_at": 1775098783289,
        "updated_at": 1775098949984,
        "task_status_msg": "",
        "task_info": {
            "parent_video": null
        },
        "task_result": {
            "videos": [
                {
                    "id": "868515638896496662",
                    "url": "{视频链接}",
                    "duration": "5.041",
                    "watermark_url": null
                }
            ]
        },
        "final_unit_deduction": "6"
    },
    "request_id": "29f424f9-628c-4914-b1ad-463b630db0e4"
}

图生视频

创建任务

请求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": "id12345",
        "task_status": "submitted",
        "created_at": 1775100512686,
        "updated_at": 1775100512686,
        "task_info": {
            "external_task_id": "id12345",
            "parent_video": null
        }
    },
    "request_id": "fa85a38e-3521-4173-8a27-06c70fdbd41f"
}

查询任务

请求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/id12345' \
--header 'Authorization: Bearer ${Your AK}' \
--header 'Content-Type: application/json'

返回值示例

{
    "code": 0,
    "message": "SUCCEED",
    "data": {
        "task_id": "id12345",
        "task_status": "succeed",
        "created_at": 1775100512686,
        "updated_at": 1775100668232,
        "task_status_msg": "",
        "task_info": {
            "external_task_id": "id12345",
            "parent_video": null
        },
        "task_result": {
            "videos": [
                {
                    "id": "868522892492279809",
                    "url": "{视频链接}",
                    "duration": "5.041",
                    "watermark_url": null
                }
            ]
        },
        "final_unit_deduction": "6"
    },
    "request_id": "7e3b2c27-d9b6-47dd-8b92-ba8a829909a1"
}

图像生成

创建任务

请求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": "868890892747673686",
        "task_status": "succeed",
        "created_at": 1775188250826,
        "updated_at": 1775188467595,
        "task_status_msg": "",
        "task_info": {
            "parent_video": null
        },
        "task_result": {
            "videos": [
                {
                    "id": "868890892911263836",
                    "url": "{图片链接}",
                    "duration": "5.041",
                    "watermark_url": null
                }
            ]
        },
        "final_unit_deduction": "6"
    },
    "request_id": "091dc51b-589d-4d5b-9c1a-430ab0ba4cce"
}

动作控制

创建任务

请求URL

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

请求方法

POST

请求参数

字段	类型	必填	默认值	描述
prompt	string	可选	空	文本提示词，可包含正向描述和负向描述可通过提示词为画面增加元素、实现运镜效果等;不能超过2500个字符
image_url	string	必须	无	参考图像，生成视频中的人物、背景等元素均已参考图为准视频内容需满足以下要求：人物比例尽量与参考动作比例一致，尽量避免全身动作驱动半身人物进行生成人物需要漏出清晰的上半身或全身的肢体及头部，避免遮挡画面中人物避免存在极端朝向，比如倒立、平卧等。人物占画面比例不得太低支持真实/风格化的角色（包括人物/类人动物/部分纯动物/部分类人肢体比例的角色）通过包含支持传入图片Base64编码或图片URL（确保可访问）请注意，若您使用base64的方式，请确保您传递的所有图像数据参数均采用Base64编码格式。在提交数据时，请不要在Base64编码字符串前添加任何前缀，例如data:image/png;base64,。正确的参数格式应该直接是Base64编码后的字符串。图片格式支持.jpg / .jpeg / .png 图片文件大小不能超过10MB，图片宽高尺寸介于300px～65536px，图片宽高比介于1:2.5 \~ 2.5:1之间
video_url	string	必须	无	参考视频的获取链接。生成视频中的人物动作与参考视频一致。视频内容需满足以下要求：人物需要漏出清晰的上半身或全身的全部肢体及头部，避免遮挡建议上传1人动作视频，2人及以上会取画面占比最大的人物动作进行生成推荐使用真人动作，部分风格化的人物/类人肢体比例可以通过动作视频一镜到底，角色始终出现在画面中，避免切镜、运镜等。否则会被截取。动作避免过快，相对平稳的动作生成效果更佳视频文件支持.mp4/.mov，文件大小不超过100MB，仅支持长宽的边长均位于340px\~3850px之间，上述校验不通过会返回错误码等信息视频时长下限不短于3秒，时长上限与人物朝向参考（character_orientation）有关：当人物朝向与视频中人物一致时，视频时长最长可达30秒；当人物朝向与图片中人物一致时，视频时长最长可达10秒；如果您的动作难度比较高、速度比较快，有一定概率生成不足上传视频时长的结果，因为模型只能提取有效动作时长进行生成，最短提取出3s可用连续动作即可生成。请注意，因此消耗的积分将无法退还，建议适当调整动作难度与速度系统会校验视频内容，如有问题会返回错误码等信息
element_list	array	可选	无	主体参考列表，基于主体库中主体的 ID 配置, kling-v2-6不支持。用 key:value 承载，如下： "element_list":[ { "element_id": 829836802793406551 } ] 引用主体时，生成的视频暂时只能参考视频中的人物朝向暂时仅支持引入1个主体 element_idlong必填(主体库中主体的 ID)
keep_original_sound	string	可选	yes	可选择是否保留视频原声枚举值：yes，no 其中yes：保留视频原声其中no：不保留视频原声
character_orientation	string	必须	无	生成视频中人物的朝向，可选择与图片一致或与视频一致枚举值：image，video，其中：其中image：与图片中人物朝向一致；此时参考视频时长不得超过10秒；其中video：与视频中人物朝向一致；此时参考视频时长不得超过30秒；
mode	string	必须	无	生成视频的模式枚举值：std，pro 其中std：标准模式（标准），基础模式，性价比高其中pro：专家模式（高品质），高表现模式，生成视频质量更佳
watermark_info	object	可选	无	是否同时生成含水印的结果通过enabled参数定义，具体格式如下： "watermark_info": { "enabled": boolean } true 为生成，false 为不生成暂不支持自定义水印
callback_url	string	可选	无	本次任务结果回调通知地址，如果配置，服务端会在任务状态发生变更时主动通知
external_task_id	string	可选	无	自定义任务ID 用户自定义任务ID，传入不会覆盖系统生成的任务ID，但支持通过该ID进行任务查询请注意，单用户下需要保证唯一性

请求示例

curl -g '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"
}'

返回示例

{
  "code": 0, // 错误码；
  "message": "string", // 错误信息
  "request_id": "string", // 请求ID，系统生成，用于跟踪请求、排查问题
  "data": {
    "task_id": "string", // 任务ID，系统生成
    "task_info": { //任务创建时的参数信息
      "external_task_id": "string" //客户自定义任务ID
    },
    "task_status": "string", // 任务状态，枚举值：submitted（已提交）、processing（处理中）、succeed（成功）、failed（失败）
    "created_at": 1722769557708, // 任务创建时间，Unix时间戳、单位ms
    "updated_at": 1722769557708 //任务更新时间，Unix时间戳、单位ms
  }
}

查询动作控制任务

请求方法

GET

请求URL

https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/kling/videos/motion-control/{taskId或external\_task\_id}

task_id

动作控制的任务ID。直接在请求路径中填写值，与external_task_id两种查询方式二选一

external_task_id

动作控制的自定义任务ID。直接在请求路径中填写值，与task_id两种查询方式二选一

请求示例

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

返回示例

{
  "code": 0, // 错误码；
  "message": "string", // 错误信息
  "request_id": "string", // 请求ID，系统生成，用于跟踪请求、排查问题
  "data": {
    "task_id": "string", // 任务ID，系统生成
    "task_status": "string", // 任务状态，枚举值：submitted（已提交）、processing（处理中）、succeed（成功）、failed（失败）
    "task_status_msg": "string", // 任务状态信息，当任务失败时展示失败原因（如触发平台的内容风控等）
    "task_info": { //任务创建时的参数信息
      "external_task_id": "string" //客户自定义任务ID
    },
    "task_result": {
      "videos": [
        {
          "id": "string", // 生成的视频ID；全局唯一
          "url": "string", // 生成视频的URL，防盗链格式（请注意，为保障信息安全，生成的图片/视频会在30天后被清理，请及时转存）
          "watermark_url": "string", // 含水印视频下载URL，防盗链格式
          "duration": "string" //视频总时长，单位s
        }
      ]
    },
    "watermark_info": {
      "enabled": boolean
           },
    "final_unit_deduction": "string", // 任务最终扣减积分数值
    "created_at": 1722769557708, // 任务创建时间，Unix时间戳、单位ms
    "updated_at": 1722769557708 //任务更新时间，Unix时间戳、单位ms
  }
}

视频生音效

创建任务

请求URL

https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/kling/audio/video-to-audio

请求方法

POST

请求参数

字段	类型	必填	默认值	描述
video_id	string	可选	空	通过MaaS_KeLing生成的视频的 ID 与 video_url 参数二选一填写，不能同时为空，也不能同时有值仅支持 30 天内生成并且长度在 3.0 秒-20.0 秒的视频
video_url	string	可选	无	所上传视频的获取链接与 video_id 参数二选一填写，不能同时为空，也不能同时有值视频格式仅支持 MP4/MOV，文件大小≤100M，视频长度在 3.0 秒-20.0 秒
sound_effect_prompt	string	可选	无	音效生成提示词不能超过 200 个字符
bgm_prompt	string	可选	无	配乐生成提示词 • 不能超过 200 个字符
asmr_mode	boolean	可选	false	是否开启 ASMR 模式；该模式会增强细节音效，适合高沉浸内容场景 • true 表示开启，false 表示关闭（默认值）
external_task_id	string	可选	无	自定义任务 ID 用户自定义任务 ID，传入不会覆盖系统生成的任务 ID，但支持通过该 ID 进行任务查询请注意，单用户下需要保证唯一性
callback_url	string	可选	无	本次任务结果回调通知地址，如果配置，服务端会在任务状态发生变更时主动通知

请求示例

curl -g 'https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/kling/audio/video-to-audio' \
-H 'Authorization: Bearer {Your AK}' \
-H 'Content-Type: application/json' \
-d '{
    "video_id": "",
    "video_url": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/20fps-7s.mov"
}'

返回示例

{
  "code": 0, // 错误码；
  "message": "string", // 错误信息
  "request_id": "string", // 请求ID，系统生成，用于跟踪请求、排查问题
  "data": {
    "task_id": "string", // 任务ID，系统生成
    "task_info": { // 任务创建时的参数信息
      "external_task_id": "string" // 客户自定义任务ID
    },
    "task_status": "string", // 任务状态，枚举值：submitted（已提交）、processing（处理中）、succeed（成功）、failed（失败）
    "created_at": 1722769557708, // 任务创建时间，Unix时间戳、单位ms
    "updated_at": 1722769557708 // 任务更新时间，Unix时间戳、单位ms
  }
}

查询视频生音效任务

请求方法

GET

请求URL

https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/kling/audio/video-to-audio/{taskId或external\_task\_id}

task_id

视频生音频的任务ID。直接在请求路径中填写值，与external_task_id两种查询方式二选一

external_task_id

视频生音频的自定义任务ID。创建任务时填写的 external_task_id，与 task_id 两种查询方式二选一

请求示例

curl -g 'https://genaiapi.cloudsway.net/v1/ai/{{endpointPath}}/kling/audio/video-to-audio/{{taskId}}' \
-H 'Authorization: Bearer {Your AK}' \
-H 'Content-Type: application/json'

返回示例

{
  "code": 0, // 错误码；具体定义见错误码
  "message": "string", // 错误信息
  "request_id": "string", // 请求ID，系统生成，用于跟踪请求、排查问题
  "data": {
    "task_id": "string", // 任务ID，系统生成
    "task_status": "string", // 任务状态，枚举值：submitted（已提交）、processing（处理中）、succeed（成功）、failed（失败）
    "task_status_msg": "string", // 任务状态信息，当任务失败时展示失败原因（如触发平台的内容风控等）
    "task_info": { // 任务创建时的参数信息
      "external_task_id": "string", // 客户自定义任务ID
      "parent_video": { // 原始视频信息
        "id": "string", // 原始视频ID
        "url": "string", // 原始视频URL
        "duration": "string" // 原始视频时长，单位s（秒）
      }
    },
    "task_result": {
      "videos": [
        {
          "id": "string", // 生成的视频ID；全局唯一
          "url": "string", // 生成视频的URL（请注意，为保障信息安全，生成的图片/视频会在30天后被清理，请及时转存）
          "duration": "string" // 视频总时长，单位s（秒）
        }
      ],
      "audios": [
        {
          "id": "string", // 生成的音频ID；全局唯一，将在30天后被清理
          "url_mp3": "string", // 生成音频的MP3格式URL（请注意，为保障信息安全，生成的音频会在30天后被清理，请及时转存）
          "url_wav": "string", // 生成音频的WAV格式URL（请注意，为保障信息安全，生成的音频会在30天后被清理，请及时转存）
          "duration_mp3": "string", // MP3格式音频总时长，单位s（秒）
          "duration_wav": "string" // WAV格式音频总时长，单位s（秒）
        }
      ]
    },
    "final_unit_deduction": "string", // 任务最终扣减积分数值
    "created_at": 1722769557708, // 任务创建时间，Unix时间戳、单位ms
    "updated_at": 1722769557708 // 任务更新时间，Unix时间戳、单位ms
  }
}

文生音效

创建文生音效任务

请求URL

POST v1/ai/{endpointPath}/kling/audio/text-to-audio

请求参数

请求示例

curl -g 'https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/kling/audio/text-to-audio' \
-H 'Authorization: Bearer {Your AK}' \
-H 'Content-Type: application/json' \
-d '{
    "prompt": "春节庆祝时的烟花声",
    "duration": 3,
    "external_task_id": "",
    "callback_url": ""
  }'

返回示例

{
    "code": 0,
    "message": "SUCCEED",
    "data": {
        "task_id": "871457979416604766",
        "task_status": "submitted",
        "created_at": 1775800291981,
        "updated_at": 1775800291981,
        "task_info": {}
    },
    "request_id": "828f9782-d2e1-4550-a36d-e715ae2ae037"
}

查询文生音效任务

请求URL

GET v1/ai/{endpointPath}/kling/audio/text-to-audio/{id}

task_id

文生音频的任务 ID:请求路径参数，直接将值填写在请求路径中,与 external_task_id 两种查询方式二选一

external_task_id

用户自定义任务ID。创建任务时填写的 external_task_id，与 task_id 两种查询方式二选一

请求示例

curl -g 'https://genaiapi.cloudsway.net/v1/ai/{endpointPath}/kling/audio/text-to-audio/{id}' \
-H 'Authorization: Bearer {Your AK}' \
-H 'Content-Type: application/json'

返回示例

{
    "code": 0,
    "message": "SUCCEED",
    "data": {
        "task_id": "871457647223545935",
        "task_status": "succeed",
        "created_at": 1775800212780,
        "updated_at": 1775800228263,
        "task_status_msg": "",
        "task_info": {},
        "task_result": {
            "audios": [
                {
                    "id": "871457647265472604",
                    "url": null,
                    "duration": null,
                    "url_mp3": "https://v1-fdl.kechuangai.com/ksc2/ErHLIqeozb1WHdz1Izp1XGMBtJebQoG3Cp-2dvW1aWViY8RLKpP-tk5x7W6eeTn2b9GYO9YFP-o6znENuMnJ_gfCTlDfVz_FxCmXqGQ_q9-dhYwdNq2aZ8d7OHlPbYDwz0EsdeQnxcY_WktB6fbeiN5oHMdZZX8Uptz-fQGeBJWReQzcvLau7vxSQFcBf1rU1kGJZD3nRhuRJ-QT0NE0SA.mp3?cacheKey=ChtzZWN1cml0eS5rbGluZy5tZXRhX2VuY3J5cHQSsAFXEmxe-C5r1GsrJ4R_tFpMHnPrbjCJDG0KIp-dlRASzaKKVZPnTgDc4lOQw0tb7j0a6SuaZpiXsbq5v7GDhAdOjAaaMEFTIEhrKwILiBTZGoMM-l7cRD7Ak1Ijpt7KdddfiPC78jYKpRJEQVhp4DUtiyq8gzSrs6IOPskVBlbkMrhYZjRCYaJlswSacwFokyXfVoigHmoCox4tWOKtHuxwm5f_cNbqIxHkA6_Z19xqBhoSj4dfrTYhUzYe6jlYP2ZR__D3IiDmgbsrWNwPG28XCgRF7KfT3EKY6rUhktnmmeKY_OffqCgFMAE&x-kcdn-pid=112757&pkey=AAXEF3UtKZpRO5SOnZyIm1g87c3z1b0907OuSWpmsuDt4YCj95yjTniBUsV4LWeF5xlebOHfqK04MbbxPGXsyKVxpOqoVRq45ysb_TG_D6tKUSyb4zwibeQsYkSxRnmsFQw",
                    "url_wav": "https://v1-fdl.kechuangai.com/ksc2/ax60xYdmxPhWhrgqKcjG_R9nmqBtwZMYjs5jpC56Q5hVdN5Oae3O7d7kzmoEMhSJ-9Xv7-jrsi3v2DL0aHod0XOhTY8qoSofHRwh02DrXweWPL3JnQlUb13iVF2821muQ1O_-1-cbKUP1pg-QpQUOHvhd_FydZUe36F6bnvEW3E9AvbB95J6K0py-whjEerp2Z59LoNZAo2cHPtKS0ncHQ.wav?cacheKey=ChtzZWN1cml0eS5rbGluZy5tZXRhX2VuY3J5cHQSsAHMhoi-CYC9uUILiob74ZeXGkx3LSdWf7QCCBzpAdPiIjTaWxyhiErxhtb1mMQxCeT-YmlFsuqdVOJ73bXn5w7A6kLgO27kbl4uM5IjmZV5_dwTGhllwW_B2UXMdfwFxKIfRPu93U3-2M-Y3chNNOd0GhtUteZ9KIQn9Xc9bSpncu6HeNoMhIVm76XCDYyldt54EFfx8yLB51QV6LFCnnOtiAzbD-srIaG7HPJtH5j5tRoSqwnSbF-azU9cbKSOb8doGVG2IiAf7HRWbkMraGIU3pE62uCrWJoBkKaBwUWwUTOYw9nlhCgFMAE&x-kcdn-pid=112757&pkey=AAVm6lQUh6-ZOYrSRgFdt0zru0pJpiVxoeU820BANf98nNF4I4T8nG-q9lNdkw01UgQWYSR7L3cr6v6MVHiyN3UfBhNJJ9SFSS9f4E4z1eAlaLm8L8p3Ew6-nhILspq7oQU",
                    "duration_mp3": "3.056",
                    "duration_wav": "3.0"
                }
            ]
        },
        "final_unit_deduction": "0.25"
    },
    "request_id": "5571ddf9-0c33-44cd-8087-300bb47688ab"
}

数字人

创建任务

请求URL

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

请求方法

POST

请求参数

字段	类型	必填	默认值	描述
image	string	必须	无	数字人参考图支持传入图片Base64编码或图片URL（确保可访问）请注意，若您使用base64的方式，请确保您传递的所有图像数据参数均采用Base64编码格式。在提交数据时，请不要在Base64编码字符串前添加任何前缀，例如data:image/png;base64,。正确的参数格式应该直接是Base64编码后的字符串。示例：正确的Base64编码参数： `1 iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==` 错误的Base64编码参数（包含data:前缀）： `1 data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==` 请仅提供Base64编码的字符串部分，以便系统能够正确处理和解析您的数据。图片格式支持.jpg / .jpeg / .png 图片文件大小不能超过10MB，图片宽高尺寸不小于300px，图片宽高比介于1:2.5 ~ 2.5:1之间
audio_id	string	可选	空	通过试听接口生成的音频的ID 仅支持使用30天内生成的、时长不短于2秒且不超过300秒的音频 audio_id、sound_file参数二选一，不能同时为空，也不能同时有值
sound_file	string	可选	空	音频文件支持传入音频Base64编码或图音频URL（确保可访问）音频文件支持.mp3/.wav/.m4a/.aac(标准audio/acc格式)，文件大小不超过5MB，格式不匹配或文件过大会返回错误码等信息仅支持使用时长不短于2秒且不长于300秒的音频 audio_id、sound_file参数二选一，不能同时为空，也不能同时有值系统会校验音频内容，如有问题会返回错误码等信息
prompt	string	可选	空	正向文本提示词可定义数字人动作、情绪及运镜等不能超过2500个字符
mode	string	可选	std	生成视频的模式枚举值：std，pro 其中std：标准模式（标准），基础模式，性价比高其中pro：专家模式（高品质），高表现模式，生成视频质量更佳
callback_url	string	可选	无	本次任务结果回调通知地址，如果配置，服务端会在任务状态发生变更时主动通知具体通知的消息schema见“Callback协议”
external_task_id	string	可选	空	自定义任务ID 用户自定义任务ID，传入不会覆盖系统生成的任务ID，但支持通过该ID进行任务查询请注意，单用户下需要保证唯一性

请求示例

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": "一个古风女孩在唱古风歌曲",
    "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"
}'

返回值示例

{
  "code": 0, //错误码；具体定义见错误码
  "message": "string", //错误信息
  "request_id": "string", //请求ID，系统生成，用于跟踪请求、排查问题
  "data":{
    "task_id": "string", //任务ID，系统生成
    "task_info":{ //任务创建时的参数信息
       "external_task_id": "string" //客户自定义任务ID
    }, 
    "task_status": "string", //任务状态，枚举值：submitted（已提交）、processing（处理中）、succeed（成功）、failed（失败）
    "created_at": 1722769557708, //任务创建时间，Unix时间戳、单位ms
    "updated_at": 1722769557708 //任务更新时间，Unix时间戳、单位ms
  }
}

查询任务

请求URL

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

请求方法

GET

请求参数

字段	类型	必填	默认值	描述
task_id	string	可选	无	数字人的任务ID 请求路径参数，直接将值填写在请求路径中

返回值示例

{
  "code": 0, //错误码；具体定义见错误码
  "message": "string", //错误信息
  "request_id": "string", //请求ID，系统生成，用于跟踪请求、排查问题
  "data":{
          "task_id": "string", //任务ID，系统生成
    "task_status": "string", //任务状态，枚举值：submitted（已提交）、processing（处理中）、succeed（成功）、failed（失败）
    "task_status_msg": "string", //任务状态信息，当任务失败时展示失败原因（如触发平台的内容风控等）
    "task_info": { //任务创建时的参数信息
      "external_task_id": "string"//客户自定义任务ID
    },
    "task_result":{
      "videos":[
        {
                "id": "string", //生成的视频ID；全局唯一
                      "url": "string", //生成视频的URL，例如https://p1.a.kwimgs.com/bs2/upload-ylab-stunt/special-effect/output/HB1_PROD_ai_web_46554461/-2878350957757294165/output.mp4（请注意，为保障信息安全，生成的图片/视频会在30天后被清理，请及时转存）
                      "duration": "string" //视频总时长，单位s
        }
      ]
    },
    "created_at": 1722769557708, //任务创建时间，Unix时间戳、单位ms
    "updated_at": 1722769557708 //任务更新时间，Unix时间戳、单位ms
  }
}

MaaS_KeLing_3.0接口文档

请求协议

请求Header

文生视频

创建任务

请求URL

请求方法

请求参数

请求示例

返回值示例

查询任务

请求URL

请求方法

查询示例

返回值示例

图生视频

创建任务

请求URL

请求方法

请求参数

请求示例

返回值示例

查询任务

请求URL

请求方法

查询示例

返回值示例

图像生成

创建任务

请求URL

请求方法

请求参数

请求示例

返回值示例

查询任务（单个）

请求URL

请求方法

查询示例

返回值示例

动作控制

创建任务

请求URL

请求方法

请求参数

请求示例

返回示例

查询动作控制任务

请求方法

请求URL

请求示例

返回示例

视频生音效

创建任务

请求URL

请求方法

请求参数

请求示例

返回示例

查询视频生音效任务

请求方法

请求URL

请求示例

返回示例

文生音效

创建文生音效任务

请求URL

请求参数

请求示例

返回示例

查询文生音效任务

请求URL

请求示例

返回示例

数字人

创建任务

请求URL

请求方法

请求参数

请求示例

返回值示例