> ## 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` を API エンドポイント（Base URL）としてご利用ください。本ドキュメント内の例では `https://toapis.com` を `https://toapis.cn` に置き換えてください。
</Note>

* 非同期タスク API。送信後に統一された `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` のみ推奨。メインの参照動画 1 本を渡すのと同じ意味になります。
</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.