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

> Qwen image-to-image API for prompt-guided image transformation

## Overview

Qwen Image is an asynchronous image-to-image API. Provide one source image and a prompt, then poll the task until the generated variants are ready.

| Capability      | Value                                      |
| --------------- | ------------------------------------------ |
| Model ID        | `qwen`                                     |
| Mode            | `image-to-image`                           |
| Prompt length   | 1-2000 characters                          |
| Source image    | Exactly 1 public `image_url`               |
| Images per task | `num_images` must be `1`, `2`, `3`, or `4` |
| Aspect ratios   | `1:1`, `4:3`, `3:4`, `9:16`, `16:9`        |
| Speed options   | `none`, `regular`, `high`                  |
| Output formats  | `png`, `jpeg`                              |

## Endpoint and authentication

Base URL:

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

| Method | Endpoint                           | Purpose                               |
| ------ | ---------------------------------- | ------------------------------------- |
| `POST` | `/generateTask/qwen`               | Submit an image-to-image task         |
| `GET`  | `/statusTask/qwen?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" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "async",
    "input": {
      "mode": "image-to-image",
      "prompt": "turn this product photo into a clean studio hero image with soft reflections",
      "image_url": "https://example.com/source.png",
      "num_images": 2,
      "aspect_ratio": "16:9",
      "speed": "regular",
      "output_format": "png"
    }
  }'
```

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?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-1.png\",\"https://file.apixo.ai/image-2.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

```json theme={null}
{
  "request_type": "async",
  "callback_url": "https://your-server.com/webhooks/apixo",
  "input": {
    "mode": "image-to-image",
    "prompt": "transform into a warm sunrise scene with cinematic lighting",
    "image_url": "https://example.com/source.jpg",
    "num_images": 4,
    "aspect_ratio": "16:9",
    "speed": "regular",
    "num_inference_steps": 30,
    "guidance_scale": 8,
    "output_format": "jpeg",
    "negative_prompt": "low quality, blurry, distorted",
    "seed": 42
  }
}
```

## 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 Image input parameters.

  <Expandable title="properties">
    <ParamField body="mode" type="string" default="image-to-image">
      Generation mode. The only supported value is `image-to-image`. If omitted, the backend resolves this single supported mode automatically.
    </ParamField>

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

    <ParamField body="image_url" type="string" required>
      Source image URL. Must be a directly fetchable public image URL.
    </ParamField>

    <ParamField body="num_images" type="integer" required>
      Number of requested output images. Supported values: `1`, `2`, `3`, `4`.
    </ParamField>

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

    <ParamField body="speed" type="string" default="none">
      Optional generation speed. Supported values: `none`, `regular`, `high`.
    </ParamField>

    <ParamField body="num_inference_steps" type="integer" default="25">
      Optional inference step count. Supported range: `2-49`.
    </ParamField>

    <ParamField body="guidance_scale" type="integer" default="4">
      Optional guidance scale. Supported range: `0-20`.
    </ParamField>

    <ParamField body="output_format" type="string" default="png">
      Output image format. Supported values: `png`, `jpeg`.
    </ParamField>

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

    <ParamField body="seed" type="integer">
      Optional random seed.
    </ParamField>

    <ParamField body="sync_mode" type="boolean">
      Optional sync flag for compatibility. For normal APIXO task usage, keep the default asynchronous workflow.
    </ParamField>
  </Expandable>
</ParamField>

## Response format

### Submit task response

`POST /generateTask/qwen` 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" \
  -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": "image-to-image",
      "prompt": "make this image look like a premium editorial campaign",
      "image_url": "https://example.com/source.jpg",
      "num_images": 1
    }
  }'
```

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

## Billing

Qwen Image is billed by the requested `num_images` value.

| Requested images | APIXO price           |
| ---------------- | --------------------- |
| `1`              | `$0.025 / generation` |
| `2`              | `$0.050 / generation` |
| `3`              | `$0.075 / generation` |
| `4`              | `$0.100 / generation` |

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

## Latency and polling

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

| Use case                                       | Recommended first poll      | Poll interval                 |
| ---------------------------------------------- | --------------------------- | ----------------------------- |
| Normal image-to-image task                     | 10s-15s after task creation | 5s-10s                        |
| Multiple outputs or high-concurrency workloads | Prefer callback mode        | If polling, use 10s or longer |

<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                                                              |
| --------------------------- | ----------------------------------------------------------------------------- |
| Missing `input`             | Returns `The required parameter {{input}} is missing.`                        |
| Missing `prompt`            | Returns `The required parameter {{prompt}} is missing.`                       |
| Prompt is empty or too long | Returns a validation or length error                                          |
| Missing `image_url`         | Returns `The required parameter {{image_url}} is missing.`                    |
| Invalid `num_images`        | Returns `The parameter {{num_images}} must be 1, 2, 3 or 4.`                  |
| Invalid `aspect_ratio`      | Returns the supported aspect-ratio list                                       |
| Invalid `speed`             | Returns `The parameter {{speed}} must be either 'none', 'regular' or 'high'.` |
| Invalid `output_format`     | Returns `The parameter {{output_format}} must be either 'jpeg' or 'png'.`     |

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)