> ## 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 動画生成

> Generate videos with Vidu Q3 models, including text-to-video, image-to-video, first-last frame, reference-to-video and subjects generation

> [!NOTE]
>
> **中国本土のユーザー向け：** 中国本土のユーザーは `https://toapis.cn` を API エンドポイント（Base URL）としてご利用ください。本ドキュメント内の例では `https://toapis.com` を `https://toapis.cn` に置き換えてください。

* Async task API, returns a task ID after submission
* Supported models: `viduq3-pro`, `viduq3-turbo`, `viduq3`
* `viduq3-pro`: High quality model, supports audio-video sync and storyboard generation
* `viduq3-turbo`: Fast model, intelligent scene switching, fastest generation, best cost-effectiveness
* `viduq3`: Best multi-camera consistency, intelligent camera switching, multi-reference generation

> [!WARNING]
>
> Use publicly accessible image URLs. Do not pass base64 image data in `image_urls`; upload local images with the [Upload 画像API](https://docs.toapis.com/docs/ja/api-reference/uploads/images.md) first.

## Authorization

**Authorization** `string` *required*

All endpoints require Bearer Token authentication.

```
Authorization: Bearer YOUR_API_KEY
```

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

**model** `string` *required*

Vidu Q3 model name.

Options:

* `viduq3-pro` - high quality, supports audio-video sync and storyboard generation
* `viduq3-turbo` - fastest generation, intelligent scene switching
* `viduq3` - best multi-camera consistency, for multi-reference/subjects generation

**prompt** `string` *required*

Text prompt, maximum **5000 characters**.

Describes subject, action, scene, camera movement, and style. When using subjects, reference them via `@name` in the prompt.

Example: `"A cat playing piano, camera slowly zooms in, cinematic quality"`

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

Video duration in seconds.

* `viduq3-pro` / `viduq3-turbo`: `1` to `16`
* `viduq3`: `3` to `16`

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

Video resolution.

Options:

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

**aspect\_ratio** `string`

Video aspect ratio.

Common values: `16:9`, `9:16`, `1:1`

Q3 models support any aspect ratio. When `image_urls` is provided, the output ratio is usually determined by the reference image.

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

Reference image URL array.

* `viduq3-pro` / `viduq3-turbo`
  * Omitted: text-to-video
  * 1 image: image-to-video, image as first frame
  * 2 images: first-last frame
* `viduq3`
  * 必須, up to 7 reference images

Example: `["https://example.com/reference.jpg"]`

**audio** `boolean`

Whether to enable audio-video output.

* All Q3 models default to `true`

When `true`, the system generates speech and sound effects based on the prompt.

**seed** `integer`

Random seed for more reproducible results with the same parameters.

**metadata** `object`

Extended parameters for fields supported by the upstream API but not exposed as top-level fields.

**Show metadata fields**

**subjects** `array`

Subject list (Subjects mode, `viduq3` only). Each subject contains `name` and `images` fields.

* Up to 7 subjects
* Up to 3 images per subject
* Reference subjects via `@name` in the prompt

Example:

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

**auto\_subjects** `boolean`

Whether to use intelligent entity library, defaults to `false`.

**voice\_id** `string`

Voice ID for specifying the voice character in the video.

**audio\_type** `string`

Audio type, effective when `audio` is `true`.

Options:

* `all` - sound effects + speech (default)
* `speech_only` - speech only
* `sound-effect_only` - sound effects only

**off\_peak** `boolean`

Off-peak mode, defaults to `false`.

* `true`: off-peak generation, consumes fewer credits
* Off-peak tasks will be generated within 48 hours; incomplete tasks are auto-cancelled with credits refunded
* Q3 models support off-peak when `audio=true`

**payload** `string`

Transparent passthrough parameter, max 1048576 characters.

**callback\_url** `string`

ToAPIs 最終 Task Webhook。Token URL と secret を設定してください。[Webhook](https://docs.toapis.com/docs/ja/api-reference/webhooks/task-webhooks.md)。

## モデル Selection

| モデル | Use Case | Image Input | Resolution | Duration |
| - | - | - | - | - |
| `viduq3-pro` | High quality text/image/first-last frame | 任意, up to 2 images | `540p` / `720p` / `1080p` | 1-16s |
| `viduq3-turbo` | Fast text/image/first-last frame | 任意, up to 2 images | `540p` / `720p` / `1080p` | 1-16s |
| `viduq3` | Multi-reference/Subjects generation | 必須, up to 7 images | `540p` / `720p` / `1080p` | 3-16s |

## Billing Dimensions

Vidu Q3 is billed by model, resolution, and generation type:

* `viduq3-pro`: high quality tier, approximately 2x the price of turbo
* `viduq3-turbo`: fast tier, best cost-effectiveness
* `viduq3`: multi-reference generation, billed at reference generation rate

## レスポンス

**id** `string`

Task ID for querying task status.

**object** `string`

Object type, usually `generation.task`.

**model** `string`

モデル used for the request.

**status** `string`

Task status: `queued`, `in_progress`, `completed`, or `failed`.

**created\_at** `integer`

Task creation timestamp.

## Examples

### Text-to-Video

```json theme={null}
{
  "model": "viduq3-pro",
  "prompt": "A cat playing piano, camera slowly zooms in, cinematic quality",
  "duration": 8,
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "audio": true
}
```

### Image-to-Video

```json theme={null}
{
  "model": "viduq3-turbo",
  "prompt": "The person in the image slowly turns and smiles",
  "image_urls": ["https://example.com/portrait.jpg"],
  "duration": 5,
  "resolution": "720p"
}
```

### First-Last Frame

```json theme={null}
{
  "model": "viduq3-pro",
  "prompt": "The person naturally sits down from standing, smooth motion",
  "image_urls": [
    "https://example.com/first-frame.jpg",
    "https://example.com/last-frame.jpg"
  ],
  "duration": 8,
  "resolution": "720p"
}
```

### Multi-Reference Image Video

```json theme={null}
{
  "model": "viduq3",
  "prompt": "Keep the character consistent from the reference images, walking through a futuristic city street",
  "image_urls": [
    "https://example.com/character-front.jpg",
    "https://example.com/character-side.jpg"
  ],
  "duration": 6,
  "resolution": "1080p"
}
```

### Subjects Mode

```json theme={null}
{
  "model": "viduq3",
  "prompt": "@cat and @dog are running in the park, sunny day",
  "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]
>
> Video generation is asynchronous. Use the [Get Video Task ステータス](https://docs.toapis.com/docs/ja/api-reference/tasks/video-status.md) endpoint to query progress and results.

```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": "A cat playing piano, camera slowly zooms in, cinematic quality",
    "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": "A cat playing piano, camera slowly zooms in, cinematic quality",
        "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: "A cat playing piano, camera slowly zooms in, cinematic quality",
    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.