How to Use the Qwen Image 3.0 Pro API: curl, Python, and a Working Request

Qwen Image 3.0 Pro is the higher tier of Alibaba's Qwen Image 3.0, live on hiapi's async task API in two entries: qwen-image-3.0-pro/text-to-image and qwen-image-3.0-pro/image-to-image. It costs more than standard Qwen Image 3.0 and adds richer detail and materials, while keeping accurate Chinese and English text. This guide gives you a working request in curl and Python, the current input schema, and the production patterns you need before shipping it.

Updated October 2026. The earlier model id qwen-image-3.0-pro and its size field no longer work: the old id returns MODEL_UNAVAILABLE and size is rejected as an unknown field. Use the model ids above with aspect_ratio and resolution.

What it costs

	1K (default)	2K
Pro text-to-image / image-to-image	$0.0497	$0.0993
Standard text-to-image / image-to-image (for comparison)	$0.0358	$0.0358

Live hiapi prices, checked October 18, 2026.

Pro at 1K costs about 39% more than standard; at 2K it's about 2.8× standard. On image-to-image, 1–3 reference images add nothing. Failed tasks aren't charged.

A real output

16:9. The brass plaque reads 深海来信 with LETTERS FROM THE DEEP beneath, both exactly as the prompt asked:

High-end cinematic architectural editorial photograph inside a futuristic underwater restaurant at midnight. A vast curved observation window fills the background with deep cobalt water and luminous translucent jellyfish drifting outside. On the right, a sculptural dining table of black stone, hand-blown glass and restrained brushed brass catches a narrow beam of warm light. A small refined brass menu plaque on the table is naturally photographed and contains only the exact Chinese characters “深海来信”; directly below, the exact English words “LETTERS FROM THE DEEP”. The left third remains calm dark-blue negative space with volumetric light rays. No poster layout; this must feel like an expensive real location photographed for an architecture magazine. cinematic composition, dramatic directional lighting, rich cohesive cobalt-and-gold color grade, ultra-detailed, premium commercial finish, subtle film grain, shallow depth of field, high dynamic range, 16:9 hero composition

Generate this prompt →

qwen-image-3.0-pro/text-to-image, 16:9, example from the model page.

Minimal working example

Prerequisite: a hiapi API key from the dashboard. New accounts get 200 free credits.

curl

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-3.0-pro/text-to-image",
    "input": {
      "prompt": "A celadon teapot on a walnut table in soft morning side light, a small card beside it that reads \"FIRST FLUSH\"",
      "aspect_ratio": "4:3",
      "resolution": "1K",
      "prompt_extend": false
    }
  }'

You get a taskId back. Poll it:

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-... \
  -H "Authorization: Bearer $HIAPI_KEY"

When data.status is success, the image is at data.output[0].url. It's a temporary link, so download and store it right away.

Python

import os, time, requests

KEY = os.environ["HIAPI_KEY"]
BASE = "https://api.hiapi.ai/v1"
H = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

r = requests.post(f"{BASE}/tasks", headers=H, json={
    "model": "qwen-image-3.0-pro/text-to-image",
    "input": {
        "prompt": 'A celadon teapot on a walnut table in soft morning side light, a small card beside it that reads "FIRST FLUSH"',
        "aspect_ratio": "4:3",
        "resolution": "1K",
        "prompt_extend": False,
    },
})
task_id = r.json()["data"]["taskId"]

while True:
    d = requests.get(f"{BASE}/tasks/{task_id}", headers=H).json()["data"]
    if d["status"] in ("success", "fail"):
        break
    time.sleep(5)

if d["status"] == "success":
    open("result.png", "wb").write(requests.get(d["output"][0]["url"]).content)
else:
    print(d)

Input schema

Field	Required	Values	Notes
prompt	Yes	Up to 18,000 characters	Content, style, composition; put any text to render in quotes
image_urls	Image-to-image only	1–3 images	JPEG/PNG/WEBP/BMP/GIF/TIFF, up to 10 MB each, no SVG
aspect_ratio	No	1:1 (default), 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9
resolution	No	1K (default) / 2K	Sets the price
output_format	No	png (default) / jpeg
prompt_extend	No	boolean, default true	Rewrites your prompt; set false when wording must be exact
negative_prompt	No	Up to 500 characters	What to keep out of the image
seed	No	0–2147483647	Fix it to reproduce a result

Image-to-image example:

{
  "model": "qwen-image-3.0-pro/image-to-image",
  "input": {
    "prompt": "Refine this product photo into a premium magazine shot, keeping the bottle shape and the label text unchanged",
    "image_urls": ["https://example.com/product.jpg"],
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "prompt_extend": false
  }
}

Errors you'll see

All of these return HTTP 400 at submission; no task is created and nothing is billed:

• MODEL_UNAVAILABLE: you used the old id qwen-image-3.0-pro. Switch to /text-to-image or /image-to-image.
• additional properties 'size' not allowed: size is gone; use aspect_ratio plus resolution.
• resolution: value must be one of '1K', '2K': Pro has no 4K.
• image_urls: minItems: got 0, want 1: image-to-image needs at least one reference.

A bad API key returns 401. Failures after a task is created show up as status: "fail" on the polled result, so check data.status, not just the HTTP code.

Production patterns

• Turn off prompt_extend for text: automatic rewriting can change the words you asked for.
• Callbacks instead of polling: add "callback": {"url": "https://your-app.com/webhooks/hiapi", "when": "final"} at the top level of the request and deduplicate by taskId. See the create task reference.
• Idempotency: send an Idempotency-Key header on creation and reuse it when retrying after a timeout, so a retry never creates a second billed task.
• Store outputs promptly: output URLs expire.

FAQ

Pro or standard? Start with standard at $0.0358, the same price at 1K and 2K. Move to Pro when standard's detail isn't enough. The standard guide is How to use the Qwen Image 3.0 API.

Can it output 4K? No. Only 1K and 2K.

How many reference images can I send? Up to 3, at no extra cost.

Does the old qwen-image-3.0-pro id still work? No. It returns MODEL_UNAVAILABLE. Use qwen-image-3.0-pro/text-to-image or qwen-image-3.0-pro/image-to-image.