MaaS_KL接口文档
请求协议
http
Header
| 参数名 | 类型 | 描述 |
|---|---|---|
| Authorization | string | 鉴权 |
视频生成-文生视频-创建任务
请求URL
https://genaiapi.cloudsway.net/v1/ai/{endpoinPath}/kling/videos/text2video
请求方法
POST
请求体
| 字段 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| model_name | string | 可选 | kling-v1 | 模型名称，枚举值: MaaS_KL_V1.5, MaaS_KL_V1.6, MaaS_KL_V1 |
| prompt | string | 必须 | 无 | 正向文本提示词，不能超过2500个字 |
| negative_prompt | string | 可选 | 空 | 负向文本提示词，不能超过2500个字符 |
| cfg_scale | float | 可选 | 0.5 | 生成视频的自由度；值越大，模型自由度越小，与用户输入的提示词相关性越强，取值范围: [0, 1] |
| mode | string | 可选 | std | 生成视频的模式 - 枚举值: std, pro 。其中std:标准模式(标准)，基础模式，性价比高；pro:专家模式(高品质)，高表现模式，生成视频质量更佳。不同模型版本、视频模式支持范围不同，详见当前文档3 - 0能力地图 |
| camera_control | object | 可选 | 空 | 控制摄像机运动的协议(如未指定，模型将根据输入的文本/图片进行智能匹配)。不同模型版本、视频模式支持范围不同，详见当前文档3 - 0能力地图 |
| 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.5, MaaS_KL_V1.6, MaaS_KL_V1 |
| 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不同模型版本、视频模式支持范围不同，详见当前文档3 - 0能力地图 |
| image_tail | string | 可选 | 空 | 参考图像 - 尾帧控制。支持传入图片Base64编码或图片URL(确保可访问)，参数格式要求同image。图片格式支持.jpg / .jpeg / .png，图片文件大小不能超过10MB，图片分辨率不小于300*300px。image参数与image_tail参数至少二选一，二者不能同时为空。image+image_tail参数、dynamic_masks/static_mask参数、camera_control不同模型版本、视频模式支持范围不同，详见当前文档3 - 0能力地图 |
| prompt | string | 可选 | 无 | 正向文本提示词，不能超过2500个字符 |
| negative_prompt | string | 可选 | 空 | 负向文本提示词，不能超过2500个字符 |
| cfg_scale | float | 可选 | 0.5 | 生成视频的自由度；值越大，模型自由度越小，与用户输入的提示词相关性越强，取值范围: [0, 1] |
| mode | string | 可选 | std | 生成视频的模式 - 枚举值:std, pro。其中std:标准模式(标准)，基础模式，性价比高；pro:专家模式(高品质)，高表现模式，生成视频质量更佳。不同模型版本、视频模式支持范围不同，详见当前文档3 - 0能力地图 |
| static_mask | string | 可选 | 无 | 静态笔刷涂抹区域(用户通过运动笔刷涂抹的mask图片)。“运动笔刷”能力包含“动态笔刷dynamic_masks”和“静态笔刷static_mas”。支持传入图片Base64编码或图片URL(确保可访问，格式要求同image)。图片格式支持.jpg / .jpeg / .png，图片长宽比必须与输入图片相同(即image字段)，否则任务失败。static_mask和dynamic_masks.mask这两张图片的分辨率必须一致。不同模型版本、视频模式支持范围不同，详见当前文档3 - 0能力地图 |
| 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 | 可选 | 空 | 控制摄像机运动的协议(如未指定，模型将根据输入的文本/图片进行智能匹配)。不同模型版本、视频模式支持范围不同，详见当前文档3 - 0能力地图 |
| 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（仅支持V1.0模型，不支持V1.5模型）
- 支持图生视频接口生成的视频ID（仅支持V1.0模型，不支持V1.5模型）
- 支持视频延长接口生成的视频ID（注意不能超过3分钟）
| 字段 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| video_id | string | 必须 | 无 | 视频ID - 支持文生视频接口生成的视频ID（仅支持V1.0模型，不支持V1.5模型） - 支持图生视频接口生成的视频ID（仅支持V1.0模型，不支持V1.5模型） - 支持视频延长接口生成的视频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
}
}