> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Qwen Image 3.0 Image Generation

>  - Asynchronous processing mode, returns a task ID for subsequent queries
- Supports text-to-image and image-to-image (1-3 reference images for editing)
- Supports 1K / 2K resolution, up to 6 images per request
- Standard and Pro variants (Pro is stronger for dense layout and text) 

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.apimart.ai/v1/images/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "qwen-image-3.0",
      "prompt": "A cafe poster with the title Autumn Limited, warm tones, refined layout",
      "size": "16:9",
      "resolution": "1K"
    }'
  ```

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

  url = "https://api.apimart.ai/v1/images/generations"

  payload = {
      "model": "qwen-image-3.0",
      "prompt": "A cafe poster with the title Autumn Limited, warm tones, refined layout",
      "size": "16:9",
      "resolution": "1K",
  }

  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json",
  }

  response = requests.post(url, json=payload, headers=headers)

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = "https://api.apimart.ai/v1/images/generations";

  const payload = {
    model: "qwen-image-3.0",
    prompt: "A cafe poster with the title Autumn Limited, warm tones, refined layout",
    size: "16:9",
    resolution: "1K",
  };

  const headers = {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json",
  };

  fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(payload),
  })
    .then((response) => response.json())
    .then((data) => console.log(data))
    .catch((error) => console.error("Error:", error));
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "data": [
      {
        "status": "submitted",
        "task_id": "task_01JGXYZ1234567890ABCDEF"
      }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": 400,
      "message": "Invalid request parameters",
      "type": "invalid_request_error"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": 401,
      "message": "Authentication failed, please check your API key",
      "type": "authentication_error"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "code": 402,
      "message": "Insufficient account balance, please top up and try again",
      "type": "payment_required"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": 429,
      "message": "Too many requests, please try again later",
      "type": "rate_limit_error"
    }
  }
  ```
</ResponseExample>

## Supported Models

| Model                | Description                                                                      | Max images | Resolution |
| -------------------- | -------------------------------------------------------------------------------- | ---------- | ---------- |
| `qwen-image-3.0`     | Clear instruction following, stable text rendering; better value for general use | 6          | 1K / 2K    |
| `qwen-image-3.0-pro` | Richer content; best for newspapers, storyboards, menus, exams, dense layout     | 6          | 1K / 2K    |

<Tip>
  Prefer `-pro` for dense text/layout. Use `qwen-image-3.0` for general images. Prompt max \~**4.5k tokens**. Model names are not interchangeable with the 2.0 series.
</Tip>

