跳转到主要内容
POST
/
vidu
/
ent
/
v2
/
reference2video
Vidu 参考生视频 (viduq3)
curl --request POST \
  --url https://api.powertokens.ai/vidu/ent/v2/reference2video \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "viduq3",
  "subjects": [
    {
      "name": "your_subject1_name",
      "images": [
        "your_image_url1",
        "your_image_url2",
        "your_image_url3"
      ],
      "voice_id": ""
    },
    {
      "name": "your_subject2_name",
      "images": [
        "your_image_url4",
        "your_image_url5",
        "your_image_url6"
      ],
      "voice_id": ""
    }
  ],
  "prompt": "@your_subject1_name 和 @your_subject2_name 在一起吃火锅，并且旁白音说火锅大家都爱吃。",
  "duration": 8,
  "audio": true
}
'
{
  "task_id": "your_task_id_here",
  "state": "created",
  "model": "viduq3",
  "images": [
    "your_image_url1",
    "your_image_url2"
  ],
  "prompt": "@1 和 @2 在一起吃火锅，并且旁白音说火锅大家都爱吃。",
  "duration": 8,
  "seed": "random_number",
  "aspect_ratio": "3:4",
  "resolution": "1080p",
  "movement_amplitude": "auto",
  "payload": "",
  "off_peak": false,
  "credits": "credits_number",
  "created_at": "2025-01-01T15:41:31.968916Z"
}

授权

​
Authorization
string
header
必填

在请求头中传入 Authorization: Bearer <token>。

请求体

application/json
​
model
enum<string>
必填

模型名称可选值：viduq3

  • viduq3-turbo：支持智能切镜，支持音画同出，生成速度最快，性价比最高
  • viduq3：支持智能切镜，支持音画同出，多机位的一致性更出色
可用选项:
viduq3
​
subjects
object[]
必填

使用q3、q2、q1、2.0模型时，只能使用图片主体和文字主体

  • 图片或文字主体最多不超过7个 使用q2-pro模型时，可以使用视频主体、文字主体和图片主体
  • 图片或文字主体最多不超过4个
  • 视频主体最多不超过2个（如果是临时的视频主体，则最多1个） 注：viduq3-mix暂不支持使用主体
Required array length: 1 - 7 elements
​
prompt
string
必填

文本提示词生成视频的文本描述。 注1：字符长度不能超过 5000 个字符 注2：使用sujects主体参数时，可以通过@主体name 来表示主体内容，例如："@1 和 @2 在一起吃火锅，并且旁白音说火锅大家都爱吃。"

Maximum string length: 5000
​
auto_subjects
boolean
默认值:false

是否使用智能主体库能力，默认false，可选值 true、false

  • true：使用智能主体库能力。
  • false：不使用智能主体库能力。
​
server_id
string

