> ## 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 Q3 視頻生成

> 使用 Vidu Q3 視頻模型生成異步視頻任務。

<Note>
  **中國大陸用戶請注意：** 中國大陸用戶請使用 `https://toapis.cn` 作為接口地址（Base URL）。文檔示例中的 `https://toapis.com` 請替換為 `https://toapis.cn`。
</Note>

* 異步任務接口，提交後返回統一 `generation.task`
* 當前對外模型：`viduq3-pro-fast`、`viduq3-ad`、`viduq3-drama`、`viduq3-mix`

<Warning>
  `viduq3-ad`、`viduq3-drama`、`viduq3-mix` 不是純文生視頻模型。不要只傳 `prompt`；至少需要參考素材。否則上游通常會返回 `InvalidParameter`，例如 `Missing required field 'subjects' in request body`。
</Warning>

## 認證

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

  ```http theme={null}
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## 支持模型

| 模型 | 生成類型 | 推薦輸入 | 推薦分辨率 |
| - | - | - | - |
| `viduq3-pro-fast` | 首幀圖生視頻 | 1 張參考圖 | `720P` / `1080P` |
| `viduq3-ad` | 參考視頻生成 | 參考視頻 + 參考圖 | `720P` / `1080P` |
| `viduq3-drama` | 劇情型參考視頻生成 | 參考視頻 + 參考圖 | `1080P` |
| `viduq3-mix` | 混合參考生成 | 參考視頻 + 參考圖 | `720P` / `1080P` |

## 請求參數

<ParamField body="model" type="string" required>
  只支持以下 4 個對外模型名：

  * `viduq3-pro-fast`
  * `viduq3-ad`
  * `viduq3-drama`
  * `viduq3-mix`
</ParamField>

<ParamField body="prompt" type="string" required>
  提示詞。

  即使是參考生成模型也建議始終填寫 `prompt`，用於描述鏡頭、動作、節奏和風格。
</ParamField>

<ParamField body="image_urls" type="string[]">
  參考圖片 URL 列表。

  * `viduq3-pro-fast`：只使用第 1 張圖片，作為首幀
  * `viduq3-ad` / `viduq3-drama` / `viduq3-mix`：建議傳 1 張或多張主體/風格參考圖

  兼容字段：

  * `input_reference`
  * `reference_images`
  * `images`
  * `image`
</ParamField>

<ParamField body="url" type="string">
  參考視頻 URL。

  僅 `viduq3-ad` / `viduq3-drama` / `viduq3-mix` 推薦傳入。等價於傳入一個主參考視頻。
</ParamField>

<ParamField body="video_list" type="array">
  參考視頻列表。

  僅 `viduq3-ad` / `viduq3-drama` / `viduq3-mix` 使用。每一項支持：

  * `video_url`
  * `refer_type`（可選）
  * `keep_original_sound`（可選）
</ParamField>

<ParamField body="duration" type="integer" default={5}>
  視頻時長，單位秒。默認 `5`。
</ParamField>

<ParamField body="resolution" type="string" default="720P">
  分辨率，支持 `720P`、`1080P`。

  建議：

  * `viduq3-drama` 優先使用 `1080P`
</ParamField>

<ParamField body="audio" type="boolean">
  是否生成音頻。

  當前服務端默認行為：

  * `viduq3-pro-fast`：默認 `true`
  * `viduq3-ad`：默認 `true`
  * `viduq3-mix`：默認 `true`
  * `viduq3-drama`：建議顯式傳值，不要依賴默認值
</ParamField>

<ParamField body="watermark" type="boolean" default={false}>
  是否添加水印。
</ParamField>

<ParamField body="seed" type="integer">
  隨機種子。
</ParamField>

<ParamField body="metadata" type="object">
  擴展參數，會按上游視頻請求結構嘗試透傳。

  常見用法：

  * `metadata.input.first_frame_url`
  * `metadata.input.last_frame_url`
  * `metadata.input.audio_url`
  * `metadata.parameters.audio`
  * `metadata.parameters.watermark`

  <Warning>
    `viduq3-ad` / `viduq3-drama` / `viduq3-mix` 在上游側可能要求主體結構化輸入（如 `subjects`）。如果只傳純文本 prompt，通常會直接失敗。
  </Warning>
</ParamField>

## 輸入規則

### 1. `viduq3-pro-fast`

* 這是首幀圖生視頻模型
* 至少傳 1 張圖
* 多張圖時當前只會取第 1 張
* 適合「讓靜態圖片動起來」的場景

### 2. `viduq3-ad` / `viduq3-drama` / `viduq3-mix`

* 這是參考視頻生成模型，不建議純 prompt 調用
* 推薦至少傳：
  * 1 個參考視頻：`url` 或 `video_list`
  * 1 張參考圖：`image_urls` 或兼容圖片字段
* 如果缺少主體/參考素材，上游可能返回：
  * `InvalidParameter`
  * `Missing required field 'subjects' in request body`

## 請求示例

### `viduq3-pro-fast` 首幀圖生視頻

```bash theme={null}
curl --request POST \
  --url 'https://toapis.com/v1/videos/generations' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "viduq3-pro-fast",
    "prompt": "让角色自然抬头微笑，镜头轻微推进，保留原画风格。",
    "image_urls": [
      "https://example.com/first-frame.png"
    ],
    "duration": 5,
    "resolution": "720P",
    "audio": true,
    "watermark": false
  }'
