> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Vidu Q4 Preview 视频生成

> 使用 Vidu Q4 Preview 模型生成视频，支持图生视频和多参考图生成，参考模式可挂参考音频

<Note>
  **国内用户请注意：** 中国大陆用户请使用 `https://toapis.cn` 作为接口地址（Base URL）。文档示例中的 `https://toapis.com` 请替换为 `https://toapis.cn`。
</Note>

* 异步任务接口，提交后返回任务 ID
* 支持模型：`viduq4-preview`
* 两种生成模式：
  * **首帧图生视频**：单张图片作为首帧
  * **参考生视频**：多张参考图，可附加参考音频

<Warning>
  请传入公网可访问的图片和音频 URL。不要在 `image_urls`、`reference_images` 或 `sounds` 中直接传 base64 数据；本地文件请先使用 [上传图片接口](../../uploads/images) 获取 URL。
</Warning>

## 认证

<ParamField header="Authorization" type="string" required>
  所有接口均需要使用 Bearer Token 认证。

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## 请求参数

<ParamField body="model" type="string" required>
  模型名称，固定为 `viduq4-preview`。
</ParamField>

<ParamField body="prompt" type="string" required>
  视频提示词，描述主体、动作、场景、镜头和风格。
</ParamField>

<ParamField body="image_urls" type="string[]">
  图片 URL 数组。生成模式由 `video_generation_mode` 和图片数量决定：

  * **首帧模式**（默认）：在 `image_urls` 中传入恰好 1 张图片 URL，图片作为首帧。
  * **参考模式**：将 `video_generation_mode` 设为 `reference_images_to_video`，在 `image_urls`（或 `reference_images`）中传入参考图。

  示例：`["https://example.com/first-frame.jpg"]`
</ParamField>

<ParamField body="video_generation_mode" type="string">
  生成模式选择器。

  可选值：

  * `reference_images_to_video` - 多参考图生成，`image_urls` 中的多张图片按参考图处理

  省略时为首帧图生视频。传入多张图片、`reference_images` 或 `sounds` 的请求会自动路由到参考生视频。
</ParamField>

<ParamField body="duration" type="integer" default="5">
  视频时长（秒），`3` 到 `16`。
</ParamField>

<ParamField body="resolution" type="string" default="720p">
  视频分辨率。

  可选值：

  * `540p`
  * `720p`
  * `1080p`
  * `2K`
  * `4K`
</ParamField>

<ParamField body="aspect_ratio" type="string">
  视频宽高比，用于参考模式。

  可选值：`16:9`、`9:16`、`4:3`、`3:4`、`1:1`
</ParamField>

<ParamField body="audio" type="boolean" default="true">
  是否为视频生成音频。
</ParamField>

<ParamField body="watermark" type="boolean" default="false">
  是否在生成的视频上添加水印。
</ParamField>

<ParamField body="seed" type="integer">
  随机种子，相同参数下可获得更可复现的结果。
</ParamField>

<ParamField body="metadata" type="object">
  扩展参数，用于传递上游 API 支持但未暴露为顶层字段的参数。

  <Expandable title="展开 metadata 字段">
    <ParamField body="is_rec" type="boolean">
      是否自动扩写优化提示词。省略时上游默认为 `true`。
    </ParamField>

    <ParamField body="sounds" type="string[]">
      参考音频 URL 数组（仅参考生视频模式），最多 3 个音频文件。

      示例：`["https://example.com/voice.mp3"]`
    </ParamField>

    <ParamField body="wm_position" type="integer">
      水印位置，`1` 到 `4`。当 `watermark` 为 `true` 时生效。
    </ParamField>

    <ParamField body="wm_url" type="string">
      自定义水印图片 URL。当 `watermark` 为 `true` 时生效。
    </ParamField>

    <ParamField body="meta_data" type="string">
      自定义元数据标识，JSON 格式字符串，原样透传到结果中。
    </ParamField>

    <ParamField body="callback_url" type="string">
      ToAPIs 任务最终 Webhook。需先配置 Token URL 和签名密钥，详见 [任务 Webhooks](/docs/cn/api-reference/webhooks/task-webhooks)。
    </ParamField>
  </Expandable>
