MaaS_KL接口文档

请求协议

http

参数名	类型	描述
Authorization	string	鉴权

文生视频

创建任务

请求URL

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

请求方法

POST

请求参数

字段	类型	必填	默认值	描述
model_name	string	可选	kling-v1	模型名称，枚举值: MaaS_KL_V1.6，MaaS_KL_V2.1_Master，MaaS_KeLing_V2.6
prompt	string	必须	无	正向文本提示词，不能超过2500个字
sound	string	可选	off	生成视频时是否同时生成声音枚举值：on，off，仅MaaS_KeLing_V2.6 及后续版本模型支持当前参数。
negative_prompt	string	可选	空	负向文本提示词，不能超过2500个字符
cfg_scale	float	可选	0.5	生成视频的自由度；值越大，模型自由度越小，与用户输入的提示词相关性越强，取值范围: [0, 1] MaaS_KL_V2.1_Master，MaaS_KeLing_V2.6不支持该参数
mode	string	可选	std	生成视频的模式 - 枚举值: std, pro 。其中std:标准模式(标准)，基础模式，性价比高；pro:专家模式(高品质)，高表现模式，生成视频质量更佳。MaaS_KL_V2.1_Master不支持该参数，MaaS_KeLing_V2.6目前仅支持pro（高品质）
camera_control	object	可选	空	控制摄像机运动的协议(如未指定，模型将根据输入的文本/图片进行智能匹配)。不同模型版本、视频模式支持范围不同
camera_control - type	string	可选	无	预定义的运镜类型 - 枚举值: “simple”, “down_back”, “forward_up”, “right_turn_forward”, “left_turn_forward”。simple:简单运镜，此类型下可在 "config" 中六选一进行运镜；down_back:镜头下压并后退 ➡ 下移拉远，此类型下config参数无需填写；forward_up:镜头前进并上仰 ➡ 推进上移，此类型下config参数无需填写；right_turn_forward:先右旋转后前进 ➡ 右旋推进，此类型下config参数无需填写；left_turn_forward:先左旋并前进 ➡ 左旋推进，此类型下config参数无需填写
camera_control - config	object	可选	无	包含六个字段，用于指定摄像机在不同方向上的运动或变化。当运镜类型指定simple时必填，指定其他类型时不填。以下参数6选1，即只能有一个参数不为0，其余参数为0
camera_control - horizontal	float	可选	无	水平运镜，控制摄像机在水平方向上的移动量(沿x轴平移)，取值范围: [-10, 10] ，负值表示向左平移，正值表示向右平移
camera_control - vertical	float	可选	无	垂直运镜，控制摄像机在垂直方向上的移动量(沿y轴平移)，取值范围: [-10, 10] ，负值表示向下平移，正值表示向上平移
camera_control - pan	float	可选	无	水平摇镜，控制摄像机在水平面上的旋转量(绕y轴旋转)，取值范围: [-10, 10] ，负值表示绕y轴向左旋转，正值表示绕y轴向右旋转
camera_control - tilt	float	可选	无	垂直摇镜，控制摄像机在垂直面上的旋转量(沿x轴旋转)，取值范围: [-10, 10] ，负值表示绕x轴向下旋转，正值表示绕x轴向上旋转
camera_control - roll	float	可选	无	旋转运镜，控制摄像机的滚动量(绕z轴旋转)，取值范围: [-10, 10] ，负值表示绕z轴逆时针旋转，正值表示绕z轴顺时针旋转
camera_control - zoom	float	可选	无	变焦，控制摄像机的焦距变化，影响视野的远近，取值范围: [-10, 10] ，负值表示焦距变长､视野范围变小，正值表示焦距变短､视野范围变大
camera_control - aspect_ratio	string	可选	16:9	生成视频的画面纵横比(宽 : 高)，枚举值: 16:9, 9:16, 1:1
duration	string	可选	5	生成视频时长，单位s，枚举值: 5, 10
external_task_id	string	可选	无	自定义任务ID - 用户自定义任务ID，传入不会覆盖系统生成的任务ID，但支持通过该ID进行任务查询。请注意，单用户下需要保证唯一性

请求示例

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":"小狗在草地上奔跑"
}'

返回值示例

