> ## 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 3.0 Pro API
> Qwen Image 3.0 Pro image generation and editing API for higher-fidelity text-to-image and image-to-image workflows
## Overview
Qwen Image 3.0 Pro is an asynchronous image generation and editing API for higher-fidelity outputs. Use `text-to-image` for prompt-only generation, or `image-to-image` when you want to guide the output with one to three reference images.
| Capability | Value |
| --------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Model ID | `qwen-image-3-0-pro` |
| Modes | `text-to-image`, `image-to-image` |
| Output count | One generated image per accepted task |
| Prompt | Required, non-empty string |
| Image-to-image prompt limit | Maximum `800` characters |
| Reference images | Required for `image-to-image`; `1-3` public image URLs |
| Aspect ratios | `1:1`, `1:2`, `2:1`, `1:3`, `3:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `9:21`, `21:9` |
| Default aspect ratio | `1:1` for `text-to-image`; omitted `image-to-image` ratio follows the first input image |
| Resolution tiers | `1k`, `2k` |
| Prompt expansion | `enable_prompt_expansion`, default `true` |
| Seed | `-1` for random, or `0-2147483647` |
## Endpoint and authentication
Base URL:
```text theme={null}
https://api.apixo.ai/api/v1
```
| Method | Endpoint | Purpose |
| ------ | ------------------------------------------------ | ------------------------------------------ |
| `POST` | `/generateTask/qwen-image-3-0-pro` | Submit an image generation or editing task |
| `GET` | `/statusTask/qwen-image-3-0-pro?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-image-3-0-pro" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_type": "async",
"input": {
"mode": "text-to-image",
"prompt": "a premium product launch poster with crisp readable typography, realistic studio lighting, refined layout",
"aspect_ratio": "16:9",
"resolution": "2k",
"enable_prompt_expansion": true,
"seed": -1
}
}'
```
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-image-3-0-pro?taskId=task_12345678" \
-H "Authorization: Bearer YOUR_API_KEY"
```
Processing response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "processing",
"createTime": 1767965610929
}
}
```
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
}
}
```
Failed response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "failed",
"failCode": "InvalidParameter",
"failMsg": "The parameter is invalid",
"createTime": 1767965610929,
"completeTime": 1767965620132
}
}
```
Parse `resultJson` after `state` becomes `success`:
```javascript theme={null}
const payload = JSON.parse(data.resultJson);
const imageUrls = payload.resultUrls;
```
## Request body
### Text-to-image
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "text-to-image",
"prompt": "a high-end editorial key visual for a fashion campaign, crisp typography, elegant lighting",
"aspect_ratio": "9:16",
"resolution": "2k",
"enable_prompt_expansion": true,
"seed": -1
}
}
```
### Image-to-image
```json theme={null}
{
"request_type": "callback",
"callback_url": "https://your-server.com/webhooks/apixo",
"input": {
"mode": "image-to-image",
"prompt": "upgrade this product photo into a high-end catalog image, preserve the product shape, improve lighting and background",
"image_urls": [
"https://example.com/product-front.png",
"https://example.com/product-reference.png"
],
"resolution": "2k",
"enable_prompt_expansion": true,
"seed": 123456
}
}
```
In `image-to-image` mode, omit `aspect_ratio` when you want the output to follow the first input image ratio. If you provide `aspect_ratio`, it must be one of the supported ratios below.
## Parameters
Result delivery mode. Supported values: `async`, `callback`. Use `async` for polling with `statusTask`, or `callback` for webhook delivery.
Required when `request_type` is `callback`. Must be a public HTTPS URL that can receive the final task payload. See [Webhooks](/docs/api-reference/webhooks).
Qwen Image 3.0 Pro input parameters.
Generation mode. Supported values: `text-to-image`, `image-to-image`.
Text prompt describing the desired image or edit. Leading and trailing whitespace is ignored for validation. For `image-to-image`, the prompt cannot exceed `800` characters.
Reference image URLs. Required for `image-to-image`; provide `1-3` public, directly fetchable image URLs. Ignored for `text-to-image`.
Output aspect ratio. Supported values: `1:1`, `1:2`, `2:1`, `1:3`, `3:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `9:21`, `21:9`. For `text-to-image`, blank or omitted values default to `1:1`; for `image-to-image`, blank or omitted values follow the first input image ratio.
Output resolution tier. Supported values: `1k`, `2k`. The API accepts either lowercase or uppercase values and normalizes them for billing and processing.
Whether to enable prompt expansion before generation. Supported values: `true`, `false`.
Random seed. Use `-1` for random output, or send an integer from `0` through `2147483647` for more repeatable experiments.
## Response format
### Submit task response
`POST /generateTask/qwen-image-3-0-pro` returns a task ID when the task is accepted:
API status code. `200` means the task was accepted.
Human-readable status message.
Unique task identifier used with the status endpoint.
### Status response fields
Unique task identifier.
Current task state: `pending`, `processing`, `success`, or `failed`.
JSON string containing generated image URLs in `resultUrls`. Present when `state` is `success`.
Machine-readable failure code. Present when `state` is `failed`.
Human-readable failure message. Present when `state` is `failed`.
Task creation timestamp in Unix milliseconds.
Task completion timestamp in Unix milliseconds. Present after completion.
Processing duration in milliseconds when available.
## 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-image-3-0-pro" \
-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": "preserve the product design, refine the materials, and place it in a premium studio scene",
"image_urls": [
"https://example.com/product-front.png",
"https://example.com/product-reference.png"
],
"resolution": "2k"
}
}'
```
See [Webhooks](/docs/api-reference/webhooks) for delivery requirements and retry behavior.
## Billing
Qwen Image 3.0 Pro is billed per generated image. Each accepted task produces one image, and `image-to-image` pricing also depends on the number of input image URLs.
| Mode | Resolution | Input images | APIXO price |
| ---------------- | ---------- | -----------: | ---------------: |
| `text-to-image` | `1k` | `0` | `$0.040 / image` |
| `text-to-image` | `2k` | `0` | `$0.075 / image` |
| `image-to-image` | `1k` | `1` | `$0.043 / image` |
| `image-to-image` | `1k` | `2` | `$0.046 / image` |
| `image-to-image` | `1k` | `3` | `$0.049 / image` |
| `image-to-image` | `2k` | `1` | `$0.078 / image` |
| `image-to-image` | `2k` | `2` | `$0.081 / image` |
| `image-to-image` | `2k` | `3` | `$0.084 / image` |
Billing behavior:
```text theme={null}
precharge = unit_price_for_mode_resolution_and_input_image_count
final_charge = unit_price when the generated image succeeds
refund = precharge - final_charge
```
For current discounts and market comparison pricing, see [Pricing](https://apixo.ai/pricing).
## Latency and polling
Qwen Image 3.0 Pro tasks are asynchronous. Actual latency varies by prompt complexity, reference image accessibility, selected resolution, and current queue load.
| Workflow | Recommended first poll | Poll interval |
| -------------- | --------------------------- | ------------- |
| Text-to-image | 10s-15s after task creation | 5s-10s |
| Image-to-image | 15s after task creation | 5s-10s |
For production queues or batches, use callback mode to avoid frequent polling.
Rate limits and concurrency can vary by account, API key, and model. If you receive `429`, slow down requests and retry with backoff. For account-level details, see [System APIs](/docs/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 account cannot access the model | Check permissions and account status |
| `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 a missing-parameter error |
| Missing or invalid `mode` | Returns `Invalid mode type. Supported: text-to-image, image-to-image` |
| Missing, non-string, or empty `prompt` | Returns a prompt validation error |
| `image-to-image` prompt exceeds `800` characters | Returns a prompt length error |
| Missing `image_urls` for `image-to-image` | Returns a missing-parameter error |
| `image_urls` is not an array, contains empty values, or contains more than `3` items | Returns an image URL validation error |
| Invalid `aspect_ratio` | Returns the supported aspect-ratio list |
| Invalid `resolution` | Returns `The parameter {{resolution}} is invalid. Supported: 1k, 2k.` |
| Invalid `enable_prompt_expansion` | Returns a boolean type error |
| Invalid `seed` | Returns the supported seed range |
See [Error Codes](/docs/api-reference/errors) for the full error reference.
## Related links
* [Qwen Image 3.0](/docs/models/image/qwen-image-3-0)
* [Image Models](/docs/models/image)
* [Generate Task](/docs/api-reference/generate-task)
* [Status Task](/docs/api-reference/status-task)
* [Webhooks](/docs/api-reference/webhooks)
* [Error Codes](/docs/api-reference/errors)
* [Parameter Specification](/docs/api-reference/parameters)
* [Pricing](https://apixo.ai/pricing)