通过创建主体API获取的 主体id，使用已有主体时必传该参数

  • 创建主体参考[创建和使用主体库
​
audio
boolean
默认值:false

是否使用音视频直出能力，默认false，可选值 true、false

  • true：使用音视频直出能力。
  • false：不使用音视频直出能力。 viduq3、viduq3-turbo默认audio为true，其他模型为false
​
audio_type
enum<string>
默认值:all

音频类型，audio为true时必填，默认为all

  • all：音效+人声
  • speech_only：仅人声
  • sound_effect_only：仅音效
可用选项:
all,
speech_only,
sound_effect_only
​
voice_id
string

音色ID用来决定视频中的声音音色，为空时系统会自动推荐，可选枚举值参考列表：新音色列表 或者您可以使用声音复刻API来复刻任意音色，voice_id可以互通

  • 该参数在q3参考生模型中不生成
​
duration
integer

视频时长参数，默认值依据模型而定： viduq3-turbo：默认5秒，可选：3 - 16 viduq3：默认5秒，可选：3 - 16

​
seed
integer

随机种子当默认不传或者传0时，会使用随机数替代手动设置则使用设置的种子

​
aspect_ratio
enum<string>
默认值:16:9

比例默认 16:9，可选值如下：16:9、9:16、1:1

可用选项:
16:9,
9:16,
1:1
​
resolution
enum<string>

分辨率参数，默认值依据模型和视频时长而定： viduq3-turbo（3-16秒）：默认 720p, 可选：540p、720p、1080p viduq3（3-16秒）：默认 720p, 可选：540p、720p、1080p

可用选项:
540p,
720p,
1080p
​
movement_amplitude
enum<string>
默认值:auto

运动幅度默认 auto，可选值：auto、small、medium、large 注：使用q2、q3模型时该参数不生效

可用选项:
auto,
small,
medium,
large
​
payload
string

透传参数不做任何处理，仅数据传输注：最多 1048576个字符

Maximum string length: 1048576
​
off_peak
boolean
默认值:false

错峰模式，默认为：false，可选值：

  • true：错峰生成视频；
  • false：即时生成视频； 注1：错峰模式消耗的积分更低，具体请查看产品定价 注2：错峰模式下提交的任务，会在48小时内生成，未能完成的任务会被自动取消，并返还该任务的积分； 注3：您也可以手动取消错峰任务 注4：q3模型在audio参数为true时，支持错峰任务；
​
watermark
boolean
默认值:false

是否添加水印

  • true：添加水印；
  • false：不添加水印； 注1：目前水印内容为固定，内容由AI生成，默认不加 注2：您可以通过watermarked_url参数查询获取带水印的视频内容，详情见查询任务接口
​
wm_position
integer
默认值:3

水印位置，表示水印出现在图片的位置，默认为：3，可选项为： 1：左上角 2：右上角 3：右下角 4：左下角

​
wm_url
string

水印内容，此处为图片URL不传时，使用默认水印：内容由AI生成

​
meta_data
string

元数据标识，json格式字符串，透传字段，您可以 自定义格式 或使用 示例格式 ，示例如下： { "Label": "your_label","ContentProducer": "yourcontentproducer","ContentPropagator": "your_content_propagator","ProduceID": "yourproductid", "PropagateID": "your_propagate_id","ReservedCode1": "yourreservedcode1", "ReservedCode2": "your_reserved_code2" } 该参数为空时，默认使用vidu生成的元数据标识

​
callback_url
string

Callback 协议 需要您在创建任务时主动设置 callback_url，请求方法为 POST，当视频生成任务有状态变化时，Vidu 将向此地址发送包含任务最新状态的回调请求。回调请求内容结构与查询任务API的返回体一致 回调返回的"status"包括以下状态：

  • processing 任务处理中
  • success 任务完成（如发送失败，回调三次）
  • failed 任务失败（如发送失败，回调三次） Vidu采用回调签名算法进行认证，详情见：回调签名算法

响应

提交成功，返回视频任务对象。

​
task_id
string

Vidu 生成的任务ID

​
state
enum<string>

处理状态 可选值： created 创建成功 queueing 任务排队中 processing 任务处理中 success 任务成功 failed 任务失败

可用选项:
created,
queueing,
processing,
success,
failed
​
model
string

本次调用的模型名称

​
prompt
string

本次调用的提示词参数

​
images
string[]

本次调用的图像参数

​
duration
integer

本次调用的视频时长参数

​
seed
integer

本次调用的随机种子参数

​
aspect_ratio
string

本次调用的 比例 参数

​
resolution
string

本次调用的分辨率参数

​
bgm
boolean

本次调用的背景音乐参数

​
audio
boolean

本次调用是否开启音视频直出

​
audio_type
string

本次调用输出的音频类型

​
movement_amplitude
string

本次调用的镜头动态幅度参数

​
payload
string

本次调用时传入的透传参数

​
off_peak
boolean

本次调用时是否使用错峰模式

​
credits
integer

本次调用使用的积分数

​
watermark
boolean

本次提交任务是否使用水印

​
created_at
string<date-time>

任务创建时间