Come usare l'API Qwen Image 2.1 Turbo: curl, Python e una richiesta realmente testata

Qwen Image 2.1 Turbo (qwen-image-2.1-turbo) è il livello veloce ed economico della famiglia di immagini 2.1 di Alibaba su hiapi. Riceve un prompt testuale, con 0–10 immagini di riferimento opzionali, e restituisce un PNG da 2048×2048. Questa guida presenta una richiesta eseguibile così com'è, lo schema di input effettivamente applicato dall'API, una chiamata di editing e i risultati che abbiamo osservato quando abbiamo testato l'affermazione del "PNG trasparente".

Devi ottenere una chiave API hiapi dalla console. Le chiamate passano attraverso l'API unificata di attività asincrone, quindi non c'è una risposta sincrona per l'immagine.

Richiesta minima: testo in immagine

curl -s -X POST https://www.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.1-turbo",
    "input": {
      "prompt": "贴纸风格的插画：一只戴着草帽的柴犬坐在冲浪板上，平涂配色，粗轮廓线，珊瑚橙与海蓝色",
      "aspect_ratio": "1:1",
      "seed": 42
    }
  }'
# {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Poi esegui il polling di GET /v1/tasks/<taskId> finché data.status non è success, e leggi data.output[0].url.

import os, time, requests

BASE = "https://www.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def run(input_: dict) -> str:
    r = requests.post(f"{BASE}/v1/tasks", headers=HEADERS, timeout=30,
                      json={"model": "qwen-image-2.1-turbo", "input": input_})
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]          # 注意：字段是 taskId，不是 id

    while True:
        try:
            d = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except requests.RequestException:
            time.sleep(3)                          # 临时网络错误：继续轮询同一个 id
            continue
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(3)                              # pending / running / archiving

url = run({"prompt": "a straw-hat shiba on a surfboard, flat sticker style", "aspect_ratio": "1:1"})
open("out.png", "wb").write(requests.get(url, timeout=60).content)

Scarica subito il file. L'URL di output si trova su temp.hiapi.ai ed è accompagnato da un timestamp expireAt (nella nostra esecuzione circa sette giorni dopo la creazione); se hai bisogno di conservarlo più a lungo, salva tu stesso i byte del file.

Schema di input (le regole effettivamente applicate dall'API)

Quanto segue deriva dagli errori di validazione restituiti dopo che abbiamo inviato volutamente richieste non valide, quindi riflette il comportamento reale dell'endpoint online, non una parafrasi della documentazione:

Campo	Regola
prompt	stringa obbligatoria (il modulo nella pagina del modello ne imposta il limite a 4500 caratteri)
aspect_ratio	uno dei valori 1:1, 16:9, 9:16, 4:3, 3:4
image_urls	array di URL di immagini di riferimento, 0–10 elementi; passare direttamente una stringa viene rifiutato, con image_urls must be an array
prompt_extend	booleano, interruttore di ottimizzazione del prompt
seed	intero, da 0 a 2147483647

Ci sono due differenze rispetto agli altri modelli Qwen della stessa famiglia. Qui non esiste il campo resolution: inviarlo restituisce additional properties 'resolution' not allowed. Per 1:1 l'output è una tela fissa da 2048×2048, e lo abbiamo verificato di persona. Inoltre, i campi sconosciuti di solito vengono rifiutati, non ignorati. Un aspect_ratio errato restituisce HTTP 400 con error_code: INVALID_REQUEST e l'elenco dei valori consentiti nel message.

Modifica con immagini di riferimento

L'editing e il ridisegno stilistico usano lo stesso id modello. Inserisci l'immagine di origine in image_urls e descrivi la modifica nel prompt:

curl -s -X POST https://www.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.1-turbo",
    "input": {
      "prompt": "把草帽重新着色为深紫色，其他部分保持不变",
      "image_urls": ["https://temp.hiapi.ai/.../source.png"],
      "aspect_ratio": "1:1",
      "seed": 42
    }
  }'

I risultati che abbiamo osservato in esecuzioni reali

Il 2026-10-24 abbiamo eseguito una chiamata di testo in immagine e una chiamata di editing, entrambe con seed: 42 e aspect_ratio: "1:1".

