Vidu Q3 - Reference to Video

认证

authorization `string` 必填

所有 API 均使用 Bearer Token 鉴权

获取 API Key：

用法：

将以下 Header 添加到请求中：

Authorization: Bearer YOUR_API_KEY

参数（非主体调用）

model `string` 必填

请求使用的模型 ID

值: viduq3_i2v_reference

images `array[string]`

图像参考, 支持上传 1～7 张图片, 模型将以此参数中传入的图片中的主体为参考生成具备主体一致性的视频

注1：支持传入图片 Base64 编码或图片 URL（确保可访问）
注2：图片支持 png、jpeg、jpg、webp 格式
注3：图片像素不能小于 128*128, 且比例需要小于 1:4 或者 4:1, 且大小不超过 50M
注4：请注意, http 请求的 post body 不超过 20MB, 且编码必须包含适当的内容类型字符串, 例如：

data:image/png;base64,{base64_encode}

sounds `array[string]`

音频参考, 支持上传 1～7 个音频, 模型将以此参数中传入的音频作为参考

注1：最多支持上传 7 个音频, 每个音频时长最多 20s
注2：音频支持 mp3 格式
注3：每个音频文件大小不超过 50M
注4：请注意, base64 decode 之后的字节长度需要小于 20M, 且编码必须包含适当的内容类型字符串, 例如：

data:audio/mp3;base64,{base64_encode}

⚠️ 目前暂不支持, 仅提前预留该参数

prompt `string` 必填

生成视频的文本描述

注：字符长度不能超过 5000 个字符

duration `integer`

视频时长

默认值: 5

范围: 3 - 16

seed `integer`

随机种子, 不传或传 0 时使用随机数替代

aspect_ratio `string`

比例参数, 支持任意比例或 auto

默认值: 16:9

可选值: 1:1、9:16、16:9、3:4、4:3、auto（根据输入图自动推荐）

audio `bool`

是否使用音视频直出能力

默认值: true

可选值:
true：需要音画同步, 输出带声音的视频（包括台词和音效）
false：不需要音视频直出, 输出静音视频

resolution `string`

分辨率参数

默认值: 720p

可选值: 720p、1080p

payload `string`

透传参数, 不做任何处理, 仅数据传输

注：最多 1048576 个字符

off_peak `bool`

错峰模式

默认值: false

可选值:
true：错峰生成视频, 消耗的积分更低；错峰模式下提交的任务会在 48 小时内生成, 未能完成的任务会被自动取消并返还积分
false：即时生成视频

注：audio 参数为 true 时支持错峰任务

watermark `bool`

是否添加水印, 默认不加

可选值:
true：添加水印
false：不添加水印

注：目前水印内容为固定, 内容由 AI 生成

wm_position `integer`

水印位置

默认值: 3

可选值:
1：左上角
2：右上角
3：右下角
4：左下角

wm_url `string`

水印内容（图片 URL）, 不传时使用默认水印

meta_data `string`

元数据标识

callback_url `string`

回调 URL

参数（主体调用）

model `string` 必填

请求使用的模型 ID

值: viduq3_i2v_reference

subjects `array[object]` 必填

主体列表, 最多不超过 7 个图片或文字主体

name string 必填

用户指定的主体名称, 生成时可通过 [@name] 的方式在 prompt 中引用

server_id string

通过创建主体 API 获取的主体 ID

prompt `string` 必填

生成视频的文本描述, 通过 [@subjects_name] 来引用主体内容

示例："[@1] 和 [@2] 在一起吃火锅"

注：字符长度不能超过 5000 个字符

audio `bool`

是否使用音视频直出能力

默认值: true

可选值:
true：使用音视频直出能力
false：不使用音视频直出能力

duration `integer`

视频时长

默认值: 5

范围: 3 - 16

seed `integer`

随机种子, 不传或传 0 时使用随机数替代

aspect_ratio `string`

比例参数, 支持任意比例或 auto

默认值: 16:9

可选值: 1:1、9:16、16:9、3:4、4:3、auto（根据输入图或视频自动推荐）