{
"request_id": "string", //请求ID，系统生成，用于跟踪请求、排查问题
"code": 0, //错误码；具体定义见错误码
"message": "string", //错误信息 
"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/text2video/{id}

请求方法

GET

查询参数

字段	类型	必填	默认值	描述
task_id	string	可选	无	文生视频的任务ID，请求路径参数，直接将值填写在请求路径中，与external_task_id两种查询方式二选一
external_task_id	string	可选	无	文生视频的自定义任务ID，创建任务时填写的external_task_id，与task_id两种查询方式二选一

返回值示例

{
"code": 0, //错误码；具体定义见错误码 
"message": "string", //错误信息 
"request_id": "string", //请求ID，系统生成，用于跟踪请求、排查问题
"data":{ 
"task_status": "string", //任务状态，枚举值:submitted(已提交)、processing(处理中)、succeed(成功)、failed(失败)
"task_status_msg": "string", //任务状态信息，当任务失败时展示失败原因(如触发平台的内容风控等)
"task_info": { //任务创建时的参数信息 
"task_id": "string", //任务ID，系统生成 
"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/
"duration": "string" //视频总时长，单位s 
}
],
"created_at": 1722769557708, //任务创建时间，Unix时间戳、单位ms
"updated_at": 1722769557708 //任务更新时间，Unix时间戳、单位ms
}
}

图生视频

创建任务

请求URL

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

请求方法

POST

请求参数

