Qwen Image API

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:

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:

Authorization: Bearer YOUR_API_KEY

Submit requests also require:

Content-Type: application/json

Copy-paste async quickstart

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:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678"
  }
}

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

Poll for result

curl -X GET "https://api.apixo.ai/api/v1/statusTask/qwen?taskId=task_12345678" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success response:

{
  "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:

const payload = JSON.parse(data.resultJson);
const imageUrls = payload.resultUrls;

Request body

{
  "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

request_type · string · default: "async" · required

Result delivery mode. Use async for polling with statusTask, or callback for webhook delivery.

callback_url · string

Required when request_type is callback. Must be a callback URL that can receive the final task payload. See Webhooks.

input · object · required

Qwen Image input parameters.

Show properties

mode · 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.

prompt · string · required

Prompt text. Must be a non-empty string and cannot exceed 2000 characters.

image_url · string · required

Source image URL. Must be a directly fetchable public image URL.

num_images · integer · required

Number of requested output images. Supported values: 1, 2, 3, 4.

aspect_ratio · string

Optional output aspect ratio. Supported values: 1:1, 4:3, 3:4, 9:16, 16:9.

speed · string · default: "none"

Optional generation speed. Supported values: none, regular, high.

num_inference_steps · integer · default: "25"

Optional inference step count. Supported range: 2-49.

guidance_scale · integer · default: "4"

Optional guidance scale. Supported range: 0-20.

output_format · string · default: "png"

Output image format. Supported values: png, jpeg.

negative_prompt · string

Optional negative prompt. Maximum length is 500 characters.

seed · integer

Optional random seed.

sync_mode · boolean

Optional sync flag for compatibility. For normal APIXO task usage, keep the default asynchronous workflow.

Response format

Submit task response

POST /generateTask/qwen returns a task ID when the task is accepted:

code · integer

API status code. 200 means the task was accepted.

message · string

Human-readable status message.

data.taskId · string

Unique task identifier used with the status endpoint.

Status response fields

taskId · string

Unique task identifier.

state · string

Current task state: pending, processing, success, or failed.

resultJson · string

JSON string containing generated image URLs in resultUrls. Present when state is success.

failCode · string

Machine-readable failure code. Present when state is failed.

failMsg · string

Human-readable failure message. Present when state is failed.

createTime · integer

Task creation timestamp in Unix milliseconds.

completeTime · integer

Task completion timestamp in Unix milliseconds. Present after completion.

costTime · integer

Processing duration in milliseconds when available.

Webhook callback mode

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

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

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

For production queues or batches, use callback mode to avoid frequent polling.

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.

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 for the full error reference.

Related links

• Generation API Overview
• Image Models
• Generate Task
• Status Task
• Webhooks
• Error Codes
• Parameter Specification
• Pricing