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

> Generate images with the Vidu reference-image family and receive a unified generation.task response.

> [!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.

* Unified async image generation API
* Supports the Vidu reference-image family
* Works for text-to-image and reference-image-to-image flows
* Query task status with the returned task ID

## Body

**model** `string` *required*

Supported models:

* `vidu-image`
* `viduq3-fast`
* `viduq2-pro`
* `viduq2-fast`

**prompt** `string` *required*

Text prompt for image generation

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

Reference image URLs, up to 7 images

**size** `string` (default: 1:1)

Aspect ratio. Supported values:

* `1:1`
* `4:3`
* `3:4`
* `16:9`
* `9:16`
* `3:2`
* `2:3`

**metadata.resolution** `string` (default: 1K)

Resolution when `size` is given as a ratio.

Supported values:

* `1K`
* `2K`
* `4K`

`viduq2-fast` only supports `1K`.

**n** `integer` (default: 1)

Only `1` is supported

**seed** `integer`

Random seed

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

Whether to add watermark

## Model Matrix

| Model | Resolution | Ratios |
| - | - | - |
| `vidu-image` | `1K` / `2K` / `4K` | `1:1` / `4:3` / `3:4` / `16:9` / `9:16` / `3:2` / `2:3` |
| `viduq3-fast` | `1K` / `2K` / `4K` | Same as above |
| `viduq2-pro` | `1K` / `2K` / `4K` | Same as above |
| `viduq2-fast` | `1K` only | Same as above |

## Request Example

```bash cURL theme={null}
curl --request POST \
  --url https://toapis.com/v1/images/generations \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "viduq3-fast",
    "prompt": "Create a cinematic product poster while preserving the main object from the reference image.",
    "image_urls": [
      "https://example.com/reference-1.png"
    ],
    "size": "3:2",
    "metadata": {
      "resolution": "2K",
      "watermark": false
    },
    "seed": 42,
    "n": 1
  }'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://toapis.com/v1/images/generations",
    headers={
        "Authorization": "Bearer <YOUR_API_KEY>",
        "Content-Type": "application/json",
    },
    json={
        "model": "viduq3-fast",
        "prompt": "Create a cinematic product poster while preserving the main object from the reference image.",
        "image_urls": [
            "https://example.com/reference-1.png",
        ],
        "size": "3:2",
        "metadata": {
            "resolution": "2K",
            "watermark": False,
        },
        "seed": 42,
        "n": 1,
    },
)

task = response.json()
print(task["id"])
print(task["status"])
```

```javascript JavaScript theme={null}
const response = await fetch('https://toapis.com/v1/images/generations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <YOUR_API_KEY>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'viduq3-fast',
    prompt: 'Create a cinematic product poster while preserving the main object from the reference image.',
    image_urls: [
      'https://example.com/reference-1.png'
    ],
    size: '3:2',
    metadata: {
      resolution: '2K',
      watermark: false
    },
    seed: 42,
    n: 1
  })
});

const task = await response.json();
console.log(task.id);
console.log(task.status);
```

## Response

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

## Notes

* All four models use the same async endpoint: `POST /v1/images/generations`
* Successful results are returned in `result.data[].url`
* `viduq2-fast` is the lightweight tier and stays on `1K` only


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