> ## 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.

# Qwen Image 3.0 Image Generation

> Generate images with qwen-image-3.0 or qwen-image-3.0-pro

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

* Supports `qwen-image-3.0` and `qwen-image-3.0-pro`
* Supports text-to-image, image-to-image, and multi-reference generation
* Accepts up to 3 reference images
* Supports 1K and 2K output resolutions with 7 aspect ratios
* Generates exactly 1 image per request. `n` must be `1`
* Runs asynchronously and returns a task ID for status queries

> [!WARNING]
>
> `image_urls` accepts publicly accessible image URLs only. Base64 Data URIs are not supported. Use the [Upload Image API](https://docs.toapis.com/docs/en/api-reference/uploads/images.md) first for local files.

## Supported models

| Model | Text-to-image | Image-to-image | Reference limit | Output |
| - | - | - | - | - |
| `qwen-image-3.0` | Yes | Yes | 3 images | Exactly 1 |
| `qwen-image-3.0-pro` | Yes | Yes | 3 images | Exactly 1 |

## Authorizations

**Authorization** `string` *required*

All endpoints require Bearer Token authentication.

Get an API key from the [API Key Management Page](https://toapis.com/console/token) and send it in the request header:

```text theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Body

**model** `string` *required*

Model name. The only supported values are:

* `qwen-image-3.0`
* `qwen-image-3.0-pro`

**prompt** `string` *required*

Text description or editing instruction. The value cannot be empty.

**size** `string`

Output aspect ratio. Recommended values:

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

Explicit pixel sizes are also accepted as `WIDTH*HEIGHT` or `WIDTHxHEIGHT`. The total pixel area must be between `512*512` and `2048*2048`, and the aspect ratio must be between `1:8` and `8:1`.

If omitted, the model chooses the output size.

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

Resolution tier used when `size` is an aspect ratio:

* `1K` - Default
* `2K`

`metadata.resolution` is also accepted, but the top-level field is recommended.

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

Number of images to generate. This is fixed at `1`.

> [!WARNING]
>
> Values greater than `1` return `400 invalid_request`.

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

Reference image URLs for image-to-image, editing, or multi-reference generation.

* Maximum 3 images
* URLs only; base64 Data URIs are not supported
* Use the [Upload Image API](https://docs.toapis.com/docs/en/api-reference/uploads/images.md) for local files

**client\_business\_id** `string`

Your order ID, transaction ID, or other business identifier. When provided, the same image task endpoint can be queried with this ID.

**metadata** `object`

Qwen Image advanced parameters.

**metadata properties**

**metadata.prompt\_extend** `boolean` (default: true)

Whether to automatically optimize and expand the prompt.

**metadata.prompt\_extend\_mode** `string`

Prompt expansion mode:

* `direct` - Direct expansion
* `agent` - Agent expansion, text-to-image only

When `image_urls` is present, `agent` is automatically changed to `direct`.

**metadata.negative\_prompt** `string`

Negative prompt describing content to avoid.

**metadata.seed** `integer`

Random seed. The same seed can help produce similar results, but does not guarantee identical output.

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

Whether to add a watermark.

## Resolution and pixel mapping

When `size` is an aspect ratio, ToAPIs maps it to the following pixel dimensions. Both models use the same mapping.

| Aspect ratio | 1K | 2K |
| - | - | - |
| `1:1` | 1024×1024 | 2048×2048 |
| `4:3` | 1152×864 | 1600×1200 |
| `3:4` | 864×1152 | 1200×1600 |
| `16:9` | 1280×720 | 1920×1080 |
| `9:16` | 720×1280 | 1080×1920 |
| `3:2` | 1152×768 | 1728×1152 |
| `2:3` | 768×1152 | 1152×1728 |

## Response

**id** `string`

Unique task identifier for status queries.

**object** `string`

Object type, always `generation.task`.

**model** `string`

Model used for the request.

**status** `string`

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

**progress** `integer`

Progress percentage from 0 to 100.

**created\_at** `integer`

Task creation time as a Unix timestamp.

## Request examples

```bash cURL (Text-to-Image) 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": "qwen-image-3.0",
    "prompt": "A cinematic fantasy poster of an ancient city above the clouds, golden morning light, with the clear Chinese title 云上长安",
    "size": "16:9",
    "resolution": "2K",
    "n": 1,
    "metadata": {
      "prompt_extend": true,
      "negative_prompt": "blurry, low quality, incorrect text",
      "watermark": false
    }
  }'
```

```bash cURL (Multi-reference) 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": "qwen-image-3.0-pro",
    "prompt": "Keep the person from the first image and the clothing design from the second image. Create a modern magazine cover with detailed facial features and materials.",
    "image_urls": [
      "https://example.com/person.png",
      "https://example.com/outfit.png"
    ],
    "size": "3:4",
    "resolution": "2K",
    "n": 1,
    "metadata": {
      "prompt_extend": true,
      "prompt_extend_mode": "direct",
      "watermark": false
    }
  }'
```

```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": "qwen-image-3.0-pro",
        "prompt": "A premium black-and-gold perfume poster with studio lighting and sharp details",
        "size": "1:1",
        "resolution": "2K",
        "n": 1,
        "metadata": {
            "prompt_extend": True,
            "watermark": False,
        },
    },
)
response.raise_for_status()
task = response.json()
print(task["id"], 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: "qwen-image-3.0",
    prompt: "A cinematic product photo of a transparent mechanical watch",
    size: "4:3",
    resolution: "1K",
    n: 1,
    metadata: {
      prompt_extend: true,
      watermark: false
    }
  })
});

if (!response.ok) {
  throw new Error(await response.text());
}

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

## Submission response

```json 200 theme={null}
{
  "id": "task_img_abc123def456",
  "object": "generation.task",
  "model": "qwen-image-3.0-pro",
  "status": "queued",
  "progress": 0,
  "created_at": 1787270400
}
```

## Query the task

```bash theme={null}
curl --request GET \
  --url https://toapis.com/v1/images/generations/task_img_abc123def456 \
  --header 'Authorization: Bearer <YOUR_API_KEY>'
```

See [Get Image Task Status](https://docs.toapis.com/docs/en/api-reference/tasks/image-status.md) for response fields and polling guidance.

### Completed response

```json theme={null}
{
  "id": "task_img_abc123def456",
  "object": "generation.task",
  "model": "qwen-image-3.0-pro",
  "status": "completed",
  "progress": 100,
  "created_at": 1787270400,
  "completed_at": 1787270458,
  "expires_at": 1787356858,
  "result": {
    "type": "image",
    "data": [
      {
        "url": "https://files.toapis.com/generated/qwen-image-result.png"
      }
    ]
  }
}
```

> [!WARNING]
>
> Generated image URLs expire after 24 hours. Download or copy the image before `expires_at`.

## Billing

* Successful output: `$0.03` per request
* Reference image input: `$0.003` per image
* There is no free reference-image allowance
* `qwen-image-3.0` and `qwen-image-3.0-pro` currently use the same billing rules


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