字段	类型	必填	默认值	描述
model_name	string	可选	kling-v1	模型名称，枚举值: MaaS_KL_V1.6, MaaS_KL_V2.1，MaaS_KL_V2.1_Master，MaaS_KeLing_V2.6
image	string	必须	空	参考图像 - 支持传入图片Base64编码或图片URL(确保可访问)。请注意，若使用base64的方式，请确保传递的所有图像数据参数均为正确的Base64编码，即仅提供Base64编码的字符串部分，不要包含data:前缀。图片格式支持.jpg / .jpeg / .png，图片文件大小不能超过10MB，图片分辨率不小于300*300px。image参数与image_tail参数至少二选一，二者不能同时为空。image + image_tail参数、dynamic_masks/static_mask参数、camera_control不同模型版本、视频模式支持范围不同
image_tail	string	可选	空	参考图像 - 尾帧控制。支持传入图片Base64编码或图片URL(确保可访问)，参数格式要求同image。图片格式支持.jpg / .jpeg / .png，图片文件大小不能超过10MB，图片分辨率不小于300*300px。image参数与image_tail参数至少二选一，二者不能同时为空。image+image_tail参数、dynamic_masks/static_mask参数、camera_control不同模型版本、视频模式支持范围不同
sound	string	可选	off	生成视频时是否同时生成声音枚举值：on，off，仅MaaS_KeLing_V2.6 及后续版本模型支持当前参数。
prompt	string	可选	无	正向文本提示词，不能超过2500个字符
negative_prompt	string	可选	空	负向文本提示词，不能超过2500个字符
cfg_scale	float	可选	0.5	生成视频的自由度；值越大，模型自由度越小，与用户输入的提示词相关性越强，取值范围: [0, 1]
mode	string	可选	std	生成视频的模式 - 枚举值:std, pro。其中std:标准模式(标准)，基础模式，性价比高；pro:专家模式(高品质)，高表现模式，生成视频质量更佳。MaaS_KL_V2.1_Master不支持该参数，MaaS_KeLing_V2.6 目前仅支持pro。
static_mask	string	可选	无	静态笔刷涂抹区域(用户通过运动笔刷涂抹的mask图片)。“运动笔刷”能力包含“动态笔刷dynamic_masks”和“静态笔刷static_mas”。支持传入图片Base64编码或图片URL(确保可访问，格式要求同image)。图片格式支持.jpg / .jpeg / .png，图片长宽比必须与输入图片相同(即image字段)，否则任务失败。static_mask和dynamic_masks.mask这两张图片的分辨率必须一致。不同模型版本、视频模式支持范围不同
dynamic_masks	array	可选	无	动态笔刷配置列表，可配置多组(最多6组)，每组包含“涂抹区域mask”与“运动轨迹trajectories”
dynamic_masks - mask	string	可选	无	动态笔刷涂抹区域(用户通过运动笔刷涂抹的mask图片)。支持传入图片Base64编码或图片URL(确保可访问，格式要求同image)。图片格式支持.jpg / .jpeg / .png，图片长宽比必须与输入图片相同(即image字段)，否则任务失败。static_mask和dynamic_masks.mask这两张图片的分辨率必须一致
dynamic_masks - trajectories	array	可选	无	运动轨迹坐标序列。生成5s的视频，轨迹长度不超过77，即坐标个数取值范围: [2, 77] 。轨迹坐标系，以图片左下角为坐标原点。注1:坐标点个数越多轨迹刻画越准确，如只有2个轨迹点则为这两点连线。注2:轨迹方向以传入顺序为指向，以最先传入的坐标为轨迹起点，依次连接
dynamic_masks - trajectories - x	int	可选	无	轨迹点横坐标(在像素二维坐标系下，以输入图片image左下为原点的像素坐标)
dynamic_masks - trajectories - y	int	可选	无	轨迹点纵坐标(在像素二维坐标系下，以输入图片image左下为原点的像素坐标)
camera_control	object	可选	空	控制摄像机运动的协议(如未指定，模型将根据输入的文本/图片进行智能匹配)。不同模型版本、视频模式支持范围不同
camera_control - type	string	可选	无	预定义的运镜类型 - 枚举值: “simple”, “down_back”, “forward_up”, “right_turn_forward”, “left_turn_forward”。simple:简单运镜，此类型下可在 "config" 中六选一进行运镜；down_back:镜头下压并后退 ➡ 下移拉远，此类型下config参数无需填写；forward_up:镜头前进并上仰 ➡ 推进上移，此类型下config参数无需填写；right_turn_forward:先右旋转后前进 ➡ 右旋推进，此类型下config参数无需填写；left_turn_forward:先左旋并前进 ➡ 左旋推进，此类型下config参数无需填写
camera_control - config	object	可选	无	包含六个字段，用于指定摄像机在不同方向上的运动或变化。当运镜类型指定simple时必填，指定其他类型时不填。以下参数6选1，即只能有一个参数不为0，其余参数为0
camera_control - horizontal	float	可选	无	水平运镜，控制摄像机在水平方向上的移动量(沿x轴平移)，取值范围: [-10, 10] ，负值表示向左平移，正值表示向右平移
camera_control - vertical	float	可选	无	垂直运镜，控制摄像机在垂直方向上的移动量(沿y轴平移)，取值范围: [-10, 10] ，负值表示向下平移，正值表示向上平移
camera_control - pan	float	可选	无	水平摇镜，控制摄像机在水平面上的旋转量(绕y轴旋转)，取值范围: [-10, 10] ，负值表示绕y轴向左旋转，正值表示绕y轴向右旋转
camera_control - tilt	float	可选	无	垂直摇镜，控制摄像机在垂直面上的旋转量(沿x轴旋转)，取值范围: [-10, 10] ，负值表示绕x轴向下旋转，正值表示绕x轴向上旋转
camera_control - roll	float	可选	无	旋转运镜，控制摄像机的滚动量(绕z轴旋转)，取值范围: [-10, 10] ，负值表示绕z轴逆时针旋转，正值表示绕z轴顺时针旋转
camera_control - zoom	float	可选	无	变焦，控制摄像机的焦距变化，影响视野的远近，取值范围: [-10, 10] ，负值表示焦距变长､视野范围变小，正值表示焦距变短､视野范围变大
duration	string	可选	5	生成视频时长，单位s，枚举值: 5, 10
external_task_id	string	可选	无	自定义任务ID - 用户自定义任务ID，传入不会覆盖系统生成的任务ID，但支持通过该ID进行任务查询。请注意，单用户下需要保证唯一性

请求示例

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":"哪吒在练武"
}'

返回值示例

{
"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/image2video/{id}

请求方法

GET

查询参数

字段	类型	必填	默认值	描述
task_id	string	可选	无	图生视频的任务ID 请求路径参数，直接将值填写在请求路径中，与external_task_id两种查询方式二选一
external_task_id	string	可选	无	图生视频的自定义任务ID 创建任务时填写的external_task_id，与task_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/
"duration": "string" //视频总时长，单位s
}
]
}
"created_at": 1722769557708, //任务创建时间，Unix时间戳、单位ms
"updated_at": 1722769557708, //任务更新时间，Unix时间戳、单位ms
}
}

视频延长

创建任务

请求URL

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

请求方法

POST

请求参数

视频ID

支持文生视频接口生成的视频ID（2.1版本暂不支持）
支持图生视频接口生成的视频ID（2.1版本暂不支持）
支持视频延长接口生成的视频ID（注意不能超过3分钟）

