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

* 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](../../uploads/images) first for local files.
</Warning>

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

<ParamField header="Authorization" type="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
  ```
</ParamField>

## Body

<ParamField body="model" type="string" required>
  Model name. The only supported values are:

  * `qwen-image-3.0`
  * `qwen-image-3.0-pro`
</ParamField>

<ParamField body="prompt" type="string" required>
  Text description or editing instruction. The value cannot be empty.
</ParamField>

<ParamField body="size" type="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.
</ParamField>

<ParamField body="resolution" type="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.
</ParamField>

<ParamField body="n" type="integer" default={1}>
  Number of images to generate. This is fixed at `1`.

  <Warning>
    Values greater than `1` return `400 invalid_request`.
  </Warning>
</ParamField>

<ParamField body="image_urls" type="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](../../uploads/images) for local files
</ParamField>

<ParamField body="client_business_id" type="string">
  Your order ID, transaction ID, or other business identifier. When provided, the same image task endpoint can be queried with this ID.
</ParamField>

<ParamField body="metadata" type="object">
  Qwen Image advanced parameters.

  <Expandable title="metadata properties">
    <ParamField body="metadata.prompt_extend" type="boolean" default={true}>
      Whether to automatically optimize and expand the prompt.
    </ParamField>

    <ParamField body="metadata.prompt_extend_mode" type="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`.
    </ParamField>

    <ParamField body="metadata.negative_prompt" type="string">
      Negative prompt describing content to avoid.
    </ParamField>

    <ParamField body="metadata.seed" type="integer">
      Random seed. The same seed can help produce similar results, but does not guarantee identical output.
    </ParamField>

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

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

<ResponseField name="id" type="string">
  Unique task identifier for status queries.
</ResponseField>

<ResponseField name="object" type="string">
  Object type, always `generation.task`.
</ResponseField>

<ResponseField name="model" type="string">
  Model used for the request.
</ResponseField>

<ResponseField name="status" type="string">
  Task status: `queued`, `in_progress`, `completed`, or `failed`.
</ResponseField>

<ResponseField name="progress" type="integer">
  Progress percentage from 0 to 100.
</ResponseField>

<ResponseField name="created_at" type="integer">
  Task creation time as a Unix timestamp.
</ResponseField>

## Request examples

<RequestExample>
  ```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);
  ```
</RequestExample>

## 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](../../tasks/image-status) 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`.
</Warning>

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