> ## 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]
>
> **中国本土のユーザーへ：** API エンドポイント（Base URL）には `https://toapis.cn` をご利用ください。本ドキュメントの例にある `https://toapis.com` は `https://toapis.cn` に置き換えてください。

* 非同期タスク API。送信後にタスク ID を返します
* 対応モデル：`viduq4-preview`
* 2 つの生成モード：
  * **先頭フレーム画像から動画**：1 枚の画像を先頭フレームとして使用
  * **参照画像から動画**：複数の参照画像と任意の参照音声

> [!WARNING]
>
> 公開アクセス可能な画像・音声 URL を指定してください。`image_urls`、`reference_images`、`sounds` に base64 データを直接渡さないでください。ローカルファイルは先に [画像アップロード API](https://docs.toapis.com/docs/ja/api-reference/uploads/images.md) で URL を取得してください。

## 認証

**Authorization** `string` *required*

すべてのエンドポイントで Bearer Token 認証が必要です。

```
Authorization: Bearer YOUR_API_KEY
```

## リクエストパラメータ

**model** `string` *required*

モデル名。`viduq4-preview` 固定です。

**prompt** `string` *required*

動画プロンプト。被写体、動き、シーン、カメラワーク、スタイルを記述します。

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

画像 URL の配列。モードは `video_generation_mode` と画像枚数で決まります：

* **先頭フレームモード**（デフォルト）：`image_urls` に画像 URL を 1 枚だけ渡します。画像が先頭フレームになります。
* **参照モード**：`video_generation_mode` を `reference_images_to_video` に設定し、`image_urls`（または `reference_images`）に参照画像を渡します。

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

**video\_generation\_mode** `string`

生成モードセレクター。

オプション：

* `reference_images_to_video` - 複数参照画像による生成。`image_urls` の複数画像を参照画像として扱います

省略時は先頭フレーム画像から動画です。複数画像、`reference_images`、`sounds` を含むリクエストは自動的に参照画像から動画にルーティングされます。

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

動画の長さ（秒）。`3` から `16`。

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

動画の解像度。

オプション：

* `540p`
* `720p`
* `1080p`
* `2K`
* `4K`

**aspect\_ratio** `string`

動画のアスペクト比。参照モードで使用します。

オプション：`16:9`、`9:16`、`4:3`、`3:4`、`1:1`

**audio** `boolean` (default: true)

動画に音声を生成するかどうか。

**watermark** `boolean` (default: false)

生成動画にウォーターマークを付けるかどうか。

**seed** `integer`

ランダムシード。同じパラメータでより再現性の高い結果を得られます。

**metadata** `object`

拡張パラメータ。上流 API がサポートするがトップレベルフィールドとして公開されていない項目を渡します。

**metadata フィールドを表示**

**is\_rec** `boolean`

プロンプトを自動で拡張・最適化するかどうか。省略時の上流デフォルトは `true` です。

**sounds** `string[]`

参照音声 URL の配列（参照画像から動画モードのみ）。最大 3 件。

例：`["https://example.com/voice.mp3"]`

**wm\_position** `integer`

ウォーターマーク位置。`1` から `4`。`watermark` が `true` のとき有効です。

**wm\_url** `string`

カスタムウォーターマーク画像 URL。`watermark` が `true` のとき有効です。

**meta\_data** `string`

カスタムメタデータ識別子。JSON 形式の文字列としてそのまま結果に透過されます。

**callback\_url** `string`

ToAPIs 最終タスク Webhook。先に Token URL と署名シークレットを設定してください。[タスク Webhooks](https://docs.toapis.com/docs/ja/api-reference/webhooks/task-webhooks.md) を参照。

## モード選択

| モード | トリガー方法 | 画像入力 | 音声入力 |
| - | - | - | - |
| 先頭フレーム画像から動画 | `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` - 解像度が高いほど秒単価が上がります

## レスポンス

**id** `string`

タスク ID。タスクステータスの照会に使用します。

**object** `string`

オブジェクトタイプ。通常は `generation.task` です。

**model** `string`

リクエストで使用されたモデル。

**status** `string`

タスクステータス：`queued`、`in_progress`、`completed`、`failed`。

**created\_at** `integer`

タスク作成タイムスタンプ。

## 例

### 先頭フレーム画像から動画

```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]
>
> 動画生成は非同期です。[動画タスクステータスの取得](https://docs.toapis.com/docs/ja/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": "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());
```


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