字段	类型	必填	默认值	描述
video_id	string	必须	无	视频ID - 支持文生视频接口生成的视频ID（2.1版本暂不支持） - 支持图生视频接口生成的视频ID（2.1版本暂不支持） - 支持视频延长接口生成的视频ID（注意不能超过3分钟）请注意，基于目前的清理策略、视频生成30天之后会被清理，则无法进行延长
prompt	string	可选	无	正向文本提示不能超过2500个字符词

请求示例

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": "哪吒从背后掏出一把红印枪，脚踩风火轮"
}'

返回值示例

{
"code": 0, //错误码；具体定义见错误码
"message": "string", //错误信息
"request_id": "string", //请求ID，系统生成，用于跟踪请求、排查问题
"data": {
"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/video-extend/{task_id}

请求方法

GET

查询参数

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

返回值示例

{
"code": 0, //错误码；具体定义见1.1错误码
"message": "string", //错误信息；具体定义见1.1错误码
"request_id": "string", //请求ID，系统生成，用于跟踪请求、排查问题；全局唯一
"data":{
"task_id": "string", //任务ID，系统生成；全局唯一
"task_status": "string", //任务状态，枚举值：submitted（已提交）、processing（处理中）、succeed（成功）、failed（失败
"task_status_msg": "string", //任务状态信息，当任务失败时展示失败原因（如触发平台的内容风控等）
"task_info":{ //任务创建时的参数信息
"parent_video": {
"id": "string", //续写前的视频ID；全局唯一
"url": "string", //续写前视频的URL（请注意，为保障信息安全，生成的图片/视频会在30天后被清理，请及时转存）
"duration": "string" //续写前的视频总时长，单位s
}
}, //任务创建时用户填写的详细信息
"task_result":{
"videos":[ //数组是为了保留扩展性，以防未来要支持n
{
"id": "string", //续写后的完整视频ID；全局唯一
"url": "string", //续写后视频的URL
"duration": "string" //视频总时长，单位s
}
]
}
"created_at": 1722769557708, //任务创建时间，Unix时间戳、单位ms
"updated_at": 1722769557708, //任务更新时间，Unix时间戳、单位ms
}
}

多图参考生视频

支持模型：MaaS_KeLing_V1.6

创建任务

请求URL

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

请求方法

POST

请求参数

字段	类型	必填	默认值	描述
model_name	string	可选	MaaS_KeLing_V1.6	模型名称枚举值：MaaS_KeLing_V1.6
image_list	array	必须	空	最多支持4张图片，用key:value承载。 API端无裁剪逻辑，请直接上传。已选主体后的图片支持传入图片Base64编码或图片URL（确保可访问）请注意，若您使用base64的方式，请确保您传递的所有图像数据参数均采用Base64编码格式。在提交数据时，请不要在Base64编码字符串前添加任何前缀，正确的参数格式应该直接是Base64编码后的字符串分，以便系统能够正确处理和解析您的数据。图片格式支持.jpg / .jpeg / .png 图片文件大小不能超过10MB，图片宽高尺寸不小于300px，图片宽高比介于1:2.5 \~ 2.5:1之间
prompt	string	必须	无	正向文本提示词不能超过2500个字符
negative_prompt	string	可选	空	负向文本提示词不能超过2500个字符
mode	string	可选	std	生成视频的模式枚举值：std，pro其中std：标准模式（标准），基础模式，性价比高其中pro：专家模式（高品质），高表现模式，生成视频质量更佳不同模型版本、视频模式支持范围不同，详见当前文档3-0能力地图
duration	string	可选	5	生成视频时长，单位s枚举值：5，10
aspect_ratio	string	可选	16:09	生成图片的画面纵横比（宽:高）枚举值：16:9, 9:16, 1:1
callback_url	string		无	本次任务结果回调通知地址，如果配置，服务端会在任务状态发生变更时主动通知具体通知的消息schema见“Callback协议”
external_task_id	string	可选	无	自定义任务ID用户自定义任务ID，传入不会覆盖系统生成的任务ID，但支持通过该ID进行任务查询请注意，单用户下需要保证唯一性

请求示例

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": "不要出现负能量的内容",
    "mode": "std",
    "duration": "10",
    "aspect_ratio": "9:16",
    "external_task_id": "xiaosuvideo03013018412"
}'

返回值示例

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

查询任务

请求URL

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

请求方法

GET

请求示例

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

返回值示例

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

对口型

人脸识别-创建任务

请求URL

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

请求方法

POST

请求参数

字段	类型	必填	默认值	描述
video_id	string	可选	无	通过可灵AI生成的视频的ID 用于指定视频、判断视频是否可用于对口型服务与video_url参数二选一填写，不能同时为空，也不能同时有值仅支持使用30天内生成的时长不超过60秒的视频
video_url	string	可选	无	所上传视频的获取URL 用于指定视频，并判断视频是否可用于对口型服务与video_id参数二选一填写，不能同时为空，也不能同时有值视频文件支持.mp4/.mov，文件大小不超过100MB，视频时长不超过60s且不短于2s，仅支持720p和1080p、长宽的边长均位于512px\~2160px之间，上述校验不通过会返回错误码等信息系统会校验视频内容，如有问题会返回错误码等信息

请求示例

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

返回值示例

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

对口型-创建任务

请求URL

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

请求方法

POST

请求参数

字段	类型	必填	默认值	描述
session_id	string	必须	无	会话ID，会基于对口型人脸识别接口生成
face_choose	array	必填	无	指定人脸对口型包括人脸ID、口型参考等内容等暂时仅支持指定单人对口型
face_choose face_id	string	必填	无	人脸ID由人脸识别接口返回
face_choose audio_id	string	可选	空	通过试听接口生成的音频的ID 仅支持使用30天内生成的、时长不短于2秒且不超过60秒的音频 audio_id、sound_file参数二选一，不能同时为空，也不能同时有值
face_choose sound_file	string	可选	空	音频文件支持传入音频Base64编码或图音频URL（确保可访问）音频文件支持.mp3/.wav/.m4a，文件大小不超过5MB，格式不匹配或文件过大会返回错误码等信息仅支持使用时长不短于2秒且不长于60秒的音频 audio_id、sound_file参数二选一，不能同时为空，也不能同时有值系统会校验音频内容，如有问题会返回错误码等信息
face_choose sound_start_time	long	必须	无	音频裁剪起点时间以原始音频开始时间为准，开始时间为0分0秒，单位ms 起点之前的音频会被裁剪，裁剪后音频不得短于2秒
face_choose sound_end_time	long	必须	无	音频裁剪终点时间以原始音频开始时间为准，开始时间为0分0秒，单位ms 终点之后的音频会被裁剪，裁剪后音频不得短于2秒，终点时间不得晚于原始音频总时长
face_choose sound_insert_time	long	必须	无	裁剪后音频插入时间以视频开始时间为准，视频开始时间为0分0秒，单位ms 插入音频的时间范围与该人脸可对口型时间区间至少重合2秒时长，插入音频的开始时间不得早于视频开始时间，插入音频的结束时间不得晚于视频结束时间
face_choose sound_volume	float	可选	1	音频音量大小；值越大，音量越大取值范围：[0, 2]
face_choose original_audio_volume	float	可选	1	原始视频音量大小；值越大，音量越大取值范围：[0, 2] 原视频无声时，当前参数无效果
external_task_id	string	可选	无	自定义任务ID 用户自定义任务ID，传入不会覆盖系统生成的任务ID，但支持通过该ID进行任务查询请注意，单用户下需要保证唯一性
callback_url	string	可选	无	本次任务结果回调通知地址，如果配置，服务端会在任务状态发生变更时主动通知具体通知的消息schema见“Callback协议”

请求示例

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

返回值示例

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

查询任务

请求URL

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

请求方法

GET

请求示例

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'

返回值示例

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

O1生视频

创建主体

请求URL

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

请求方法

POST

请求参数

字段	类型	必填	默认值	描述
element_name	string	必须	无	主体名称不能超过20个字符
element_description	string	必须	无	主体描述不能超过100个字符
element_frontal_image	string	必须	无	主体正面参考图支持传入图片Base64编码或图片URL（确保可访问）图片格式支持.jpg / .jpeg / .png 图片文件大小不能超过10MB，图片宽高尺寸不小于300px，图片宽高比要在1:2.5 \~ 2.5:1之间
element_refer_list	array	必须	无	主体其他参考列表可通过上传多张、不同角度的主体参考图来定义主体外观至少上传1张参考图，至多上传3张参考图用key:value承载，其中具体如下："element_refer_list":[ {"image_url":"image_url_1"}, {"image_url":"image_url_2"}, {"image_url":"image_url_3"} ]

请求示例

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"}]
}'

