创建视频生成任务-主体调用参考生视频
更新时间：2026-03-25
POST
https://qianfan.baidubce.com/beta/video/generations/qianfan-video
本接口支持通过定义主体并结合提示词，精准生成包含特定人物、语音及动作的主体一致性视频，接口返回task_id用于后续查询结果。
权限说明
调用本文API，需使用API Key鉴权方式。使用API Key鉴权调用API流程，具体调用流程，请查看认证鉴权。
请求参数
Headers 参数
除公共头域外，无其它特殊头域
Body 参数
model
string
模型名称。
VQ2：最新模型VQ1：画面清晰，平滑转场，运镜稳定V2.0：生成速度快VQ2-Pro：新模型，效果好，细节丰富，目前仅支持非主体调用
必选
type
string
任务类型，固定值：reference2video。
必选
model_parameters
object {10}
必选
显示子属性
隐藏子属性
subjects
array
图片主体信息，用于定义视频中的特定角色或主体。支持 1-3 个主体，所有主体图片总和需在 1-7 张之间。
subjects 与 images 为互斥参数，仅能选择其中一种方式传参。
- 当
audio为true时，必须使用subjects参数。 - 当
audio为false时，可选择subjects（生成无声视频）或images。
必选
images
array
通用参考图像，当不使用主体定义subjects时，通过此参数传入 1-7 张参考图。
subjects和images参数二选一。如subjects参数有值，此参数必须为空。
- 支持
png,jpeg,jpg,webp格式。 - 支持 URL (需公网可访问) 或 Base64，Base64 解码后 < 10MB， 符合格式：
data:image/png;base64,{base64_encode} - 图片像素不能小于 128*128，比例需在 1:4 到 4:1 之间，大小不超过 50MB。
可选
显示子属性
隐藏子属性
items
string
prompt
string
提示词，用于描述生成的视频内容。
字符长度不能超过 1500 个字符。
必选
bgm
boolean
是否为生成的视频添加背景音乐，默认值：false。
true：开启。系统将从预设 BGM 库中自动挑选并适配适合视频时长的音乐。false：关闭。不添加背景音乐。 生效限制：- 当
audio参数为true时，bgm参数不生效。 - 当使用
VQ2系列模型且视频时长 (duration) 设置为 9秒 或 10秒 时，bgm参数不生效。
可选
duration
integer
视频时长（秒）。
VQ2：默认设置为 5 秒，支持自定义设置 1 至 10 秒 的任意整数时长。VQ1：默认设置为 5 秒，仅支持 5 秒 固定时长。V2.0：默认设置为 4 秒，仅支持 4 秒 固定时长。
可选
audio
boolean
音视频开关，默认值：false。
true：启用音视频。必须传入subjects参数，此时bgm参数失效。false：仅生成视频画面。subjects与images参数可选其一，且bgm参数生效。
可选
aspect_ratio
string
画面比例，默认值：16:9
- 通用可选值：16:9, 9:16, 1:1
VQ2模型仅支持 4:3, 3:4。
可选
resolution
string
分辨率，默认值取决于模型与时长。
VQ2 (1-10s)：默认 720p。可选：540p, 720p, 1080p。VQ1 (5s)：默认 1080p。可选：1080p。V2.0 (4s)：默认 360p。可选：360p, 720p。
可选
movement_amplitude
string
运动幅度，默认值：auto
可选值：auto, small, medium, large。
使用VQ2模型时该参数不生效。
可选
seed
integer
随机种子。
当未传入种子或传入值为0时，系统将自动生成随机数作为种子，确保每次生成结果具有随机性。
用户可传入非零整数值作为固定种子，以实现结果的可复现性。
可选
请求结构
POST /beta/video/generations/qianfan-video HTTP/1.1
HOST: qianfan.baidubce.com
Authorization: Bearer <API Key>
Content-Type: application/json
{
"model": "VQ2",
"type": "reference2video",
"model_parameters": {
"images": [
"https://example.com/image_1.jpg",
"https://example.com/image_2.jpg",
"https://example.com/image_3.jpg",
],
"prompt": "一个人物在雪中行走，与参考图像保持一致。",
"audio": false,
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9",
"seed": 42
}
}示例代码
基础调用
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": "VQ2",
"type": "reference2video",
"model_parameters": {
"subjects": [
{
"id": "hero_001",
"images": [
"https://example.com/image_1.jpg"
],
"voice_id": "male-qn-qingse"
}
],
"prompt": "电影镜头中，hero_001伫立雨中，神情严肃地交谈",
"audio": true,
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9"
}
}'返回响应
Headers 参数
除公共头域外，无其它特殊头域
返回参数
log_id
string
日志ID，用于问题排查。
必选
task_id
string
任务ID，用于后续查询生成结果。
必选
status
string
任务状态，标识当前任务所处阶段。
created创建成功queueing任务排队中processing任务处理中success任务成功failed任务失败
必选
model
string
使用的模型名称。
必选
images
array
图像参考。
可选
显示子属性
隐藏子属性
items
string
prompt
string
输入的提示词内容。
必选
duration
integer
视频时长 (秒)。
可选
seed
integer
使用的随机种子。
可选
resolution
string
生成的视频分辨率。
可选
aspect_ratio
string
画面比例。
可选
bgm
boolean
背景音乐。
可选
created_at
string
任务创建的时间，格式为时间戳字符串（毫秒级）。
必选
任务创建成功
{
"log_id": "as-kt1mc6gsji",
"task_id": "697b42989e7e53a32e55bb3c",
"status": "created",
"model": "VQ2",
"prompt": "电影镜头中，hero_001伫立雨中，神情严肃地交谈",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9",
"created_at": "1769685656000"
}错误码
如果调用失败并返回报错信息，请参见错误码进行解决。
公共错误码：查看公共错误码
本接口专有错误码如下：
| HTTP状态码 | 错误码 | 错误信息 | 错误描述 |
|---|---|---|---|
| 400 | BadRequest | bad request | 不合法的请求。 |
| 400 | FieldLacking | field is missing or empty: {{.fields}} | 缺少字段，具体字段见错误信息。 |
| 400 | FieldUnwanted | unwanted field: {{.fields}} | 不需要传某些字段，具体字段见错误信息。 |
| 400 | FieldItemCountOutOfRange | field item count out of range: {{.fields}} | 字段数量超出限制（如数组长度超限）。 |
| 400 | PageSizeOutOfRange | page size out of range | 图像尺寸或格式有问题。 1. 图片大小需小于 50M。 2. 格式只支持 jpg/jpeg/png/webp。 3. 图片长宽比需要小于 1:4 或者 4:1。 4. 跳舞特效的图片长宽比需要在 1:1.2 至 1:2 之间。 |
| 400 | ImageDownloadFailure | image download failure | 下载用户图片URL失败，请检查链接的有效性。 |
| 400 | OperationInProcess | operation in process, please retry later | 请求在处理中，请勿重复提交。 |
| 400 | TaskPromptPolicyViolation | prompt policy violation | Prompt 触发安审风控。 |
| 400 | ImageFormatInvalid | invalid image format | 图像格式不符合要求。 |
| 400 | AuditSubmitIllegal | submit is illegal | 输入内容（图片或文本）没有通过安全审核。 |
| 400 | CreationPolicyViolation | creation policy violation | 生成物触发风控。 |
| 400 | ModelUnavailable | model unavailable | 请求的模型不可用，调用任务失败，请检查模型类型并重试。 |
| 400 | FieldInvalid | invalid field: {{.fields}} | 传入参数未通过合法性校验。 |
| 400 | ImageCheckBodyJointsFailed | Image Check Body Joins Failed | 输入图人体检测失败，请重新上传。 |
| 400 | ImageCheckFaceFailed | Image Check Face Failed | 输入图人脸检测失败，请重新上传。 |
| 400 | ImageObjectsUndetected | Image BodyJoins or Face Too Much Occlusion | 输入图的人体或人脸有遮挡，请重新上传。 |
| 404 | TaskNotFound | task not found | Task id 没找到。 |
| 404 | CreationNotFound | creation not found | Creation id 没找到。 |
| 500 | InternalServiceFailure | internal service failure | 服务器内部错误，请稍后重试，或联系客服。 |
视频模型通用错误码
| HTTP状态码 | 错误码 | 错误信息 | 错误描述 |
|---|---|---|---|
| 500 | internal_error | video_genration_interal_error | video generation service interal error |
| 400 | invalid_request_error | invalid_lipsync_argument | |
| 429 | rate_limit_exceeded | video_genration_concurrency_exceeded | Rate limit reached for Concurrency |
| 403 | unsafe_request | video_genration_prompt_unsafe | the content of prompt field is unsafe |
评价此篇文章