> ## 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 系列模型生成視頻，支持文生視頻、圖生視頻、首尾幀、參考生成和 Subjects 生成

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

* 異步任務接口，提交後返回任務 ID
* 支持模型：`viduq3-pro`、`viduq3-turbo`、`viduq3`
* `viduq3-pro`：高質量模型，支持音視頻同步和分鏡視頻生成
* `viduq3-turbo`：快速模型，支持智能場景切換，生成速度最快，性價比最高
* `viduq3`：多機位一致性最優，支持智能鏡頭切換和多參考圖生成

> [!WARNING]
>
> 請傳入公網可訪問的圖片 URL。不要在 `image_urls` 中直接傳 base64 圖片數據；本地圖片請先使用 [上傳圖片接口](https://docs.toapis.com/docs/zh-Hant/api-reference/uploads/images.md) 獲取 URL。

## 認證

**Authorization** `string` *required*

所有接口均需要使用 Bearer Token 認證。

```
Authorization: Bearer YOUR_API_KEY
```

## 請求參數

**model** `string` *required*

Vidu Q3 模型名稱。

可選值：

* `viduq3-pro` - 高質量模型，支持音視頻同步和分鏡視頻生成
* `viduq3-turbo` - 快速模型，支持智能場景切換，生成速度最快
* `viduq3` - 多機位一致性最優，適用於多參考圖/Subjects 生成

**prompt** `string` *required*

視頻提示詞，最大 **5000 字符**。

描述主體、動作、場景、鏡頭和風格。使用 subjects 時可通過 `@name` 引用主體。

示例：`"一隻貓咪在彈鋼琴，鏡頭緩緩推近，電影質感"`

**duration** `integer` (default: 5)

視頻時長，單位秒。

* `viduq3-pro` / `viduq3-turbo`：`1` 到 `16`
* `viduq3`：`3` 到 `16`

**resolution** `string` (default: 720p)

視頻分辨率。

可選值：

* `540p`
* `720p`
* `1080p`

**aspect\_ratio** `string`

視頻寬高比。

常用值：`16:9`、`9:16`、`1:1`

Q3 系列模型支持任意寬高比。傳入 `image_urls` 時，寬高比通常由參考圖片決定。

**image\_urls** `string[]`

參考圖片 URL 數組。

* `viduq3-pro` / `viduq3-turbo`
  * 不傳：文生視頻
  * 傳 1 張：圖生視頻，圖片作爲首幀
  * 傳 2 張：首尾幀，第一張爲首幀，第二張爲尾幀
* `viduq3`
  * 必填，最多 7 張參考圖片

示例：`["https://example.com/reference.jpg"]`

**audio** `boolean`

是否啓用音視頻輸出。

* 所有 Q3 模型默認 `true`

設爲 `true` 時，系統根據提示詞生成語音和背景音效。

**seed** `integer`

隨機種子，用於在相同參數下復現相近結果。

**metadata** `object`

擴展參數，用於傳遞官方 API 支持但未作爲頂層字段暴露的參數。

**顯示 metadata 字段**

**subjects** `array`

主體列表（Subjects 模式，僅 `viduq3` 支持）。每個主體包含 `name` 和 `images` 字段。

* 最多 7 個主體
* 每個主體最多 3 張圖片
* 使用時在 prompt 中通過 `@name` 引用主體

示例：

```json theme={null}
[
  {"name": "cat", "images": ["https://example.com/cat.jpg"]},
  {"name": "dog", "images": ["https://example.com/dog.jpg"]}
]
```

**auto\_subjects** `boolean`

是否啓用智能實體庫能力，默認 `false`。

**voice\_id** `string`

語音 ID，用於指定視頻中的語音角色。系統會自動推薦合適的語音。

**audio\_type** `string`

音頻類型，`audio` 爲 `true` 時有效。

可選值：

* `all` - 音效+人聲（默認）
* `speech_only` - 僅人聲
* `sound-effect_only` - 僅音效

**off\_peak** `boolean`

閒時模式，默認 `false`。

* `true`：閒時生成，消耗更少積分
* 閒時任務將在 48 小時內生成，未完成自動取消並退還積分
* Q3 模型在 `audio=true` 時支持閒時任務

**payload** `string`

透傳參數，不做處理僅傳遞數據，最大 1048576 字符。

**callback\_url** `string`

ToAPIs 最終任務 Webhook。需先設定 Token URL 與密鑰；詳見 [Webhook](https://docs.toapis.com/docs/zh-Hant/api-reference/webhooks/task-webhooks.md)。

## 模型選擇

| 模型 | 適用場景 | 圖片輸入 | 分辨率 | 時長 |
| - | - | - | - | - |
| `viduq3-pro` | 高質量文生/圖生/首尾幀 | 可選，最多 2 張 | `540p` / `720p` / `1080p` | 1-16s |
| `viduq3-turbo` | 快速文生/圖生/首尾幀 | 可選，最多 2 張 | `540p` / `720p` / `1080p` | 1-16s |
| `viduq3` | 多參考圖/Subjects 生成 | 必填，最多 7 張 | `540p` / `720p` / `1080p` | 3-16s |

## 計費區分

Vidu Q3 按模型、分辨率和生成類型計費：

* `viduq3-pro`：高質量檔，價格約爲 turbo 的 2 倍
* `viduq3-turbo`：快速檔，性價比最高
* `viduq3`：多參考圖生成，按參考生成計費

## 響應

**id** `string`

任務 ID，用於查詢任務狀態。

**object** `string`

對象類型，通常爲 `generation.task`。

**model** `string`

本次請求使用的模型名稱。

**status** `string`

任務狀態：`queued`、`in_progress`、`completed` 或 `failed`。

**created\_at** `integer`

任務創建時間戳。

## 示例

### 文生視頻

```json theme={null}
{
  "model": "viduq3-pro",
  "prompt": "一隻貓咪在彈鋼琴，鏡頭緩緩推近，電影質感",
  "duration": 8,
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "audio": true
}
```

### 圖生視頻

```json theme={null}
{
  "model": "viduq3-turbo",
  "prompt": "讓圖片中的人物緩緩轉身並微笑",
  "image_urls": ["https://example.com/portrait.jpg"],
  "duration": 5,
  "resolution": "720p"
}
```

### 首尾幀

```json theme={null}
{
  "model": "viduq3-pro",
  "prompt": "人物從站立自然坐下，動作流暢",
  "image_urls": [
    "https://example.com/first-frame.jpg",
    "https://example.com/last-frame.jpg"
  ],
  "duration": 8,
  "resolution": "720p"
}
```

### 多參考圖生成視頻

```json theme={null}
{
  "model": "viduq3",
  "prompt": "保持參考圖中的角色一致，在未來城市街道中行走",
  "image_urls": [
    "https://example.com/character-front.jpg",
    "https://example.com/character-side.jpg"
  ],
  "duration": 6,
  "resolution": "1080p"
}
```

### Subjects 模式

```json theme={null}
{
  "model": "viduq3",
  "prompt": "@cat 和 @dog 在公園裏奔跑，陽光明媚",
  "image_urls": ["https://example.com/park-bg.jpg"],
  "duration": 8,
  "resolution": "720p",
  "audio": true,
  "metadata": {
    "subjects": [
      {"name": "cat", "images": ["https://example.com/cat.jpg"]},
      {"name": "dog", "images": ["https://example.com/dog.jpg"]}
    ],
    "audio_type": "all"
  }
}
```

> [!NOTE]
>
> 視頻生成爲異步任務。提交後使用 [獲取視頻任務狀態](https://docs.toapis.com/docs/zh-Hant/api-reference/tasks/video-status.md) 查詢進度和結果。

```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": "viduq3-pro",
    "prompt": "一隻貓咪在彈鋼琴，鏡頭緩緩推近，電影質感",
    "duration": 8,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "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": "viduq3-pro",
        "prompt": "一隻貓咪在彈鋼琴，鏡頭緩緩推近，電影質感",
        "duration": 8,
        "resolution": "1080p",
        "aspect_ratio": "16:9",
        "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: "viduq3-pro",
    prompt: "一隻貓咪在彈鋼琴，鏡頭緩緩推近，電影質感",
    duration: 8,
    resolution: "1080p",
    aspect_ratio: "16:9",
    audio: true
  })
});

console.log(await response.json());
```


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