# 文生视频

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

## 请求头

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

## 请求体

| 参数名称               | 类型     | 必填  | 参数描述                                                         |
|--------------------|--------|-----|--------------------------------------------------------------|
| model              | String | 是   | 模型名称<br>可选值：`viduq3-turbo` 、`viduq3-pro` 、`viduq2` 、`viduq1` <br>- viduq3-turbo：对比viduq3-pro，生成速度更快<br>- viduq3-pro：高效生成优质音视频内容，让视频内容更生动、更形象、更立体，效果更好<br>- viduq2：最新模型<br>- viduq1：画面清晰，平滑转场，运镜稳定 |
| style              | String | 可选  | 风格<br>默认 `general`，可选值：`general`、`anime`<br>`general`：通用风格，可以通过提示词来控制风格<br>`anime`：动漫风格，仅在动漫风格表现突出，可以通过不同的动漫风格提示词来控制<br>注：使用q2、q3系列模型时该参数不生效 |
| prompt             | String | 是   | 文本提示词<br>生成视频的文本描述。<br>注：字符长度不能超过 5000 个字符                   |
| duration           | Int    | 可选  | 视频时长参数，默认值依据模型而定：<br>- viduq3-pro、viduq3-turbo: 默认5秒，可选：1-16<br>- viduq2 : 默认5秒，可选：1-10<br>- viduq1 : 默认5秒，可选：5 |
| seed               | Int    | 可选  | 随机种子<br>当默认不传或者传0时，会使用随机数替代<br>手动设置则使用设置的种子                  |
| aspect_ratio       | String | 可选  | 比例<br>默认 `16:9`，可选值：`16:9`、`9:16`、`3:4`、`4:3`、`1:1`<br>注：`3:4`、`4:3`仅支持q2、q3系列模型 |
| resolution         | String | 可选  | 分辨率参数，默认值依据模型和视频时长而定：<br>- viduq3-pro、viduq3-turbo(1-16秒)：默认 720p，可选：540p、720p、1080p<br>- viduq2(1-10秒)：默认 720p，可选：540p、720p、1080p<br>- viduq1(5秒)：默认 1080p，可选：1080p |
| movement_amplitude | String | 可选  | 运动幅度<br>默认 `auto`，可选值：`auto`、`small`、`medium`、`large`<br>注：使用q2、q3系列模型时该参数不生效 |
| bgm                | Bool   | 可选  | 是否为生成的视频添加背景音乐。<br>默认：false，可选值 true 、false<br>传 true 时系统将从预设 BGM 库中自动挑选合适的音乐并添加；不传或为 false 则不添加 BGM。<br>- BGM不限制时长，系统根据视频时长自动适配<br>- BGM参数在q2模型的duration为 9秒 或 10秒 时不生效；该参数在q3系列模型中不生效 |
| audio              | Bool   | 可选  | 是否使用音视频直出能力，默认为true，枚举值为：<br>- false：不需要音视频直出，输出静音视频<br>- true：需要音画同步，输出声音的视频（包括台词和音效）<br>注1：仅q3系列模型支持该参数 |
| payload            | String | 可选  | 透传参数<br>不做任何处理，仅数据传输<br>注：最多 1048576个字符                      |
| off_peak           | Bool   | 可选  | 错峰模式，默认为：false，可选值：<br>- true：错峰生成视频；<br>- false：即时生成视频；<br>注1：错峰模式消耗的积分更低，具体请查看[产品定价](https://platform.vidu.cn/docs/pricing)<br>注2：错峰模式下提交的任务，会在48小时内生成，未能完成的任务会被自动取消，并返还该任务的积分；<br>注3：您也可以[手动取消](https://platform.vidu.cn/docs/cancel-task-api)错峰任务 |
| watermark          | Bool   | 可选  | 是否添加水印<br>- true：添加水印；<br>- false：不添加水印；<br>注1：目前水印内容为固定，内容由AI生成，默认不加<br>注2：您可以通过watermarked_url参数查询获取带水印的视频内容，详情见[查询任务接口](https://platform.vidu.cn/docs/search-task-api) |
| wm_position        | Int    | 可选  | 水印位置，表示水印出现在图片的位置，可选项为：<br>`1`：左上角<br>`2`：右上角<br>`3`：右下角<br>`4`：左下角<br>默认为：3 |
| wm_url             | String | 可选  | 水印内容，此处为图片URL<br>不传时，使用默认水印：内容由AI生成                          |
| meta_data          | String | 可选  | 元数据标识，json格式字符串，透传字段，您可以 自定义格式 或使用 示例格式 ，示例如下：<br>{<br>"Label": "your_label",<br>"ContentProducer": "your_content_producer",<br>"ContentPropagator": "your_content_propagator",<br>"ProduceID": "your_product_id", <br>"PropagateID": "your_propagate_id",<br>"ReservedCode1": "your_reserved_code1", <br>"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-pro",
    "style": "general",
    "prompt": "In an ultra-realistic fashion photography style featuring light blue and pale amber tones, an astronaut in a spacesuit walks through the fog. The background consists of enchanting white and golden lights, creating a minimalist still life and an impressive panoramic scene.",
    "duration": 5,
    "seed": 0,
    "aspect_ratio": "4:3",
    "resolution": "540p",
    "movement_amplitude": "auto",
    "off_peak": false
}' https://api.vidu.cn/ent/v2/text2video
```

## 响应体

| 字段 | 类型 | 描述 |
| --- | --- | --- |
| task_id | String | Vidu 生成的任务ID |
| state | String | 处理状态<br>可选值：<br>`created` 创建成功<br>`queueing` 任务排队中<br>`processing` 任务处理中<br>`success` 任务成功<br>`failed` 任务失败 |
| model | String | 本次调用的模型名称 |
| prompt | String | 本次调用的提示词参数 |
| duration | Int | 本次调用的视频时长参数 |
| seed | Int | 本次调用的随机种子参数 |
| aspect_ratio | String | 本次调用的 比例 参数 |
| resolution | String | 本次调用的分辨率参数 |
| bgm | 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-pro",
  "style": "general",
  "prompt": "In an ultra-realistic fashion photography style featuring light blue and pale amber tones, an astronaut in a spacesuit walks through the fog. The background consists of enchanting white and golden lights, creating a minimalist still life and an impressive panoramic scene.",
  "duration": 5,
  "seed": 0,
  "aspect_ratio": "4:3",
  "resolution": "540p",
  "movement_amplitude": "auto",
  "payload":"",
  "off_peak": false,
  "credits": 12,
  "created_at": "2025-01-01T15:41:31.968916Z"
}
```
