> ## 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 Video Generation

> Generate async video tasks with Vidu Q3 video models.

<Note>
  **Note for users in mainland China:** Please use `https://toapis.cn` as the API endpoint (Base URL). Replace `https://toapis.com` with `https://toapis.cn` in the examples in this document.
</Note>

* Async task API, returns a unified `generation.task` after submission
* Available models: `viduq3-pro-fast`, `viduq3-ad`, `viduq3-drama`, `viduq3-mix`

<Warning>
  `viduq3-ad`, `viduq3-drama`, and `viduq3-mix` are not pure text-to-video models. Do not pass only `prompt`; reference material is required. Otherwise the upstream typically returns `InvalidParameter`, e.g. `Missing required field 'subjects' in request body`.
</Warning>

## Authentication

<ParamField header="Authorization" type="string" required>
  All endpoints require Bearer Token authentication.

  ```http theme={null}
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Supported Models

| Model | Generation type | Recommended input | Recommended resolution |
| - | - | - | - |
| `viduq3-pro-fast` | First-frame image-to-video | 1 reference image | `720P` / `1080P` |
| `viduq3-ad` | Reference video generation | Reference video + reference image | `720P` / `1080P` |
| `viduq3-drama` | Narrative reference video generation | Reference video + reference image | `1080P` |
| `viduq3-mix` | Mixed reference generation | Reference video + reference image | `720P` / `1080P` |

## Request Parameters

<ParamField body="model" type="string" required>
  Only the following 4 public model names are supported:

  * `viduq3-pro-fast`
  * `viduq3-ad`
  * `viduq3-drama`
  * `viduq3-mix`
</ParamField>

<ParamField body="prompt" type="string" required>
  The prompt.

  Even for reference generation models, always provide `prompt` to describe shots, motion, pacing, and style.
</ParamField>

<ParamField body="image_urls" type="string[]">
  List of reference image URLs.

  * `viduq3-pro-fast`: only the first image is used, as the first frame
  * `viduq3-ad` / `viduq3-drama` / `viduq3-mix`: pass one or more subject/style reference images

  Compatible fields:

  * `input_reference`
  * `reference_images`
  * `images`
  * `image`
</ParamField>

<ParamField body="url" type="string">
  Reference video URL.

  Only recommended for `viduq3-ad` / `viduq3-drama` / `viduq3-mix`. Equivalent to passing one primary reference video.
</ParamField>

<ParamField body="video_list" type="array">
  List of reference videos.

  Only used by `viduq3-ad` / `viduq3-drama` / `viduq3-mix`. Each item supports:

  * `video_url`
  * `refer_type` (optional)
  * `keep_original_sound` (optional)
</ParamField>

<ParamField body="duration" type="integer" default={5}>
  Video duration in seconds. Default `5`.
</ParamField>

<ParamField body="resolution" type="string" default="720P">
  Resolution, supports `720P` and `1080P`.

  Recommendations:

  * Prefer `1080P` for `viduq3-drama`
</ParamField>

<ParamField body="audio" type="boolean">
  Whether to generate audio.

  Current server-side defaults:

  * `viduq3-pro-fast`: default `true`
  * `viduq3-ad`: default `true`
  * `viduq3-mix`: default `true`
  * `viduq3-drama`: pass the value explicitly; do not rely on the default
</ParamField>

<ParamField body="watermark" type="boolean" default={false}>
  Whether to add a watermark.
</ParamField>

<ParamField body="seed" type="integer">
  Random seed.
</ParamField>

<ParamField body="metadata" type="object">
  Extended parameters, passed through following the upstream video request structure.

  Common usage:

  * `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` may require structured subject input on the upstream side (e.g. `subjects`). Requests with only a plain text prompt usually fail.
  </Warning>
</ParamField>

## Input Rules

### 1. `viduq3-pro-fast`

* First-frame image-to-video model
* At least 1 image required
* When multiple images are provided, only the first one is used
* Best for "animate a still image" scenarios

### 2. `viduq3-ad` / `viduq3-drama` / `viduq3-mix`

* Reference video generation models; plain-prompt calls are not recommended
* Recommended minimum input:
  * 1 reference video: `url` or `video_list`
  * 1 reference image: `image_urls` or a compatible image field
* If subjects/reference material is missing, the upstream may return:
  * `InvalidParameter`
  * `Missing required field 'subjects' in request body`

## Request Examples

### `viduq3-pro-fast` first-frame image-to-video

```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` reference video generation

```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` narrative reference generation

```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` mixed reference generation

```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
  }'
```

## Success Response

```json theme={null}
{
  "id": "vid_01KABCDEF1234567890",
  "object": "generation.task",
  "model": "viduq3-pro-fast",
  "status": "queued",
  "progress": 0,
  "created_at": 1784169600
}
```

## Query Task

`GET /v1/videos/generations/{task_id}`

In progress:

```json theme={null}
{
  "id": "vid_01KABCDEF1234567890",
  "object": "generation.task",
  "model": "viduq3-pro-fast",
  "status": "in_progress",
  "progress": 60,
  "created_at": 1784169600
}
```

Completed:

```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"
      }
    ]
  }
}
```

Failed:

```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"
  }
}
```

## Notes

* After submission, ToAPIs polls the upstream task status and returns standard video task results.
* `viduq3-pro-fast` is the most stable integration form today, suitable for first-frame image-to-video.
* `viduq3-ad`, `viduq3-drama`, and `viduq3-mix` have stricter requirements on reference material. Prepare complete material per the examples above before integrating; do not pass only a prompt.


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