## Authorizations

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

  Get your API Key from the [API Key Management Page](https://apimart.ai/keys):

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Body

<ParamField body="model" type="string" required>
  Model name

  * `qwen-image-3.0` - Standard
  * `qwen-image-3.0-pro` - Pro (dense text / layout)
</ParamField>

<ParamField body="prompt" type="string" required>
  Text description for image generation, max \~**4.5k tokens**
</ParamField>

<ParamField body="image_urls" type="string[]">
  Reference image URL array (image-to-image / editing), **1-3 images**

  * Public `http(s)://` URL or `data:image/png;base64,...` (base64 is re-uploaded first)
  * Formats: JPG / JPEG / PNG / BMP / TIFF / WEBP / GIF
  * Per file ≤ 10MB; width/height recommended 384-2048 px
</ParamField>

<ParamField body="resolution" type="string" default="1K">
  Resolution tier (affects billing tier)

  * `1K` (default; lowercase accepted)
  * `2K`

  You may skip the tier and pass pixels in `size` (e.g. `1600x900`). With raw pixels, area **> 2.25M pixels** bills as 2K.
</ParamField>

<ParamField body="size" type="string" default="1:1">
  Aspect ratio, or explicit pixel size

  Supported ratios:

  * `1:1` (default)
  * `4:3` / `3:4`
  * `16:9` / `9:16`
  * `3:2` / `2:3`

  Also accepts `16x9` style, or pixels like `1024x1024`. For custom pixels, **each edge** (width and height) must be **512–2048**, aspect ratio 1:8 \~ 8:1.

  If neither `size` nor `resolution` is set, output is fixed at **1024×1024**.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Number of images, **1-6**. Values above 6 are clamped to 6.
</ParamField>

<ParamField body="negative_prompt" type="string">
  Negative prompt: content to avoid
</ParamField>

<ParamField body="prompt_extend" type="boolean" default="false">
  Intelligent prompt rewriting

  Defaults to **off** for predictable results. Set to `true` to enable intelligent rewriting.
</ParamField>

<ParamField body="prompt_extend_mode" type="string">
  Rewrite mode (3.0 series only; requires `prompt_extend: true`)

  * `direct` - works for text-to-image and image-to-image
  * `agent` - **text-to-image only**, more aggressive rewrite

  Invalid values are ignored.
</ParamField>

## Size Reference Table

Combine `resolution` (tier) + `size` (ratio):

| Resolution | 1:1       | 4:3       | 3:4       | 16:9      | 9:16      | 3:2       | 2:3       |
| ---------- | --------- | --------- | --------- | --------- | --------- | --------- | --------- |
| **1K**     | 1024×1024 | 1152×864  | 864×1152  | 1280×720  | 720×1280  | 1248×832  | 832×1248  |
| **2K**     | 2048×2048 | 2048×1536 | 1536×2048 | 2048×1152 | 1152×2048 | 2048×1360 | 1360×2048 |

## Use Cases

### Text-to-image (multiple)

```json theme={null}
{
  "model": "qwen-image-3.0",
  "prompt": "Flat illustration of a city skyline at dusk, warm orange tones",
  "size": "16:9",
  "resolution": "1K",
  "n": 4
}
```

### Dense layout with rewrite

```json theme={null}
{
  "model": "qwen-image-3.0-pro",
  "prompt": "A Western restaurant menu with appetizers, mains, and desserts columns, five dishes each with prices, serif font, cream background",
  "size": "3:4",
  "resolution": "2K",
  "prompt_extend": true,
  "prompt_extend_mode": "agent"
}
```

### Image-to-image (edit)

```json theme={null}
{
  "model": "qwen-image-3.0-pro",
  "prompt": "Change the sign text to Open, keep everything else the same",
  "image_urls": ["https://example.com/shop.jpg"],
  "size": "1:1"
}
```

### Negative prompt

```json theme={null}
{
  "model": "qwen-image-3.0",
  "prompt": "Photorealistic mountain cabin in morning mist",
  "negative_prompt": "text, watermark, people, low resolution",
  "size": "3:2"
}
```

## Limits

| Item              | Limit                                                |
| ----------------- | ---------------------------------------------------- |
| Prompt            | ≤ 4.5k tokens                                        |
| Output size       | Custom pixels: each edge 512–2048; aspect 1:8 \~ 8:1 |
| Image count       | 1-6 (excess clamped)                                 |
| Reference images  | 1-3                                                  |
| Reference formats | JPG / JPEG / PNG / BMP / TIFF / WEBP / GIF           |
| Reference size    | ≤ 10MB; width/height recommended 384-2048 px         |

## Response

<ResponseField name="code" type="integer">
  Status code; 200 on success
</ResponseField>

<ResponseField name="data" type="array">
  Response data array

  <Expandable title="Properties">
    <ResponseField name="status" type="string">
      Task status; `submitted` on create
    </ResponseField>

    <ResponseField name="task_id" type="string">
      Task ID for polling results
    </ResponseField>
  </Expandable>
</ResponseField>

## Differences from 2.0

|                      | 2.0 series    | 3.0 series                  |
| -------------------- | ------------- | --------------------------- |
| Prompt length        | Shorter       | \~4.5k tokens               |
| `prompt_extend_mode` | Not supported | `direct` / `agent`          |
| Resolution           | 1K / 2K       | 1K / 2K (Pro 2K costs more) |
| Reference images     | Supported     | 1-3 images                  |

## Notes

1. **Async**: Submit returns a `task_id`. Poll [Get Task Status](/en/api-reference/tasks/status) every **3\~5 seconds**; client timeout \~**3 minutes** (2K + multi-image is slower).
2. **Storage**: Generated images are mirrored to the platform CDN and remain available long-term.
3. **Billing**: Per delivered image × resolution tier by **actual pixel area** (> 2.25M pixels = 2K). `qwen-image-3.0` charges the same for 1K/2K; `-pro` 2K is 2× 1K. Failures are fully refunded; reference images are free.
4. **Errors**: Custom `size` edge outside 512–2048, invalid ratio, `agent` on image-to-image, unreachable/oversized references → 400; rate limit → 429.

<Note>
  **Query results**

  Use [Get Task Status](/en/api-reference/tasks/status) for progress and `result.images`.
</Note>