返回值示例

{
  "code": 0, //错误码；具体定义见错误码
  "message": "string", //错误信息
  "request_id": "string", //请求ID，系统生成，用于跟踪请求、排查问题
  "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" // 主体来源，kling为官方主体库，数字为创作者ID
  }
}

查询个人主体列表

请求URL

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

请求方法

GET

查询参数

字段	类型	必填	默认值	描述
pageNum	int	可选	1	页码取值范围：[1,1000]
pageSize	int	可选	30	每页数据量取值范围：[1,500]

返回值示例

{
  "code": 0, //错误码；具体定义见错误码
  "message": "string", //错误信息
  "request_id": "string", //请求ID，系统生成，用于跟踪请求、排查问题
  "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" // 主体来源，kling为官方主体库，其他为创作者ID
    }
  ]
}

查询官方主体列表

请求URL

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

请求方法

GET

查询参数

字段	类型	必填	默认值	描述
pageNum	int	可选	1	页码取值范围：[1,1000]
pageSize	int	可选	30	每页数据量取值范围：[1,500]

返回值示例


{
  "code": 0, //错误码；具体定义见错误码
  "message": "string", //错误信息
  "request_id": "string", //请求ID，系统生成，用于跟踪请求、排查问题
  "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" // 主体来源，kling为官方主体库，其他为创作者ID
    }
  ]
}