resolution `string`

分辨率参数

默认值: 720p

可选值: 720p、1080p

payload `string`

透传参数, 不做任何处理, 仅数据传输

注：最多 1048576 个字符

off_peak `bool`

错峰模式

默认值: false

注：audio 参数为 true 时支持错峰任务

watermark `bool`

是否添加水印, 默认不加

可选值:
true：添加水印
false：不添加水印

注：目前水印内容为固定, 内容由 AI 生成

wm_position `integer`

水印位置

默认值: 3

可选值:
1：左上角
2：右上角
3：右下角
4：左下角

wm_url `string`

水印内容（图片 URL）, 不传时使用默认水印

meta_data `string`

元数据标识

callback_url `string`

回调 URL

轮询

由于结果生成需要时间，您需要在创建任务后轮询任务状态

初始响应只返回任务 ID 和初始状态等信息，最终生成结果需通过使用该任务 ID 轮询任务状态接口获取

轮询请求与响应示例见右侧

响应格式

error `object`

错误信息, 仅在状态为 failed 时存在

code string

错误码

message string

详细错误信息

output `array`

生成结果, 仅在状态为 completed 时存在

content array

生成的资源内容列表

type string

资源类型

值: image｜video

url string

处理后的资源 URL

jobId string

远端任务 ID

usage `object`

使用统计, 仅在状态为 completed 时存在

cost string

总费用（美元）

discount number

折扣金额

metadata `object`

元数据信息

curl --location \ 'https://cloud.vtrix.ai/model/v1/generation' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "model": "viduq3_i2v_reference", "input": [ { "params": { "prompt": "Santa Claus and the bear hug by the lakeside.", "images": [ "https://example.png" ], "audio": true, "duration": 5 } } ] }'

curl --location \ 'https://cloud.vtrix.ai/model/v1/generation' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "model": "viduq3_i2v_reference", "input": [ { "params": { "subjects": [ { "name": "1", "server_id": "123123" }, { "name": "2", "server_id": "321321" } ], "prompt": "[@1] 和 [@2] 在一起吃火锅", "audio": true, "duration": 5 } } ] }'

{ "id": "task_id", "created_at": 1769757744021, "status": "completed", "model": "viduq3_i2v_reference", "output": [ { "content": [ { "type": "video", "url": "https://example.com/generated-video.mp4" } ] } ], "usage": { "cost": "0.000500", "discount": 0 } }

认证

authorization string 必填

参数（非主体调用）

model string 必填

images array[string]

sounds array[string]

prompt string 必填

duration integer

seed integer

aspect_ratio string

audio bool

resolution string

payload string

off_peak bool

watermark bool

wm_position integer

wm_url string

meta_data string

callback_url string

参数（主体调用）

model string 必填

subjects array[object] 必填

name string 必填

server_id string

prompt string 必填

audio bool

duration integer

seed integer

aspect_ratio string

resolution string

payload string

off_peak bool

watermark bool

wm_position integer

wm_url string

meta_data string

callback_url string

轮询

响应格式

error object

code string

message string

output array

content array

type string

url string

jobId string

usage object

cost string

discount number

metadata object

authorization `string` 必填

model `string` 必填

images `array[string]`

sounds `array[string]`

prompt `string` 必填

duration `integer`

seed `integer`

aspect_ratio `string`

audio `bool`

resolution `string`

payload `string`

off_peak `bool`

watermark `bool`

wm_position `integer`

wm_url `string`

meta_data `string`

callback_url `string`

model `string` 必填

subjects `array[object]` 必填

name `string` 必填

server_id `string`

prompt `string` 必填

audio `bool`

duration `integer`

seed `integer`

aspect_ratio `string`

resolution `string`

payload `string`

off_peak `bool`

watermark `bool`

wm_position `integer`

wm_url `string`

meta_data `string`

callback_url `string`

error `object`

code `string`

message `string`

output `array`

content `array`

type `string`

url `string`

jobId `string`

usage `object`

cost `string`

discount `number`

metadata `object`