> ## 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/zh-Hant/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.