> ## 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` に置き換えてください。
</Note>

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

<Warning>
  公開アクセス可能な画像・音声 URL を指定してください。`image_urls`、`reference_images`、`sounds` に base64 データを直接渡さないでください。ローカルファイルは先に [画像アップロード API](../../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` に画像 URL を 1 枚だけ渡します。画像が先頭フレームになります。
  * **参照モード**：`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/ja/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.