1. 接口描述
接口请求域名: vclm.tencentcloudapi.com 。
提交动作控制(Kling)任务并发
默认接口请求频率限制:20次/秒。
2. 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见 公共请求参数。
| 参数名称 | 必选 | 类型 | 描述 |
|---|---|---|---|
| Action | 是 | String | 公共参数,本接口取值:SubmitMotionControlKlingJob。 |
| Version | 是 | String | 公共参数,本接口取值:2024-05-23。 |
| Region | 是 | String | 公共参数,详见产品支持的 地域列表。 |
| Model | 否 | String | 模型名称 枚举值:kling-v2-6, kling-v3。 示例值:kling-v3 |
| Prompt | 否 | String | 文本提示词,可包含正向描述和负向描述 可将提示词模板化来满足不同的视频生成需求 不能超过2500个字 示例值:参考图任务动作和视频保持一致 |
| Image | 否 | String | 参考图像,生成视频中的人物、背景等元素均以参考图为准 视频内容需满足以下要求: 人物比例尽量与参考动作比例一致,尽量避免全身动作驱动半身人物进行生成 人物需要露出清晰的上半身或全身的肢体及头部,避免遮挡 画面中人物避免存在极端朝向,比如倒立、平卧等。人物占画面比例不得太低 支持真实/风格化的角色(包括人物/类人动物/部分纯动物/部分类人肢体比例的角色)通过 包含支持传入图片Base64编码或图片URL(确保可访问)。 示例值:https://****.cos.ap-guangzhou.myqcloud.com/****/video/motion-control/motion-control.jpg |
| Video | 否 | String | 参考视频的获取链接。生成视频中的人物动作与参考视频一致。 视频内容需满足以下要求: 人物需要漏出清晰的上半身或全身的全部肢体及头部,避免遮挡 建议上传1人动作视频,2人及以上会取画面占比最大的人物动作进行生成 推荐使用真人动作,部分风格化的人物/类人肢体比例可以通过 动作视频一镜到底,角色始终出现在画面中,避免切镜、运镜等。否则会被截取 动作避免过快,相对平稳的动作生成效果更佳 视频文件支持.mp4/.mov,文件大小不超过100MB,仅支持长宽的边长均位于340px~3850px之间,上述校验不通过会返回错误码等信息 视频时长下限不短于3秒,时长上限与人物朝向参考(character_orientation)有关: 当人物朝向与视频中人物一致时,视频时长最长可达30秒; 当人物朝向与图片中人物一致时,视频时长最长可达10秒; 如果您的动作难度比较高、速度比较快,有一定概率生成不足上传视频时长的结果,因为模型只能提取有效动作时长进行生成,最短提取出3s可用连续动作即可生成。请注意,因此消耗的积分将无法退还,建议适当调整动作难度与速度 系统会校验视频内容,如有问题会返回错误码等信息。 示例值:https://****.cos.ap-guangzhou.myqcloud.com/****/video/motion-control/motion-control.mp4 |
| Mode | 否 | String | 生成视频的模式 枚举值:std,pro 示例值:std |
| KeepOriginalSound | 否 | String | 可选择是否保留视频原声 枚举值:yes,no 其中yes:保留视频原声 其中no:不保留视频原声。 示例值:yes |
| CharacterOrientation | 否 | String | 生成视频中人物的朝向,可选择与图片一致或与视频一致 枚举值:image,video,其中: 其中image:与图片中人物朝向一致;此时参考视频时长不得超过10秒; 其中video:与视频中人物朝向一致;此时参考视频时长不得超过30秒; 引用主体时,生成的视频暂时只能参考视频中的人物朝向。 示例值:image |
| ElementList.N | 否 | Array of Element | 参考主体列表 基于主体库中主体的ID配置,用key:value承载,如下: "element_list":[ { "element_id":long }, { "element_id":long } ] 参考主体数量与有无参考视频、参考图片数量有关,其中: 当使用首帧生成视频时,最多支持3个主体; 当使用首尾帧生成视频时,kling-v3-omni模型最多支持3个主体,kling-video-o1模不支持主体; 有参考视频时,参考图片数量和参考主体数量之和不得超过4,且不支持使用视频角色主体; 无参考视频时,参考图片数量和参考主体数量之和不得超过7; |
| CallbackUrl | 否 | String | 本次任务结果回调通知地址,如果配置,服务端会在任务状态发生变更时主动通知 示例值:http://*:8080 |
| LogoAdd | 否 | Integer | 为生成视频添加标识的开关,默认为1,0 需前往 控制台 申请开启显示标识自主完成方可生效。 1:添加标识; 0:不添加标识; 其他数值:默认按1处理。 示例值:0 |
| LogoParam | 否 | LogoParam | 默认在生成视频的右下角添加“ AI 生成”字样,如需替换为其他的标识图片,需前往 控制台 申请开启显示标识自主完成。 |
3. 输出参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| JobId | String | 任务ID 示例值:1428569086702002176 |
| RequestId | String | 唯一请求 ID,由服务端生成,每次请求都会返回(若请求因其他原因未能抵达服务端,则该次请求不会获得 RequestId)。定位问题时需要提供该次请求的 RequestId。 |
4. 示例
示例1 调用成功示例
输入示例
POST / HTTP/1.1
Host: vclm.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: SubmitMotionControlKlingJob
<公共请求参数>
{
"Prompt": "参考图任务动作和视频保持一致",
"Model": "kling-v3",
"Mode": "std",
"CallbackUrl": "http://*********:8080",
"Image": "https://************************.cos.ap-guangzhou.myqcloud.com/********/video/motion-control/motion-control.jpg",
"Video": "https://************************.cos.ap-guangzhou.myqcloud.com/********/video/motion-control/motion-control.mp4",
"KeepOriginalSound": "yes",
"CharacterOrientation": "image"
}
输出示例
{
"Response": {
"JobId": "1428569086702002176",
"RequestId": "67f7771e-ebf2-49cf-ad5d-bd9fd1fa3724"
}
}
5. 开发者资源
腾讯云 API 平台
腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台,方便您从同一入口查询及使用腾讯云提供的所有 API 服务。
API Inspector
用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况,并自动生成各语言版本的 API 代码,也可前往 API Explorer 进行在线调试。
SDK
云 API 3.0 提供了配套的开发工具集(SDK),支持多种编程语言,能更方便的调用 API。
- Tencent Cloud SDK 3.0 for Python: CNB, GitHub, Gitee
- Tencent Cloud SDK 3.0 for Java: CNB, GitHub, Gitee
- Tencent Cloud SDK 3.0 for PHP: CNB, GitHub, Gitee
- Tencent Cloud SDK 3.0 for Go: CNB, GitHub, Gitee
- Tencent Cloud SDK 3.0 for Node.js: CNB, GitHub, Gitee
- Tencent Cloud SDK 3.0 for .NET: CNB, GitHub, Gitee
- Tencent Cloud SDK 3.0 for C++: CNB, GitHub, Gitee
- Tencent Cloud SDK 3.0 for Ruby: CNB, GitHub, Gitee
命令行工具
6. 错误码
该接口暂无业务逻辑相关的错误码,其他错误码详见 公共错误码。