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

# Qwen 2 Image

> Qwen 2 text-to-image API with standard and pro generation modes

## Overview

Qwen 2 Image is an asynchronous text-to-image API. It supports standard and pro generation modes, multiple aspect ratios, prompt extension, optional negative prompts, and up to 6 images per task.

| Capability       | Value                                     |
| ---------------- | ----------------------------------------- |
| Model ID         | `qwen-2-image`                            |
| Modes            | `text-to-image`, `text-to-image-pro`      |
| Default mode     | `text-to-image`                           |
| Prompt length    | 1-800 characters                          |
| Negative prompt  | Optional, up to 500 characters            |
| Images per task  | `num_images` defaults to `1`; range `1-6` |
| Aspect ratios    | `1:1`, `3:4`, `4:3`, `9:16`, `16:9`       |
| Prompt extension | `prompt_extend`, default `true`           |
| Watermark        | `watermark`, default `false`              |

## Endpoint and authentication

Base URL:

```text theme={null}
https://api.apixo.ai/api/v1
```

| Method | Endpoint                                   | Purpose                               |
| ------ | ------------------------------------------ | ------------------------------------- |
| `POST` | `/generateTask/qwen-2-image`               | Submit a text-to-image task           |
| `GET`  | `/statusTask/qwen-2-image?taskId={taskId}` | Poll task status and retrieve results |

All requests require your APIXO API key:

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

Submit requests also require:

```http theme={null}
Content-Type: application/json
```

## Copy-paste async quickstart

```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/qwen-2-image" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "async",
    "input": {
      "mode": "text-to-image-pro",
      "prompt": "a premium poster for a bookstore event, crisp typography, elegant layout",
      "negative_prompt": "blurry text, distorted letters, low resolution",
      "aspect_ratio": "16:9",
      "num_images": 2,
      "prompt_extend": true,
      "watermark": false
    }
  }'
```

Successful response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678"
  }
}
```

Save the `taskId`; you need it to poll for the final result.

## Poll for result

```bash theme={null}
curl -X GET "https://api.apixo.ai/api/v1/statusTask/qwen-2-image?taskId=task_12345678" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Success response:

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "success",
    "resultJson": "{\"resultUrls\":[\"https://file.apixo.ai/image.png\"]}",
    "createTime": 1767965610929,
    "completeTime": 1767965652317,
    "costTime": 41388
  }
}
```

Parse `resultJson` after `state` becomes `success`:

```javascript theme={null}
const payload = JSON.parse(data.resultJson);
const imageUrls = payload.resultUrls;
```

## Request body

### Standard text-to-image

```json theme={null}
{
  "request_type": "async",
  "input": {
    "mode": "text-to-image",
    "prompt": "a minimalist product poster for wireless earbuds, clean layout",
    "aspect_ratio": "4:3",
    "num_images": 1,
    "prompt_extend": true,
    "watermark": false
  }
}
```

### Pro text-to-image

```json theme={null}
{
  "request_type": "callback",
  "callback_url": "https://your-server.com/webhooks/apixo",
  "input": {
    "mode": "text-to-image-pro",
    "prompt": "a high-end brand key visual with readable headline text and premium lighting",
    "negative_prompt": "blurred typography, misspelled words, jagged edges",
    "aspect_ratio": "9:16",
    "num_images": 2,
    "seed": 123456
  }
}
```

## Parameters

<ParamField body="request_type" type="string" required default="async">
  Result delivery mode. Use `async` for polling with `statusTask`, or `callback` for webhook delivery.
</ParamField>

<ParamField body="callback_url" type="string">
  Required when `request_type` is `callback`. Must be a callback URL that can receive the final task payload. See [Webhooks](/api-reference/webhooks).
</ParamField>

<ParamField body="input" type="object" required>
  Qwen 2 Image input parameters.

  <Expandable title="properties">
    <ParamField body="mode" type="string" default="text-to-image">
      Generation mode. Supported values: `text-to-image`, `text-to-image-pro`. If omitted, the backend defaults to `text-to-image`.
    </ParamField>

    <ParamField body="prompt" type="string" required>
      Prompt text. Must be a non-empty string and cannot exceed `800` characters.
    </ParamField>

    <ParamField body="negative_prompt" type="string">
      Optional negative prompt. Maximum length is `500` characters.
    </ParamField>

    <ParamField body="aspect_ratio" type="string" default="1:1">
      Output aspect ratio. Supported values: `1:1`, `3:4`, `4:3`, `9:16`, `16:9`.
    </ParamField>

    <ParamField body="num_images" type="integer" default="1">
      Number of output images. Accepts integer or numeric string input. Supported range: `1-6`.
    </ParamField>

    <ParamField body="prompt_extend" type="boolean" default="true">
      Whether to enable prompt extension.
    </ParamField>

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

    <ParamField body="seed" type="integer">
      Optional random seed. Supported range: `0-2147483647`.
    </ParamField>
  </Expandable>
</ParamField>

## Response format

### Submit task response

`POST /generateTask/qwen-2-image` returns a task ID when the task is accepted:

<ResponseField name="code" type="integer">
  API status code. `200` means the task was accepted.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message.
</ResponseField>

<ResponseField name="data.taskId" type="string">
  Unique task identifier used with the status endpoint.
</ResponseField>

### Status response fields

<ResponseField name="taskId" type="string">
  Unique task identifier.
</ResponseField>

<ResponseField name="state" type="string">
  Current task state: `pending`, `processing`, `success`, or `failed`.
</ResponseField>

<ResponseField name="resultJson" type="string">
  JSON string containing generated image URLs in `resultUrls`. Present when `state` is `success`.
</ResponseField>

<ResponseField name="failCode" type="string">
  Machine-readable failure code. Present when `state` is `failed`.
</ResponseField>

<ResponseField name="failMsg" type="string">
  Human-readable failure message. Present when `state` is `failed`.
</ResponseField>

<ResponseField name="createTime" type="integer">
  Task creation timestamp in Unix milliseconds.
</ResponseField>

<ResponseField name="completeTime" type="integer">
  Task completion timestamp in Unix milliseconds. Present after completion.
</ResponseField>

<ResponseField name="costTime" type="integer">
  Processing duration in milliseconds when available.
</ResponseField>

## Webhook callback mode

Use callback mode when your backend should receive the final result automatically instead of polling.

```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/qwen-2-image" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "callback",
    "callback_url": "https://your-server.com/webhooks/apixo",
    "input": {
      "mode": "text-to-image-pro",
      "prompt": "a premium campaign poster with readable headline text",
      "aspect_ratio": "16:9",
      "num_images": 1
    }
  }'