创建任务

请求URL

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

请求方法

POST

请求参数

字段	类型	必填	默认值	描述
prompt	string	必须	无	文本提示词，可包含正向描述和负向描述可将提示词模板化来满足不同的视频生成需求不能超过2500个字符。通过<<<>>>的格式来指定某个主体、图片或视频，如：<<\>>、<<\>>、<<\>>
image_list	array	可选	空	参考图列表包括主体、场景、风格等参考图片，也可作为首帧或尾帧生成视频；当作为首帧或尾帧生成视频时：通过type参数来定义图片是否为首尾帧：first_frame为首帧，end_frame为尾帧暂时不支持仅尾帧，即有尾帧图时必须有首帧图首帧或首尾帧生视频时，不能使用视频编辑功能用key:value承载，如下："image_list":[ { "image_url":"image_url", "type":"first_frame" }, { "image_url":"image_url", "type":"end_frame" } ]支持传入图片Base64编码或图片URL（确保可访问）图片格式支持.jpg / .jpeg / .png图片文件大小不能超过10MB，图片宽高尺寸不小于300px，图片宽高比要在1:2.5 \~ 2.5:1之间有参考视频时，参考图片数量不得超过4；无参考视频时，参考图片数量不得超过7数组中超过2张图片时，不支持设置尾帧
element_list	array	可选	空	主体参考列表基于主体库中主体的ID配置，用key:value承载，如下："element_list":[ { "element_id":long } ]参考主体数量与有无参考视频、参考图片数量有关，其中：有参考视频时，参考图片数量和参考主体数量之和不得超过4；无参考视频时，参考图片数量和参考主体数量之和不得超过7
video_list	array	可选	空	参考视频，通过URL方式获取可作为特征参考视频，也可作为待编辑视频，默认为待编辑视频；可选择性保留视频原声通过refer_type参数区分参考视频类型：feature为特征参考视频，base为待编辑视频参考视频为待编辑视频时，不能定义视频首尾帧通过keep_original_sound参数选择是否保留视频原声，yes为保留，no为不保留；当前参数对特征参考视频（feature）也生效用key:value承载，如下："video_list":[ { "video_url":"video_url", "refer_type":"base", "keep_original_sound":"yes" } ]视频格式仅支持MP4/MOV仅支持时长≥3秒且≤10秒的视频视频宽高尺寸需介于720px（含）和2160px（含）之间视频帧率基于24fps～60fps，生成视频时会输出为24fps至多仅支持上传1段视频，视频大小不超过200MB
mode	string	可选	pro	生成视频的模式,枚举值：std，pro 其中std：标准模式（标准），基础模式，性价比高其中pro：专家模式（高品质），高表现模式，生成视频质量更佳
aspect_ratio	string	可选	空	生成视频的画面纵横比（宽:高）枚举值：16:9, 9:16, 1:1。未使用首帧参考或视频编辑功能时，当前参数必填
duration	string	可选	5	生成视频时长，单位s枚举值：3，4，5，6，7，8，9，10，其中：使用文生视频、首帧图生视频、首尾帧生视频时，仅支持5和10s使用视频编辑功能。（"refer_type":"base"）时，输出结果与传入视频时长相同，此时当前参数无效；此时，按输入视频时长四舍五入取整计量计费
callback_url	string	可选	空	本次任务结果回调通知地址，如果配置，服务端会在任务状态发生变更时主动通知。具体通知的消息schema见“Callback协议”
external_task_id	string	可选	空	自定义任务ID用户自定义任务ID，传入不会覆盖系统生成的任务ID，但支持通过该ID进行任务查询请注意，单用户下需要保证唯一性

