Integrazione API Qwen Image 3.0 Pro: curl, Python e tutti i parametri

Qwen Image 3.0 Pro (Tongyi Qianwen Image 3.0 Pro) è disponibile su HiAPI con due endpoint: text-to-image qwen-image-3.0-pro/text-to-image e image-to-image qwen-image-3.0-pro/image-to-image. Costa più della versione standard, ma in cambio offre dettagli e materiali più ricchi, e scrive comunque con precisione testo cinese e inglese. Questo articolo fornisce esempi curl e Python pronti all'uso, tutti i parametri attuali e alcune cose da tenere presenti prima della messa in produzione.

I vecchi nomi dei modelli qwen-image-3.0-pro e il campo size non sono più utilizzabili: il vecchio nome del modello restituisce MODEL_UNAVAILABLE, mentre size viene rifiutato come campo sconosciuto. Usa i due nomi dei modelli indicati sopra, insieme a aspect_ratio e resolution.

Prima i prezzi

	1K (predefinito)	2K
Pro text-to-image / image-to-image	$0.0497	$0.0993
Versione standard text-to-image / image-to-image (confronto)	$0.0358	$0.0358

Prezzi HiAPI attuali, verificati il 18 ottobre 2026.

Pro 1K costa circa il 39% in più della versione standard, mentre 2K costa circa 2,8 volte la versione standard. Le 1–3 immagini di riferimento per image-to-image non hanno costi aggiuntivi. In caso di fallimento non viene addebitato nulla.

Un'immagine reale

16:9. Sulla targhetta di ottone sul tavolo, «深海来信» e la riga più piccola sotto «LETTERS FROM THE DEEP» sono state scritte correttamente parola per parola:

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

Genera con questo prompt →

qwen-image-3.0-pro/text-to-image, 16:9, immagine di esempio della pagina del modello.

Genera la prima immagine

Preparazione: crea una API Key nella console. I nuovi utenti ricevono 200 crediti alla registrazione.

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": "一只青瓷茶壶放在胡桃木桌上，清晨的侧光，茶壶旁的小卡片上写着「雨前龙井」",
      "aspect_ratio": "4:3",
      "resolution": "1K",
      "prompt_extend": false
    }
  }'

Dopo aver ricevuto taskId, recupera il risultato:

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

Quando data.status è success, l'immagine si trova in data.output[0].url. Si tratta di un link temporaneo: scaricala e salvala altrove non appena la ottieni.

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": "一只青瓷茶壶放在胡桃木桌上，清晨的侧光，茶壶旁的小卡片上写着「雨前龙井」",
        "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)

Tutti i parametri

Campo	Obbligatorio	Valori	Descrizione
prompt	Sì	Massimo 18000 caratteri	Contenuto, stile e composizione dell'immagine; racchiudi tra virgolette il testo che deve apparire
image_urls	Obbligatorio per image-to-image	1–3 immagini	JPEG/PNG/WEBP/BMP/GIF/TIFF, massimo 10MB per immagine, SVG non supportato
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	Determina il prezzo
output_format	No	png (predefinito) / jpeg
prompt_extend	No	Booleano, predefinito true	Riscrive automaticamente il prompt; imposta false quando il testo deve essere riprodotto esattamente
negative_prompt	No	Massimo 500 caratteri	Elementi che non vuoi che appaiano
seed	No	0–2147483647	Fissalo per facilitare la riproduzione

Esempio image-to-image:

{
  "model": "qwen-image-3.0-pro/image-to-image",
  "input": {
    "prompt": "把这张产品图修成高端杂志风格，保留瓶身形状和标签上的文字",
    "image_urls": ["https://example.com/product.jpg"],
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "prompt_extend": false
  }
}

Errori comuni

Tutti vengono restituiti in modo sincrono al momento dell'invio con HTTP 400; nessun task viene creato e non viene addebitato nulla:

• MODEL_UNAVAILABLE: è stato usato il vecchio nome del modello qwen-image-3.0-pro; sostituiscilo con il nome che include /text-to-image o /image-to-image.
• additional properties 'size' not allowed: size non è più accettato; usa aspect_ratio più resolution.
• resolution: value must be one of '1K', '2K': Pro non supporta 4K.
• image_urls: minItems: got 0, want 1: image-to-image richiede almeno 1 immagine di riferimento.

Da tenere presente prima della messa in produzione

• Disattiva prompt_extend quando scrivi testo: la riscrittura automatica potrebbe modificare le parole che vuoi.
• Usa i callback invece del polling: aggiungi al livello superiore del corpo della richiesta "callback": {"url": "https://tuo-dominio/hiapi/callback", "when": "final"} e deduplica in base a taskId.
• Evita addebiti duplicati: includi l'header Idempotency-Key al momento dell'invio e riutilizza la stessa key nei tentativi dopo un timeout.
• Salva subito i risultati: i link di output scadono.

Domande frequenti

Come scegliere tra Pro e versione standard?

Prova prima la versione standard, $0.0358 per immagine, con 1K e 2K allo stesso prezzo. Passa a Pro quando i dettagli della versione standard non bastano. Per l'integrazione della versione standard vedi Integrazione API Qwen Image 3.0.

Si può generare in 4K?

No, sono disponibili solo 1K e 2K.

Quante immagini di riferimento al massimo?

3, senza costi aggiuntivi.

Puoi anche copiare direttamente il prompt del ristorante sottomarino qui sopra e generare dalla pagina del modello.