```

See [Webhooks](/api-reference/webhooks) for delivery requirements and retry behavior.

## Billing

Qwen 2 Image is billed per generated image.

| Mode                | APIXO price     |
| ------------------- | --------------- |
| `text-to-image`     | `$0.03 / image` |
| `text-to-image-pro` | `$0.07 / image` |

Billing behavior:

```text theme={null}
precharge = requested_num_images * unit_price_for_mode
final_charge = successful_images * unit_price_for_mode
refund = precharge - final_charge (if partial failure)
```

For current route and market comparison pricing, see [Pricing](https://apixo.ai/pricing).

## Latency and polling

Qwen 2 Image tasks are asynchronous. Actual latency varies by prompt complexity, requested image count, and queue load.

| Use case                    | Recommended first poll      | Poll interval |
| --------------------------- | --------------------------- | ------------- |
| Standard generation         | 10s after task creation     | 5s-10s        |
| Pro mode or multiple images | 10s-15s after task creation | 5s-10s        |

<Tip>
  For production queues or batches, use callback mode to avoid frequent polling.
</Tip>

Rate limits and concurrency can vary by account, API key, and route. If you receive `429`, slow down requests and retry with backoff. For account-level details, see [System APIs](/api-reference/system).

## Errors and troubleshooting

### HTTP errors

| Code  | Meaning                                        | What to do                                       |
| ----- | ---------------------------------------------- | ------------------------------------------------ |
| `400` | Invalid request body, parameter type, or value | Fix the request before retrying                  |
| `401` | Missing or invalid API key                     | Check the `Authorization` header                 |
| `402` | Insufficient balance or quota                  | Add balance or switch account/key                |
| `403` | Key or route cannot access the model           | Check permissions and route strategy             |
| `404` | Task not found                                 | Verify the `taskId` and model ID                 |
| `429` | Rate limit or concurrency limit reached        | Retry with exponential backoff                   |
| `500` | Server or unmapped model error                 | Retry with backoff                               |
| `502` | Model service error                            | Retry with backoff                               |
| `504` | Model service timeout                          | Retry or use callback mode for long-running jobs |

### Request validation

| Condition                              | Backend behavior                                                         |
| -------------------------------------- | ------------------------------------------------------------------------ |
| Invalid `mode`                         | Returns `Invalid mode type. Supported: text-to-image, text-to-image-pro` |
| Missing or empty `prompt`              | Returns a missing-parameter or validation error                          |
| Prompt exceeds `800` characters        | Returns a length error                                                   |
| Invalid `num_images`                   | Returns `The parameter {{num_images}} must be between 1 and 6.`          |
| Invalid `aspect_ratio`                 | Returns the supported aspect-ratio list                                  |
| Invalid `prompt_extend` or `watermark` | Returns a boolean type error                                             |
| Invalid `seed`                         | Returns the supported seed range                                         |

See [Error Codes](/api-reference/errors) for the full error reference.

## Related links

* [Generation API Overview](/models)
* [Generate Task](/api-reference/generate-task)
* [Status Task](/api-reference/status-task)
* [Webhooks](/api-reference/webhooks)
* [Error Codes](/api-reference/errors)
* [Parameter Specification](/api-reference/parameters)
* [Pricing](https://apixo.ai/pricing)