请求示例

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": "基于<<<element_1>>>，生成图中人物正在前行的镜头，远方天空中隐隐有佛光闪耀",
    "mode": "pro",
    "aspect_ratio":"16:9",
    "element_list": [
        {
            "element_id": 829376081165181009
        }
    ]
}'

返回值示例


{
  "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/omni-video/{id}

请求方法

GET

查询参数

字段	类型	必填	默认值	描述
task_id	string	可选	无	文生视频的任务ID请求路径参数，直接将值填写在请求路径中，与external_task_id两种查询方式二选一
external_task_id	string	可选	无	文生视频的自定义任务ID创建任务时填写的external_task_id，与task_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，防盗链格式（请注意，为保障信息安全，生成的图片/视频会在30天后被清理，请及时转存）
           "duration": "string" //视频总时长，单位s
        }
      ]
    },
    "created_at": 1722769557708, //任务创建时间，Unix时间戳、单位ms
    "updated_at": 1722769557708 //任务更新时间，Unix时间戳、单位ms
  }
}

O1生图片

创建任务

请求URL

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

请求方法

POST

请求参数

字段	类型	必填	默认值	描述
prompt	string	必须	无	文本提示词，可包含正向描述和负向描述可将提示词模板化来满足不同的图像生成需求不能超过2500个字符。通过<<<>>>的格式来指定某个图片，如：<<\>>
image_list	array	可选	空	参考图列表用key:value承载，如下："image_list":[ { "image":"image_url", } ] 支持传入图片Base64编码或图片URL（确保可访问）图片格式支持.jpg / .jpeg / .png 图片文件大小不能超过10MB，图片宽高尺寸不小于300px，图片宽高比要在1:2.5 \~ 2.5:1之间图片数量不超过10张
element_list	array	可选	空	主体参考列表基于主体库中主体的ID配置，用key:value承载，如下："element_list":[ { "element_id":long } ] 参考主体数量与参考图片数量有关，参考主体数量和参考图片数量之和不得超过10
resolution	string	可选	1k	生成图片的清晰度枚举值：1k, 2k 1k：1K标清 2k：2K高清
n	int	可选	1	生成图片数量取值范围：[1,9]
aspect_ratio	string	可选	auto	生成图片的画面纵横比（宽:高）枚举值：16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9, auto。其中：auto为根据传入内容智能生成视频参考原图横纵比生成新图时，当前参数无效
callback_url	string	可选	无	本次任务结果回调通知地址，如果配置，服务端会在任务状态发生变更时主动通知。具体通知的消息schema见“Callback协议”

请求示例

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": "两条粉红锦鲤优雅地并肩游动",
    "n": 1
}'

返回值示例

{
    "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/images/omni-image/{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":{
            "images":[
              {
                "index": int, //图片编号，0-9
                "url": "string" //生成图片的URL，防盗链格式（请注意，为保障信息安全，生成的图片/视频会在30天后被清理，请及时转存）
              }
            ]
    },
    "created_at": 1722769557708, //任务创建时间，Unix时间戳、单位ms
    "updated_at": 1722769557708 //任务更新时间，Unix时间戳、单位ms
  }
}

数字人

创建任务

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

自定义音色

创建任务

请求URL

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

请求方法

POST

请求参数

字段	类型	必填	默认值	描述
voice_name	string	必须	无	音色名称文本内容最大长度20个字符创建后不再使用的音色可通过API删除
voice_url	string	可选	空	音色数据文件获取链接支持.mp3/.wav/.mp4/.mov格式的音视频文件音频中人声需干净无杂音，有且只能有一种人声，时长不短于5秒且不长于30秒
video_id	string	可选	空	历史作品ID，可通过引用历史作品提供音频素材仅满足以下条件的视频可以用于定制音色：使用V2.6版本模型生成且开启sound参数值为on的视频通过数字人API生成的视频通过对口型API生成的视频音频中人声需干净无杂音，有且只能有一种人声，时长不短于5秒且不长于30秒
callback_url	string	可选	空	本次任务结果回调通知地址，如果配置，服务端会在任务状态发生变更时主动通知具体通知的消息schema见“Callback协议”
external_task_id	string	可选	空	自定义任务ID 用户自定义任务ID，传入不会覆盖系统生成的任务ID，但支持通过该ID进行任务查询请注意，单用户下需要保证唯一性

