Come si usa l'API di Qwen Image 3.0? Poster in cinese corretti al primo colpo

TL;DR

• Qwen Image 3.0 (Tongyi Qianwen Image 3.0) ha 4 endpoint su HiAPI: versione standard qwen-image-3.0/text-to-image, qwen-image-3.0/image-to-image, versione Pro qwen-image-3.0-pro/text-to-image, qwen-image-3.0-pro/image-to-image. Apri la pagina del modello per provarlo online.
• Versione standard a prezzo fisso $0.0358 per immagine (1K e 2K allo stesso prezzo); Pro 1K $0.0497, 2K $0.0993. Modifica e generazione allo stesso prezzo, 1–3 immagini di riferimento senza costi aggiuntivi.
• Il cinese e i testi bilingue cinese-inglese sono il suo punto di forza. Come chiamarla: POST /v1/tasks con prompt, aspect_ratio, resolution, poi polling fino a success e download.

Prima guarda un'immagine

Versione standard, 16:9, i caratteri cinesi sull'insegna scritti correttamente uno per uno:

qwen-image-3.0/text-to-image, 16:9, $0.0358.

Riferimento rapido dei parametri

Campo	Obbligatorio	Valori	Descrizione
prompt	Sì	Max 18000 caratteri	Il testo che deve apparire va scritto letteralmente tra virgolette
aspect_ratio	No	1:1 (predefinito) 3:2 2:3 4:3 3:4 16:9 9:16 21:9
resolution	No	1K (predefinito) / 2K	Nella versione standard entrambe allo stesso prezzo, Pro 2K costa il doppio
output_format	No	png (predefinito) / jpeg
prompt_extend	No	Booleano, predefinito true	Riscrive automaticamente il prompt; disattivalo quando il testo deve essere preciso
negative_prompt	No	Max 500 caratteri	Ciò che non vuoi che appaia
seed	No	0–2147483647	Fissarlo facilita la riproducibilità
image_urls	Obbligatorio per l'endpoint di modifica	1–3 immagini	JPEG, PNG, WEBP ecc., max 10 MB ciascuna

I parametri sono validati in modo rigoroso: campi in più restituiscono 400. Nota: il vecchio formato "model": "qwen-image-3.0" con size non funziona più e restituisce «model not available» oppure additional properties 'size' not allowed; passa al nome del modello indicato sopra e a aspect_ratio + resolution.

curl: genera la prima immagine

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-3.0/text-to-image",
    "input": {
      "prompt": "一张秋季饮品海报，中间是一杯桂花拿铁，顶部大标题逐字写“秋日限定”，下方副标题写“桂花拿铁”，留白充足，柔和自然光",
      "aspect_ratio": "3:4",
      "resolution": "2K",
      "prompt_extend": false
    }
  }'

La risposta contiene data.taskId. Fai polling su GET /v1/tasks/{taskId} e, quando status diventa success, scarica da output[0].url. Nella versione standard 2K e 1K costano uguale: chiedi direttamente 2K.

Python: prima genera l'immagine, poi modificala

# pip install requests; export HIAPI_KEY=你的 Key
import os, time, uuid, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def run(model, timeout_s=300, **inp):
    # 重试同一次提交时复用同一个 Idempotency-Key，只会扣一次费
    r = requests.post(API, json={"model": model, "input": inp},
                      headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(4)
    raise TimeoutError(task_id)

# 文生图，标准版 2K（$0.0358）
poster = run("qwen-image-3.0/text-to-image",
             prompt="茶叶礼盒产品图，牛皮纸方盒正面写“云雾绿茶”，下方小字“净含量 100 克”，石板台面，柔和顶光",
             aspect_ratio="1:1", resolution="2K", prompt_extend=False)

# 改图：换成深色背景，文字不变（同样 $0.0358）
edited = run("qwen-image-3.0/image-to-image",
             prompt="保持礼盒和上面的文字完全不变，把背景换成深墨绿色绒布，加一缕侧光",
             image_urls=[poster], aspect_ratio="1:1", resolution="2K")

with open("tea.png", "wb") as f:
    f.write(requests.get(edited).content)

Per passare a Pro basta cambiare il nome del modello: qwen-image-3.0-pro/text-to-image oppure qwen-image-3.0-pro/image-to-image, i parametri sono identici.

Quanto costa

Endpoint	1K	2K
Standard text-to-image / image-to-image	$0.0358	$0.0358
Pro text-to-image / image-to-image	$0.0497	$0.0993

Prezzi attuali di HiAPI, verificati il 18 ottobre 2026. In caso di errore non viene addebitato nulla.

Per il confronto tra le due versioni con lo stesso prompt vedi Prezzi dell'API Qwen Image 3.0.

Da sapere prima del rilascio

• Disattiva prompt_extend quando il testo deve essere preciso: per impostazione predefinita riscrive il prompt e potrebbe modificare proprio i caratteri che vuoi.
• Scrivi il testo che deve apparire letteralmente tra virgolette e aggiungi la frase 「除以上文字外不要其他文字」.
• Usa i callback al posto del polling: aggiungi allo stesso livello di input "callback": {"url": "https://your-app.example.com/hiapi/callback", "when": "final"} e deduplica per taskId.
• Includi l'header Idempotency-Key: in caso di retry la stessa Key crea il task una sola volta.
• Scarica subito il risultato: output[0].url ha una scadenza.

Domande frequenti

Qual è la differenza tra versione standard e Pro?

I parametri sono gli stessi; Pro offre dettagli visivi e densità di layout maggiori, costa circa il 39% in più a 1K e il doppio a 2K. I testi in cinese sono accurati in entrambe le versioni.

Quante immagini si possono inviare al massimo per la modifica?

Da 1 a 3, in image_urls, senza costi aggiuntivi.

Perché il mio vecchio codice restituisce «model not available»?

Il vecchio nome del modello qwen-image-3.0 è stato dismesso: usa qwen-image-3.0/text-to-image; anche il parametro size è stato sostituito da aspect_ratio e resolution.

Puoi anche provare subito un poster in cinese dalla pagina del modello.