• Latenza: il testo in immagine ha raggiunto success circa 29 secondi dopo la creazione (timestamp da created a completed); l'editing ha impiegato circa 22 secondi. Lo stato passa attraverso archiving per diversi cicli di polling prima di entrare in success, quindi non considerare uno stato non terminale come un errore. Si tratta solo di due campioni, non di un benchmark.
• Output: entrambe hanno restituito PNG da 2048×2048, con il risultato del testo in immagine di circa 3,9 MB.
• Comportamento dell'editing: abbiamo reimmesso il primo output e chiesto di rendere il cappello viola. Il risultato ha conservato cane, posa, onde e layout, e ha spostato verso il viola la fascia e il nastro del cappello; il corpo in paglia del cappello è rimasto in gran parte color paglia. Per le modifiche di colore su oggetti con texture, il rispetto delle istruzioni dell'editing può essere solo parziale, quindi il prompt dovrebbe essere specifico (ad esempio "ridisegna la fascia del cappello") anziché generico.
• Sfondo trasparente: il canale alpha è completamente opaco. La pagina del modello pubblicizza la possibilità di produrre PNG con sfondo trasparente, e nel prompt abbiamo scritto "sfondo completamente trasparente, mantieni solo il soggetto e gli schizzi". Il file restituito è RGBA, ma l'alpha di ogni pixel è 255 (zero pixel trasparenti) e i quattro angoli sono di un grigio biancastro chiaro (ad esempio (241, 243, 248, 255)). Esaminando l'immagine, abbiamo scoperto che il modello ha disegnato nei pixel un tenue sfondo in stile scacchiera, invece di lasciarli trasparenti. L'output dell'editing si è comportato allo stesso modo (alpha minimo 241). Quindi, nella nostra esecuzione, il solo prompt non ha prodotto un ritaglio utilizzabile direttamente su una pagina colorata. Questo risultato riguarda solo un modo di scrivere il prompt; non abbiamo trovato un campo della richiesta per attivare la trasparenza (transparent viene rifiutato come proprietà sconosciuta). Se hai bisogno di un vero canale alpha, pianifica un passaggio di rimozione dello sfondo, ad esempio consultando la guida al background remover di 851-labs, e verificalo prima del rilascio con un controllo dei pixel come Image.open(f).getchannel("A").getextrema().

Considerazioni per la produzione

• Usa i callback al posto del polling in caso di alta concorrenza: aggiungi "callback": {"url": "https://your.app/hook", "when": "final"} nel corpo della richiesta di attività, tratta il callback come un suggerimento e conferma il risultato con GET /v1/tasks/<taskId>.
• Conserva taskId: se il polling fallisce per un errore di rete, esegui di nuovo il polling dello stesso id invece di reinviare. Un nuovo invio crea e fattura una seconda attività.
• Fissa seed per ottenere output confrontabili mentre modifichi il prompt; consideralo un criterio best-effort, non una garanzia assoluta.
• Valida prima della fatturazione: gli errori di schema (HTTP 400, INVALID_REQUEST) vengono restituiti al momento della creazione, quando non è ancora stata generata alcuna immagine.

Quale livello scegliere

La stessa famiglia include anche Qwen Image 2.1 Pro, il cui prezzo per immagine indicato nella pagina dei prezzi è superiore a quello di Turbo. Entrambi sono descritti come capaci di testo in immagine, editing e 0–10 immagini di riferimento; noi abbiamo eseguito solo Turbo, quindi non formuliamo alcuna affermazione sulla qualità relativa delle immagini. Il vantaggio di Turbo sta nel prezzo più basso e nella velocità in 8 passaggi; se per i tuoi contenuti la qualità dell'output è più importante, eseguili entrambi con lo stesso prompt e lo stesso seed e confronta. Per la generazione Qwen 3.0 più recente, vedi la guida all'API Qwen Image 3.0 e la guida a Qwen Image 3.0 Pro.

Contenuti correlati

• Pagina del modello Qwen Image 2.1 Turbo
• Prezzi
• Guida all'API Qwen Image 3.0
• Documentazione

Domande frequenti

Qual è l'id del modello? qwen-image-2.1-turbo, inviato tramite POST /v1/tasks.

Si può scegliere la risoluzione di output? In questo schema no: non esiste un campo resolution. Scegli un aspect_ratio tra i cinque valori consentiti.

L'editing è supportato? Sì: passa 1–10 immagini di origine in image_urls insieme a un prompt di istruzioni. Nei nostri test, l'editing di colore su aree con texture ha funzionato solo parzialmente.

Restituisce PNG trasparenti? Nei nostri test no: il file è in modalità RGBA, ma il canale alpha è completamente opaco e contiene uno sfondo disegnato. Verifica tu stesso l'alpha e, se hai bisogno di una vera trasparenza, aggiungi un passaggio di rimozione dello sfondo.

Quanto costa? Consulta la pagina dei prezzi; al momento della stesura è il più economico dei due livelli 2.1.