请求示例

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

返回值示例

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

查询任务（单个）

请求URL

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

请求方法

GET

查询参数

字段	类型	必填	默认值	描述
task_id	string	必须	无	音色名称文本内容最大长度20个字符创建后不再使用的音色可通过API删除

请求示例

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

返回值示例

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

查询任务（列表）

请求URL

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

请求方法

GET

查询参数

字段	类型	必填	默认值	描述
pageNum	int	可选	1	页码取值范围：[1,1000]
pageSize	int	可选	30	每页数据量取值范围：[1,500]

请求示例

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

返回值示例

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

查询官方音色（列表）

请求URL

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

?pageNum=1\&pageSize=10

请求方法

GET

查询参数

字段	类型	必填	默认值	描述
pageNum	int	可选	1	页码取值范围：[1,1000]
pageSize	int	可选	30	每页数据量取值范围：[1,500]

请求示例

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

返回值示例

{
    "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": "钓系女友",
                        "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"
}

删除自定义音色

请求URL

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

请求方法

POST

请求参数

字段	类型	必填	默认值	描述
voice_id	string	必须	无	待删除的音色的ID，仅支持删除自定义音色

请求示例

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

返回值示例

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

MaaS_KeLing_V2.6指定音色

接口见 MaaS_KL接口文档图生视频

请求示例

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": "妈妈<<<voice_1>>>说写得很整齐，但有个错别字，女儿用笔另一头的橡皮擦着写错的字，说，那我改一下吧",
    "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"
}'

动作控制

创建任务

请求URL

https://genaiapi.cloudsway.net/v1/ai/{endpoinPath}/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可用连续动作即可生成。请注意，因此消耗的积分将无法退还，建议适当调整动作难度与速度系统会校验视频内容，如有问题会返回错误码等信息
keep_original_sound	string	可选	yes	可选择是否保留视频原声枚举值：yes，no 其中yes：保留视频原声其中no：不保留视频原声
character_orientation	string	必须	无	生成视频中人物的朝向，可选择与图片一致或与视频一致枚举值：image，video，其中：其中image：与图片中人物朝向一致；此时参考视频时长不得超过10秒；其中video：与视频中人物朝向一致；此时参考视频时长不得超过30秒；
mode	string	必须	无	生成视频的模式枚举值：std，pro 其中std：标准模式（标准），基础模式，性价比高其中pro：专家模式（高品质），高表现模式，生成视频质量更佳
callback_url	string	可选	无	本次任务结果回调通知地址，如果配置，服务端会在任务状态发生变更时主动通知
external_task_id	string	可选	无	自定义任务ID 用户自定义任务ID，传入不会覆盖系统生成的任务ID，但支持通过该ID进行任务查询请注意，单用户下需要保证唯一性

请求示例

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

查询任务

请求URL

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

请求方法

GET

请求示例

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

MaaS_KL接口文档

请求协议

Header

文生视频

创建任务

请求URL

请求方法

请求参数

请求示例

返回值示例

查询任务

请求URL

请求方法

查询参数

返回值示例

图生视频

创建任务

请求URL

请求方法

请求参数

请求示例

返回值示例

查询任务

请求URL

请求方法

查询参数

返回值示例

视频延长

创建任务

请求URL

请求方法

请求参数

请求示例

返回值示例

查询任务

请求URL

请求方法

查询参数

返回值示例

多图参考生视频

创建任务

请求URL

请求方法

请求参数

请求示例

返回值示例

查询任务

请求URL

请求方法

请求示例

返回值示例

对口型

人脸识别-创建任务

请求URL

请求方法

请求参数

请求示例

返回值示例

对口型-创建任务

请求URL

请求方法

请求参数

请求示例

返回值示例

查询任务

请求URL

请求方法

请求示例

返回值示例

O1生视频

创建主体

请求URL

请求方法

请求参数

请求示例

返回值示例

查询个人主体列表

请求URL

请求方法

查询参数