Qwen Image 3.0 API

Alibaba Qwen Image 3.0. One endpoint for text-to-image and image editing (pass reference images to edit, up to 3), strong at dense in-image text, 12 languages and structured layouts. 1K / 2K, eight aspect ratios or auto. Two tiers: standard qwen3-image ($0.035/image) and Pro qwen3-image-pro (1K $0.037 / 2K $0.075). Async: POST creates the task, then poll with GET ?task_id= or supply a callback_url.

Autenticação

Authorization: Bearer YOUR_API_KEY

Model & pricing

Model	model	Price	Notas
Qwen Image 3.0	qwen3-image	$0.035	1K/2K flat · everyday volume
Qwen Image 3.0 Pro	qwen3-image-pro	$0.037 / $0.075	1K / 2K · photoreal detail

Image editing adds $0.004 per reference image. Failures are never charged.

Endpoints

POST/api/v1/images/generationscreate task

GET/api/v1/images/generations?task_id=...poll status

Code examples

# ─── 1. Text-to-image ──────────────────────────────────────
# model: "qwen3-image" (standard) or "qwen3-image-pro" (higher fidelity).
# resolution: "1K" | "2K". aspect_ratio: 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9 (or "auto").
curl -X POST https://api.apimodels.app/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-image",
    "prompt": "A cafe opening poster, vertical layout. Bold brush-calligraphy title, small caption text, minimal editorial style",
    "resolution": "2K",
    "aspect_ratio": "9:16"
  }'

# Response:
# { "code": 200, "msg": "success", "data": { "taskId": "clxxx...", "state": "pending" } }


# ─── 2. Image editing with a reference URL ─────────────────
curl -X POST https://api.apimodels.app/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-image-pro",
    "prompt": "Keep the subject, change to soft evening light",
    "image_urls": ["https://example.com/photo.jpg"],
    "aspect_ratio": "auto"
  }'


# ─── 3. Multi-image edit (up to 3 reference images) ────────
curl -X POST https://api.apimodels.app/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-image",
    "prompt": "Replace the poster in image 1 with the product from image 2",
    "image_urls": [
      "https://example.com/scene.jpg",
      "https://example.com/product.jpg"
    ]
  }'


# ─── 4. Poll task status ───────────────────────────────────
curl "https://api.apimodels.app/v1/images/generations?task_id=clxxx..." \
  -H "Authorization: Bearer YOUR_API_KEY"

Parâmetros da requisição

Field	Required	Type	Description
model	Yes	string	"qwen3-image" (standard) or "qwen3-image-pro" (Pro)
prompt	Yes	string	Prompt or editing instructions, Chinese and English supported. When editing multiple images, reference them as "image 1", "image 2".
resolution	No	string	"1K" (default) or "2K". Standard is $0.035 at both; Pro is $0.037 at 1K, $0.075 at 2K.
aspect_ratio	No	string	Aspect ratio: 1:1 / 3:2 / 2:3 / 4:3 / 3:4 / 16:9 / 9:16 / 21:9. Omit or pass "auto" to let the model choose from the prompt.
image_urls	No	string[]	Reference image URLs (1-3, ≤ 10MB each, jpeg/png/webp). Providing them routes to image editing; each adds $0.004.
image_url	No	string	Single reference image URL — equivalent to image_urls with one item.
image_base64	No	string	Base64-encoded or data-URI reference image (for local files).
negative_prompt	No	string	Negative prompt — content you do not want in the image.
prompt_extend	No	boolean	Intelligent prompt rewriting, default true. Improves results for short prompts.
seed	No	integer	Random seed [0, 2147483647]. A fixed seed reproduces results.
callback_url	No	string	Webhook URL called on completion; server POSTs the same JSON as the poll response.

Campos da resposta

Field	Required	Type	Description
code	—	integer	200 em caso de sucesso; caso contrário, consulte a tabela de códigos de erro.
msg	—	string	"success" ou uma mensagem de erro.
data.taskId	—	string	ID da tarefa usado para consultas de status.
data.state	—	string	pending / processing / completed / failed.
data.resultUrls	—	string[]	Present only when state=completed; R2-hosted image URLs. Auto-deleted after 30 days — download or re-host promptly.
data.failMsg	—	string	Presente apenas quando state=failed; motivo da falha do provedor upstream.

Notas

Async flow: POST returns taskId immediately (state=pending); poll GET ?task_id= until completed.
Generation is slow — size your polling window accordingly. Measured percentiles from our own production traffic: the standard tier runs a median of 73s with 90% done inside 96s (fastest seen: 36s); Pro has a median of 121s but a long tail — 10% exceed 324s and the slowest we have seen is 359s. Allow 3 minutes for standard and at least 8 minutes for Pro. Do not give up polling before ~4 minutes, and do not set a client timeout of a few tens of seconds.
Endpoint auto-routes: prompt only → text-to-image; with image_urls / image_url / image_base64 → image editing. No endpoint or model-name switch needed.
Passing aspect_ratio "auto" (or omitting it) lets the model pick the shape from the prompt — it is not an error.
Image editing takes up to 3 reference images at $0.004 each; the per-image add-on is the same for standard and Pro.
callback_url is preferred in production — the backend POSTs the same data payload on completion, avoiding your own polling loop.
resultUrls are R2 links auto-deleted after 30 days — download or re-host within that window.
Tarefas com falha são gratuitas: requisições com state=failed não são cobradas, tentar novamente é seguro.

Try it in the Playground, or the Pro tier at Qwen Image 3.0 Pro

Perguntas frequentes

How much does the Qwen Image 3.0 API cost?

Standard (qwen3-image) is $0.035 per image at 1K or 2K. Pro (qwen3-image-pro) is $0.037 at 1K and $0.075 at 2K. Image editing adds $0.004 per reference image. Failures are never charged.

Does one model do both text-to-image and editing?

Yes. Send only a prompt for text-to-image; add image_urls (1-3 references) and the same model edits instead. No endpoint or model-name switch.

How long does a request take? What polling window should I use?

Measured on our own production traffic: the standard tier runs a median of 73s with 90% inside 96s; Pro has a median of 121s but a long tail, with 10% over 324s and a slowest observed 359s. Allow 3 minutes for standard and at least 8 minutes for Pro. Sizing the window off the median is the usual cause of a task that looks stuck.

How many reference images can I send?

Up to 3, each 10MB or less, in jpeg/png/webp. Sending a fourth is rejected at creation rather than silently dropped. Each reference image adds $0.004, so a three-image edit at 1K standard is $0.035 + 3 × $0.004 = $0.047.

What does aspect_ratio "auto" do?

It follows the first reference image, which is what you want for edits that must not re-crop the subject. With no reference image there is nothing to follow, so pass one of the eight explicit ratios (1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9) for text-to-image.

Can I get a callback instead of polling?

Yes — pass callback_url when you create the task and we POST the finished result there, which is the better shape for Pro given its long tail. Polling with GET ?task_id= still works and the two are not exclusive; a callback plus a slow safety poll is the most robust setup.

How long do resultUrls stay valid?

Seven days, then the files are deleted automatically. Download and re-host anything you need long term — do not store our URLs as if they were permanent image hosting.

Does Qwen Image 3.0 support 4K or mask-based inpainting?

Neither. Every tier tops out at 2K — for native 4K use gpt-image-2 at $0.05 per image. There is no mask parameter either; edit a region by passing the original in image_urls and describing the change in the prompt.