```

### `viduq3-ad` 參考視頻生成

```bash theme={null}
curl --request POST \
  --url 'https://toapis.com/v1/videos/generations' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "viduq3-ad",
    "prompt": "延续参考视频中的节奏与镜头语言，让主角走入商场中庭并面向镜头挥手。",
    "url": "https://example.com/reference-video.mp4",
    "image_urls": [
      "https://example.com/subject-reference.png"
    ],
    "duration": 5,
    "resolution": "1080P",
    "audio": true
  }'
```

### `viduq3-drama` 劇情型參考生成

```bash theme={null}
curl --request POST \
  --url 'https://toapis.com/v1/videos/generations' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "viduq3-drama",
    "prompt": "保持角色一致性，情绪逐步递进，镜头由中景切到近景。",
    "video_list": [
      {
        "video_url": "https://example.com/reference-scene.mp4"
      }
    ],
    "image_urls": [
      "https://example.com/character.png"
    ],
    "duration": 5,
    "resolution": "1080P",
    "watermark": false
  }'
```

### `viduq3-mix` 混合參考生成

```bash theme={null}
curl --request POST \
  --url 'https://toapis.com/v1/videos/generations' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "viduq3-mix",
    "prompt": "融合参考视频动作与参考图角色设定，生成一个更具广告感的过场镜头。",
    "url": "https://example.com/reference-action.mp4",
    "image_urls": [
      "https://example.com/brand-character.png"
    ],
    "duration": 5,
    "resolution": "720P",
    "audio": true
  }'
```

## 提交成功響應

```json theme={null}
{
  "id": "vid_01KABCDEF1234567890",
  "object": "generation.task",
  "model": "viduq3-pro-fast",
  "status": "queued",
  "progress": 0,
  "created_at": 1784169600
}
```

## 查詢任務

`GET /v1/videos/generations/{task_id}`

處理中：

```json theme={null}
{
  "id": "vid_01KABCDEF1234567890",
  "object": "generation.task",
  "model": "viduq3-pro-fast",
  "status": "in_progress",
  "progress": 60,
  "created_at": 1784169600
}
```

成功：

```json theme={null}
{
  "id": "vid_01KABCDEF1234567890",
  "object": "generation.task",
  "model": "viduq3-pro-fast",
  "status": "completed",
  "progress": 100,
  "created_at": 1784169600,
  "completed_at": 1784169660,
  "expires_at": 1784256060,
  "result": {
    "type": "video",
    "data": [
      {
        "url": "https://files.toapis.com/videos/vid_01KABCDEF1234567890.mp4",
        "format": "mp4"
      }
    ]
  }
}
```

失敗：

```json theme={null}
{
  "id": "vid_01KABCDEF1234567890",
  "object": "generation.task",
  "model": "viduq3-ad",
  "status": "failed",
  "progress": 100,
  "created_at": 1784169600,
  "completed_at": 1784169620,
  "error": {
    "code": "InvalidParameter",
    "message": "Missing required field 'subjects' in request body"
  }
}
```

## 說明

* 提交後由 ToAPIs 統一輪詢上游任務狀態，再返回標準視頻任務結果。
* `viduq3-pro-fast` 是當前最穩定的接入形態，適合首幀圖生視頻。
* `viduq3-ad`、`viduq3-drama`、`viduq3-mix` 對參考素材要求更嚴格，接入前建議先按上面的示例準備完整素材，不要只傳 prompt。


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