# 参考生视频
## 请求地址

`POST https://api.vidu.cn/ent/v2/reference2video`

### 请求头

| 字段 | 值 | 描述 |
| --- | --- | --- |
| Content-Type | application/json | 数据交换格式 |
| Authorization | Token `{your api key}` | 将 `{your api key}` 替换为您的 token |

## 使用主体调用参考生

### 请求体

| 参数名称               | 子参数       | 类型            | 必填  | 参数描述                                                         |
|--------------------|-----------|---------------|-----|--------------------------------------------------------------|
| model              |           | String        | 是   | 模型名称可选值：`viduq3-turbo`、`viduq3`、`viduq2-pro`、`viduq2`、`viduq1`、`vidu2.0`<br>- viduq3-turbo：支持智能切镜，支持音画同出，生成速度最快，性价比最高<br>- viduq3：支持智能切镜，支持音画同出，多机位的一致性更出色<br>- viduq2-pro：支持参考视频，支持视频编辑，视频替换<br>- viduq2：动态效果好，生成细节丰富<br>- viduq1：画面清晰，平滑转场，运镜稳定<br>- vidu2.0：生成速度快 |
| auto_subjects      |           | bool          | 可选  | 是否使用智能主体库能力，默认false，可选值 true、false<br>- true：使用智能主体库能力。<br>- false：不使用智能主体库能力。 |
| subjects           |           | List\[Array\] | 是   | 使用q3、q2、q1、2.0模型时，只能使用图片主体和文字主体<br> - 图片或文字主体最多不超过7个<br>使用q2-pro模型时，可以使用视频主体、文字主体和图片主体<br> - 图片或文字主体最多不超过4个<br> - 视频主体最多不超过2个（如果是临时的视频主体，则最多1个）<br>注：`viduq3-mix`暂不支持使用主体 |
|                    | name      | String        | 是   | 主体id，后续生成时可以通过@主体id的方式使用                                     |
|                    | images    | Array{String} | 可选  | 主体图片，该主体对应的图片url，与videos必填一个<br>注1：支持传入图片 Base64 编码或图片URL（确保可访问）；<br>**注2：最多支持输入 3 张图；**<br>注3：图片支持 png、jpeg、jpg、webp格式；<br>注4：图片比例需要小于 1:4 或者 4:1 ；<br>注5：请注意，base64 decode之后的字节长度需要小于20M，且编码必须包含适当的内容类型字符串，例如：<br>`data:image/png;base64,{base64_encode}` |
|                    | videos    | Array{String} | 可选  | 主体视频，该主体对应的视频url，与videos必填一个<br>注1： 仅`viduq2-pro`模型支持使用视频主体<br>注2：每个主体中的图片和视频，共享3个槽位<br>**注3：支持1个5秒视频**<br>注4：支持传入视频 Base64 编码或URL（确保可访问）<br>注5：视频支持 mp4、avi、mov格式<br>注6：视频像素不能小于 128*128，且比例需要小于1:4或者4:1<br>注7：请注意，base64 decode之后的字节长度需要小于20M，且编码必须包含适当的内容类型字符串，例如：<br>`data:video/mp4;base64,{base64_encode}` |
|                    | voice_id  | String        | 可选  | 音色ID用来决定视频中的声音音色，为空时系统会自动推荐，可选枚举值参考列表：[新音色列表](https://shengshu.feishu.cn/sheets/EgFvs6DShhiEBStmjzccr5gonOg)<br>或者您可以使用[声音复刻API](https://platform.vidu.cn/docs/voice-clone)来复刻任意音色，voice_id可以互通<br>- 该参数在q3参考生模型中不生成 |
|                    | server_id | String        | 可选  | 通过创建主体API获取的 主体id，使用已有主体时必传该参数<br>- 创建主体参考[创建和使用主体库 \| Vidu API](https://platform.vidu.cn/docs/subjects) |
| prompt             |           | String        | 是   | 文本提示词生成视频的文本描述。<br>注1：字符长度不能超过 5000 个字符<br>注2：使用sujects主体参数时，可以通过@主体name 来表示主体内容，例如："@1 和 @2 在一起吃火锅，并且旁白音说火锅大家都爱吃。" |
| audio              |           | Bool          | 可选  | 是否使用音视频直出能力，默认false，可选值 true、false<br>- true：使用音视频直出能力。<br>- false：不使用音视频直出能力。<br>viduq3、viduq3-turbo默认audio为true，其他模型为false |
| audio_type         |           | String        | 可选  | 音频类型，audio为true时必填，默认为all<br>- all：音效+人声<br>- speech_only：仅人声<br>- sound_effect_only：仅音效 |
| duration           |           | Int           | 可选  | 视频时长参数，默认值依据模型而定：<br>viduq3-turbo：默认5秒，可选：3 - 16<br>viduq3：默认5秒，可选：3 - 16<br>viduq2-pro：默认5秒，可选：0-10（0秒为自动判断时长）<br>viduq2：默认5秒，可选：1-10<br>viduq1：默认5秒，可选：5<br>vidu2.0：默认4秒，可选：4 |
| seed               |           | Int           | 可选  | 随机种子当默认不传或者传0时，会使用随机数替代手动设置则使用设置的种子                          |
| aspect_ratio       |           | String        | 可选  | 比例默认 16:9，可选值如下：16:9、9:16、1:1<br>注：q2模型 支持任意宽高比              |
| resolution         |           | String        | 可选  | 分辨率参数，默认值依据模型和视频时长而定：<br>viduq3-turbo（3-16秒）：默认 720p, 可选：540p、720p、1080p<br>viduq3（3-16秒）：默认 720p, 可选：540p、720p、1080p<br>viduq2、viduq2-pro ：默认 720p, 可选：540p、720p、1080p<br>viduq1 ：默认 1080p, 可选：1080p<br>vidu2.0 ：默认 360p, 可选：360p、720p |
| movement_amplitude |           | String        | 可选  | 运动幅度默认 auto，可选值：auto、small、medium、large<br>注：使用q2、q3模型时该参数不生效 |
| payload            |           | String        | 可选  | 透传参数不做任何处理，仅数据传输注：最多 1048576个字符                              |
| off_peak           |           | Bool          | 可选  | 错峰模式，默认为：false，可选值：<br>- true：错峰生成视频；<br>- false：即时生成视频；<br>注1：错峰模式消耗的积分更低，具体请查看产品定价<br>注2：错峰模式下提交的任务，会在48小时内生成，未能完成的任务会被自动取消，并返还该任务的积分；<br>注3：您也可以[手动取消](https://platform.vidu.cn/docs/cancel-task-api)错峰任务<br>注4：q3模型在audio参数为true时，支持错峰任务；q2、q1、2.0系列模型在audio为false时支持错峰任务 |
| watermark          |           | Bool          | 可选  | 是否添加水印<br>- true：添加水印；<br>- false：不添加水印；<br>注1：目前水印内容为固定，内容由AI生成，默认不加<br>注2：您可以通过watermarked_url参数查询获取带水印的视频内容，详情见查询任务接口 |
| wm_position        |           | Int           | 可选  | 水印位置，表示水印出现在图片的位置，默认为：3，可选项为：<br>1：左上角<br>2：右上角<br>3：右下角<br>4：左下角 |
| wm_url             |           | String        | 可选  | 水印内容，此处为图片URL不传时，使用默认水印：内容由AI生成                              |
| meta_data          |           | String        | 可选  | 元数据标识，json格式字符串，透传字段，您可以 自定义格式 或使用 示例格式 ，示例如下：<br>{<br>"Label": "your_label","ContentProducer": "yourcontentproducer","ContentPropagator": "your_content_propagator","ProduceID": "yourproductid", "PropagateID": "your_propagate_id","ReservedCode1": "yourreservedcode1", "ReservedCode2": "your_reserved_code2"<br>}<br>该参数为空时，默认使用vidu生成的元数据标识 |
| callback_url       |           | String        | 可选  | Callback 协议<br>需要您在创建任务时主动设置 callback_url，请求方法为 POST，当视频生成任务有状态变化时，Vidu 将向此地址发送包含任务最新状态的回调请求。回调请求内容结构与查询任务API的返回体一致<br>回调返回的"status"包括以下状态：<br>- processing 任务处理中<br>- success 任务完成（如发送失败，回调三次）<br>- failed 任务失败（如发送失败，回调三次）<br>Vidu采用回调签名算法进行认证，详情见：[回调签名算法](https://platform.vidu.cn/docs/callback-signature) |

```bash
curl -X POST -H "Authorization: Token {your_api_key}" -H "Content-Type: application/json" -d '
{
    "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
}' https://api.vidu.cn/ent/v2/reference2video
```

### 响应体

| 字段                 | 类型              | 描述                                                           |
|--------------------|-----------------|--------------------------------------------------------------|
| task_id            | String          | Vidu 生成的任务ID                                                 |
| state              | String          | 处理状态<br>可选值：<br>created 创建成功<br>queueing 任务排队中<br>processing 任务处理中<br>success 任务成功<br>failed 任务失败 |
| model              | String          | 本次调用的模型名称                                                    |
| prompt             | String          | 本次调用的提示词参数                                                   |
| images             | Array\[String\] | 本次调用的图像参数                                                    |
| duration           | Int             | 本次调用的视频时长参数                                                  |
| seed               | Int             | 本次调用的随机种子参数                                                  |
| aspect_ratio       | String          | 本次调用的 比例 参数                                                  |
| resolution         | String          | 本次调用的分辨率参数                                                   |
| bgm                | Bool            | 本次调用的背景音乐参数                                                  |
| audio              | Bool            | 本次调用是否开启音视频直出                                                |
| audio_type         | String          | 本次调用输出的音频类型                                                  |
| movement_amplitude | String          | 本次调用的镜头动态幅度参数                                                |
| payload            | String          | 本次调用时传入的透传参数                                                 |
| off_peak           | Bool            | 本次调用时是否使用错峰模式                                                |
| credits            | Int             | 本次调用使用的积分数                                                   |
| watermark          | Bool            | 本次提交任务是否使用水印                                                 |
| created_at         | String          | 任务创建时间                                                       |

```json
{
  "task_id": "your_task_id_here",
  "state": "created",
  "model": "viduq3",
  "images": ["your_image_url1","your_image_url2"],
  "prompt": "@1 和 @2 在一起吃火锅，并且旁白音说火锅大家都爱吃。",
  "duration": 8,
  "seed": 0,
  "aspect_ratio": "3:4",
  "resolution": "1080p",
  "movement_amplitude": "auto",
  "payload":"",
  "off_peak": false,
  "credits": 12,
  "created_at": "2025-01-01T15:41:31.968916Z"
}
```

## 非主体调用（视频生成）

### 请求体

| 参数名称               | 子参数 | 类型              | 必填  | 参数描述                                                         |
|--------------------|-----|-----------------|-----|--------------------------------------------------------------|
| model              |     | String          | 是   | 模型名称可选值：viduq3-mix、viduq3-turbo、viduq3、viduq2-pro、viduq2、viduq1、vidu2.0<br>- viduq3-mix：画面质感强，支持智能切镜，支持音画同出，动态效果好，均衡性最强<br>- viduq3-turbo：支持智能切镜，支持音画同出，生成速度最快，性价比最高<br>- viduq3：支持智能切镜，支持音画同出，多机位的一致性更出色<br>- viduq2-pro：支持参考视频，支持视频编辑，视频替换<br>- viduq2：动态效果好，生成细节丰富<br>- viduq1：画面清晰，平滑转场，运镜稳定<br>- vidu2.0：生成速度快 |
| images             |     | Array\[String\] | 是   | 图像参考支持上传1～7张图片，模型将以此参数中传入的图片中的主题为参考生成具备主体一致的视频。<br>注1：：viduq3-mix、viduq3-turbo、viduq3、 viduq2、viduq1、vidu2.0模型支持上传1～7张图片<br>注2：使用viduq2-pro模型时，如果不上传视频，则支持上传1-7张图，如果上传视频则支持1-4张图<br>注3：支持传入图片 Base64 编码或图片URL（确保可访问）<br>注4：图片支持 png、jpeg、jpg、webp格式<br>注5：图片像素不能小于 128\*128，且比例需要小于1:4或者4:1，且大小不超过50M。 <br>注6：请注意，http请求的post body不超过20MB，且编码必须包含适当的内容类型字符串，例如：data:image/png;base64,{base64_encode} |
| videos             |     | Array\[String\] | 是   | 视频参考支持上传1～2个视频，模型将以此参数中传入的视频作为参考，生成具备主体一致的视频。<br>注1： 仅viduq2-pro模型支持该参数<br>注2：使用视频参考功能时，最多支持上传 1个8秒 视频 或 2个5秒 视频<br>注3：视频支持 mp4、avi、mov格式<br>注4：视频像素不能小于 128\*128，且比例需要小于1:4或者4:1，且大小不超过100M。<br>注5：请注意，base64 decode之后的字节长度需要小于20M，且编码必须包含适当的内容类型字符串，例如：data:video/mp4;base64,{base64_encode} |
| prompt             |     | String          | 是   | 文本提示词生成视频的文本描述。<br>注：字符长度不能超过 2000 个字符。                      |
| audio              |     | Bool            | 可选  | 是否使用音视频直出能力，默认为true，枚举值为：<br>- false：不需要音视频直出，输出静音视频<br>- true：需要音画同步，输出声音的视频（包括台词和音效）<br>注：非主体调用时，仅q3模型支持该参数 |
| bgm                |     | Bool            | 可选  | 是否为生成的视频添加背景音乐。默认：false，可选值 true 、false<br>- 传 true 时系统将从预设 BGM 库中自动挑选合适的音乐并添加；不传或为 false 则不添加 BGM。<br>- BGM不限制时长，系统根据视频时长自动适配<br>- BGM参数在q2系列模型的duration为 9秒 或 10秒 时不生效<br>- 该参数在q3系列模型中不生效 |
| duration           |     | Int             | 可选  | 视频时长参数，默认值依据模型而定：<br>viduq3-turbo、viduq3-mix：默认5秒，可选3 - 16<br>viduq3：默认5秒，可选3 - 16<br>viduq2-pro：默认5秒，可选：0-10（0秒为自动判断时长）<br>viduq2：默认5秒，可选：1-10<br>viduq1：默认5秒，可选：5<br>vidu2.0：默认4秒，可选：4 |
| seed               |     | Int             | 可选  | 随机种子当默认不传或者传0时，会使用随机数替代手动设置则使用设置的种子                          |
| aspect_ratio       |     | String          | 可选  | 比例默认 16:9，可选值如下：16:9、9:16、4:3、3:4、1:1<br>注：4:3、3:4仅支持q2系列模型  |
| resolution         |     | String          | 可选  | 分辨率参数，默认值依据模型和视频时长而定：<br>viduq3-mix（3-16秒）：默认 720p, 可选：720p、1080p<br>viduq3-turbo（3-16秒）：默认 720p, 可选：540p、720p、1080p<br>viduq3（3-16秒）：默认 720p, 可选：540p、720p、1080p<br>viduq2、viduq2-pro ：默认 720p, 可选：540p、720p、1080p<br>viduq1 ：默认 1080p, 可选：1080p<br>vidu2.0 ：默认 360p, 可选：360p、720p |
| movement_amplitude |     | String          | 可选  | 运动幅度默认 auto，可选值：auto、small、medium、large <br>注：使用q2、q3系列模型时该参数不生效 |
| payload            |     | String          | 可选  | 透传参数不做任何处理，仅数据传输<br>注：最多 1048576个字符                          |
| off_peak           |     | Bool            | 可选  | 错峰模式，默认为：false，可选值：<br>- true：错峰生成视频；<br>- false：即时生成视频；<br>注1：错峰模式消耗的积分更低，具体请查看产品定价；<br>注2：错峰模式下提交的任务，会在48小时内生成，未能完成的任务会被自动取消，并返还该任务的积分；<br>注3：您也可以手动取消错峰任务；<br>注4：viduq3模型在audio参数为true时，支持错峰任务；q2、q1、2.0系列模型在audio为false时支持错峰任务；viduq3-mix模型不支持错峰 |
| watermark          |     | Bool            | 可选  | 是否添加水印<br>- true：添加水印；<br>- false：不添加水印；<br>注1：目前水印内容为固定，内容由AI生成，默认不加<br>注2：您可以通过watermarked_url参数查询获取带水印的视频内容，详情见查询任务接口 |
| wm_position        |     | Int             | 可选  | 水印位置，表示水印出现在图片的位置，默认为：3，可选项为：<br>1：左上角<br>2：右上角<br>3：右下角<br>4：左下角 |
| wm_url             |     | String          | 可选  | 水印内容，此处为图片URL不传时，使用默认水印：内容由AI生成                              |
| meta_data          |     | String          | 可选  | 元数据标识，json格式字符串，透传字段，您可以 自定义格式 或使用 示例格式 ，示例如下：<br>{<br>"Label": "your_label","ContentProducer": "your_content_producer","ContentPropagator": "your_content_propagator","ProduceID": "your_product_id", "PropagateID": "your_propagate_id","ReservedCode1": "your_reserved_code1", "ReservedCode2": "your_reserved_code2"<br>}<br>该参数为空时，默认使用vidu生成的元数据标识 |
| callback_url       |     | String          | 可选  | Callback 协议<br>需要您在创建任务时主动设置 callback_url，请求方法为 POST，当视频生成任务有状态变化时，Vidu 将向此地址发送包含任务最新状态的回调请求。回调请求内容结构与查询任务API的返回体一致<br>回调返回的"status"包括以下状态：<br>- processing 任务处理中<br>- success 任务完成（如发送失败，回调三次）<br>- failed 任务失败（如发送失败，回调三次）<br>Vidu采用回调签名算法进行认证，详情见：回调签名算法 |

```bash
curl -X POST -H "Authorization: Token {your_api_key}" -H "Content-Type: application/json" -d '
{
    "model": "viduq3-mix",
    "images": ["https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-1.png","https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-2.png","https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-3.png"],
    "prompt": "Santa Claus and the bear hug by the lakeside.",
    "duration": 5,
    "seed": 0,
    "aspect_ratio": "3:4",
    "resolution": "720p",
}' https://api.vidu.cn/ent/v2/reference2video
```

### 响应体

| 字段 | 类型 | 描述 |
| --- | --- | --- |
| task_id | String | Vidu 生成的任务ID |
| state | String | 处理状态<br>可选值：<br>created 创建成功<br>queueing 任务排队中<br>processing 任务处理中<br>success 任务成功<br>failed 任务失败 |
| model | String | 本次调用的模型名称 |
| prompt | String | 本次调用的提示词参数 |
| images | Array\[String\] | 本次调用的图像参数 |
| videos | Array\[String\] | 本次调用的视频参数 |
| duration | Int | 本次调用的视频时长参数 |
| seed | Int | 本次调用的随机种子参数 |
| aspect_ratio | String | 本次调用的 比例 参数 |
| resolution | String | 本次调用的分辨率参数 |
| bgm | Bool | 本次调用的背景音乐参数 |
| audio | Bool | 本次调用是否开启音视频直出 |
| movement_amplitude | String | 本次调用的镜头动态幅度参数 |
| payload | String | 本次调用时传入的透传参数 |
| off_peak | Bool | 本次调用时是否使用错峰模式 |
| credits | Int | 本次调用使用的积分数 |
| watermark | Bool | 本次提交任务是否使用水印 |
| created_at | String | 任务创建时间 |

```json
{
  "task_id": "your_task_id_here",
  "state": "created",
  "model": "viduq3-mix",
  "images": ["https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-1.png","https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-2.png","https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-3.png"],
  "prompt": "Santa Claus and the bear hug by the lakeside.",
  "duration": 5,
  "seed": 0,
  "aspect_ratio": "3:4",
  "resolution": "720p",
  "credits": 12,
  "created_at": "2025-01-01T15:41:31.968916Z"
}
```
