创建视频生成任务-动作控制
更新时间:2026-10-14
POST
https://qianfan.baidubce.com/beta/video/generations/qianfan-video
本接口通过动作控制模式生成视频,返回task_id用于后续查询结果。
权限说明
调用本文API,需使用API Key鉴权方式。使用API Key鉴权调用API流程,具体调用流程,请查看认证鉴权。
请求参数
Headers 参数
除公共头域外,无其它特殊头域
Body 参数
model
string
模型名称。可选值: K2.6, K3.0
必选
type
string
任务类型。固定值为:motion-control。
必选
model_parameters
object {7}
模型参数配置。
必选
显示子属性
隐藏子属性
prompt
string
文本提示词,包含正向描述和负向描述,可通过提示词为画面增加元素、实现运镜效果等。不能超过2500个字符。
可选
image_url
string
参考图像,生成视频中的人物、背景等元素均以参考图为准。
格式约束:
- 格式支持:
.jpg、.jpeg、.png - 大小不超过
10MB,宽和高均需介于300px~65536px之间,宽高比例介于1:2.5~2.5:1之间 - 支持传入图片 URL(需确保公网可访问)或图片 Base64 编码,Base64 编码不可包含头部前缀(如
data:image/png;base64,)。 画面主体要求: - 支持真实或风格化角色(包含人物、类人动物、部分纯动物、具类人肢体比例的角色)。
- 需露出清晰的头部及上半身/全身,避免严重遮挡。避免倒立、平卧等极端身体朝向。
- 人物在画面中的占比不可过低。为保证生成效果,图中人物比例应尽量与目标驱动动作的比例保持一致(例如:避免用全身动作驱动半身人物图)。
必选
video_url
string
动作参考视频链接。模型将提取该视频中的动作并应用于生成的主体。
格式约束:
- 仅支持 .mp4 或 .mov,文件不超过 100MB。
- 长宽边长均须介于 340px ~ 3850px 之间。 内容要求:
- 主体需露出清晰且无遮挡的头部及上半身/全身。
- 推荐单人平稳动作(若为多人,仅提取画面占比最大者的动作)。建议使用真人动作。
- 无切镜、无运镜,角色需始终保持在画面内。 时长限制:
- 由人物朝向(character_orientation)决定。若与视频人物朝向一致,最长 30秒;若与图片人物朝向一致,最长 10秒。
- 视频不可短于 3秒。若动作过快或难度过高,模型可能仅截取部分有效连续动作进行生成(保底生成 3秒)。 注:因截断导致的生成时长不足,已消耗的积分不予退还。
必选
element_list
array
主体参考列表,基于主体库中主体的 ID 配置。
引用主体时,生成的视频暂时只能参考视频中的人物朝向,暂时仅支持引入1个主体。
可选
显示子属性
隐藏子属性
items
object {1}
显示子属性
隐藏子属性
element_id
integer
主体库中主体的 ID
必选
keep_original_sound
string
是否保留视频原声。
yes:表示保留视频原声no:表示不保留视频原声
可选
character_orientation
string
生成视频中人物的朝向,可选择与图片一致或与视频一致。
image:表示与图片中人物朝向一致,此时参考视频时长不得超过 10 秒video:表示与视频中人物朝向一致,此时参考视频时长不得超过 30 秒。
必选
请求结构
POST /beta/video/generations/qianfan-video HTTP/1.1
HOST: qianfan.baidubce.com
Authorization: Bearer <API Key>
Content-Type: application/json
{
"model": "K3.0",
"type": "motion-control",
"model_parameters": {
"prompt": "一只猫在草地上奔跑",
"image_url": "https://example.com/image.jpg",
"video_url": "https://example.com/video.mp4",
"element_list": [
{
"element_id": 829836802793406551
}
],
"keep_original_sound": "yes",
"character_orientation": "video",
"mode": "std"
}
}
示例代码
curl
curl -X POST "https://qianfan.baidubce.com/beta/video/generations/qianfan-video" \
-H "Authorization: Bearer bce-v3/ALTAK-******ZftZDTn7/125eeb1c5e9ddc8cf3edf18ef6d03f1517ec9408" \
-H "Content-Type: application/json" \
-d '{
"model": "K3.0",
"type": "motion-control",
"model_parameters": {
"prompt": "一只猫在草地上奔跑",
"image_url": "https://example.com/image.jpg",
"video_url": "https://example.com/video.mp4",
"element_list": [
{
"element_id": 829836802793406551
}
],
"keep_original_sound": "yes",
"character_orientation": "video",
"mode": "std"
}
}'
返回响应
Headers 参数
除公共头域外,无其它特殊头域
返回参数
code
integer
错误码。
必选
message
string
错误信息。
必选
request_id
string
请求ID。
必选
data
object {5}
返回数据体,包含任务相关信息。
必选
显示子属性
隐藏子属性
task_id
string
任务ID。
必选
task_status
string
任务状态。
submitted:已提交processing:处理中succeed:成功failed:失败
必选
created_at
integer
任务创建时间,Unix 时间戳(毫秒)。
必选
updated_at
integer
任务更新时间,Unix 时间戳(毫秒)。
必选
task_info
object
任务详细信息。
必选
显示子属性
隐藏子属性
JSON
{
"code": 0,
"message": "",
"request_id": "as-j68a31c4rb",
"data": {
"task_id": "69ba687977005787f422c1c3",
"task_status": "submitted",
"created_at": 1773824121234,
"updated_at": 1773824121234,
"task_info": {}
}
}
错误码
如果调用失败并返回报错信息,请参见错误码进行解决。
公共错误码:查看公共错误码
视频模型通用错误码
| HTTP状态码 | 错误码 | 错误信息 | 错误描述 |
|---|---|---|---|
| 500 | internal_error | video_generation_internal_error | video generation service internal error |
| 400 | invalid_request_error | invalid_lipsync_argument | |
| 429 | rate_limit_exceeded | video_generation_concurrency_exceeded | Rate limit reached for Concurrency |
| 403 | unsafe_request | video_generation_prompt_unsafe | the content of prompt field is unsafe |
评价此篇文章