</ParamField>

## 模式选择

| 模式 | 触发方式 | 图片输入 | 音频输入 |
| - | - | - | - |
| 首帧图生视频 | `image_urls` 传 1 张图（默认） | 恰好 1 张 | 仅 `audio` 开关 |
| 参考生视频 | `video_generation_mode: "reference_images_to_video"`，或多图 / `reference_images` / `sounds` | 最多 15 张参考图 | 最多 3 条 `sounds` + `audio` 开关 |

## 计费维度

Vidu Q4 Preview 按生成视频秒数计费，按分辨率分档定价：

* `540p` / `720p` / `1080p` / `2K` / `4K` - 分辨率越高单价越高

## 响应

<ResponseField name="id" type="string">
  任务 ID，用于查询任务状态。
</ResponseField>

<ResponseField name="object" type="string">
  对象类型，通常为 `generation.task`。
</ResponseField>

<ResponseField name="model" type="string">
  请求使用的模型。
</ResponseField>

<ResponseField name="status" type="string">
  任务状态：`queued`、`in_progress`、`completed` 或 `failed`。
</ResponseField>

<ResponseField name="created_at" type="integer">
  任务创建时间戳。
</ResponseField>

## 示例

### 首帧图生视频

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "图片中的人物缓缓转身微笑，电影质感打光",
  "image_urls": ["https://example.com/portrait.jpg"],
  "duration": 5,
  "resolution": "1080p",
  "audio": true
}
```

### 参考生视频

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "保持参考图中的人物一致，夜晚霓虹城市街道上行走",
  "video_generation_mode": "reference_images_to_video",
  "image_urls": [
    "https://example.com/character-front.jpg",
    "https://example.com/character-side.jpg"
  ],
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "3:4",
  "audio": true
}
```

### 带参考音频的参考生视频

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "人物说出台词，口型与声音同步",
  "video_generation_mode": "reference_images_to_video",
  "image_urls": ["https://example.com/character.jpg"],
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "metadata": {
    "sounds": ["https://example.com/voice.mp3"]
  }
}
```

### 提示词扩写与水印

```json theme={null}
{
  "model": "viduq4-preview",
  "prompt": "一只猫在夕阳下的沙滩上行走",
  "image_urls": ["https://example.com/cat.jpg"],
  "duration": 8,
  "resolution": "2K",
  "watermark": true,
  "metadata": {
    "is_rec": true
  }
}
```

<Note>
  视频生成为异步任务。使用 [获取视频任务状态](../../tasks/video-status) 接口查询进度和结果。
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://toapis.com/v1/videos/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "viduq4-preview",
      "prompt": "图片中的人物缓缓转身微笑，电影质感打光",
      "image_urls": ["https://example.com/portrait.jpg"],
      "duration": 5,
      "resolution": "1080p",
      "audio": true
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://toapis.com/v1/videos/generations",
      headers={
          "Authorization": "Bearer <token>",
          "Content-Type": "application/json",
      },
      json={
          "model": "viduq4-preview",
          "prompt": "图片中的人物缓缓转身微笑，电影质感打光",
          "image_urls": ["https://example.com/portrait.jpg"],
          "duration": 5,
          "resolution": "1080p",
          "audio": True,
      },
  )

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://toapis.com/v1/videos/generations", {
    method: "POST",
    headers: {
      Authorization: "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "viduq4-preview",
      prompt: "图片中的人物缓缓转身微笑，电影质感打光",
      image_urls: ["https://example.com/portrait.jpg"],
      duration: 5,
      resolution: "1080p",
      audio: true
    })
  });

  console.log(await response.json());
  ```
</RequestExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.