Tutoriale
Come usare qwen-image-2.0-pro tramite l'API HiAPI: curl, Python e una richiesta funzionante
Esercitazione pratica di integrazione per sviluppatori: prima chiamata riuscita, analisi della struttura della richiesta e risoluzione dei problemi
In questa pagina
Cosa offre qwen-image-2.0-pro a chi usa l'API
qwen-image-2.0-pro è un modello di generazione di immagini che si invoca via HTTP. Dal punto di vista del tuo codice, si comporta come un endpoint di chat completion: invii un payload JSON che descrive l'immagine desiderata e ricevi una risposta JSON contenente l'immagine generata.
Il vantaggio di accedervi tramite l'API HiAPI è la coerenza. Una sola chiave API, un unico base URL e una sola struttura di richiesta funzionano su tutti i modelli. Se in seguito cambi l'identificatore del modello o modifichi i parametri, il codice circostante resta invariato. Non devi imparare un nuovo SDK né gestire più set di credenziali per ogni modello di immagine che provi.
Questo tutorial esegue prima una chiamata completa con curl, poi la porta in Python, spiega come leggere l'immagine dalla risposta e infine fornisce una checklist di risoluzione dei problemi e un piccolo wrapper riutilizzabile. Tutti gli esempi usano lo stesso payload e la stessa variabile d'ambiente per la chiave, così ciò che funziona nel terminale funziona anche nello script senza modifiche.
Prerequisiti e preparazione della chiave
Prima di scrivere qualsiasi codice, assicurati che queste tre cose siano pronte.
1. Account HiAPI e chiave API
Crea un account e genera una chiave API dalla dashboard. La chiave è un'informazione riservata: trattala come una password. Non incollarla in file sorgente che finiranno nel controllo di versione.
2. Esporta la chiave come variabile d'ambiente
Gli esempi seguenti leggono la chiave da HIAPI_API_KEY, così gli stessi comandi e script funzionano in locale e in CI senza modifiche.
export HIAPI_API_KEY="your_key_here"
In Windows PowerShell usa $env:HIAPI_API_KEY = "your_key_here". In CI, impostala come variabile d'ambiente segreta nella configurazione della pipeline.
3. Uno strumento per effettuare richieste HTTP
curl è di solito già installato. Per Python servono Python 3 e la libreria requests:
pip install requests
Prima di proseguire, puoi verificare che la shell veda la chiave:
# macOS / Linux
echo "${HIAPI_API_KEY:0:4}..."
Se non viene stampato nulla, la variabile non è impostata e tutte le richieste falliranno con un errore di autenticazione. Risolvi prima questo problema.
Richiesta minima funzionante con curl
Il modo più rapido per verificare la connettività è eseguire una chiamata curl leggendo la chiave dalla variabile d'ambiente. Il payload è un oggetto JSON contenente il campo model e un array messages in stile chat completion.
curl -sS https://api.hiapi.ai/v1/chat/completions \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen-image-2.0-pro",
"messages": [
{
"role": "user",
"content": "A small ceramic mug on a wooden table, soft morning light, product photo"
}
]
}'
Tre dettagli sono importanti. L'header Authorization usa lo schema Bearer. Il valore di model deve corrispondere esattamente all'identificatore del modello. content è una stringa di prompt in linguaggio naturale che descrive l'immagine.
Se la richiesta ha successo, vedrai nel terminale la risposta JSON stampata. Se fallisce, vedrai il codice di stato HTTP e il messaggio di errore. Controlla il codice di stato prima di leggere il corpo della risposta: 401 indica una chiave errata o mancante, 400 di solito indica un payload malformato, mentre 404 o un errore di modello non trovato indicano un identificatore del modello errato.
Quando questo comando restituisce una risposta di successo, la connettività è confermata e puoi passare a scrivere il codice.
La stessa richiesta in Python
Quando porti la chiamata in Python, mantieni il payload identico. L'unica differenza è il modo di leggere la variabile d'ambiente e di serializzare la richiesta.
import json
import os
import requests
api_key = os.environ["HIAPI_API_KEY"]
payload = {
"model": "qwen-image-2.0-pro",
"messages": [
{
"role": "user",
"content": "A small ceramic mug on a wooden table, soft morning light, product photo",
}
],
}
response = requests.post(
"https://api.hiapi.ai/v1/chat/completions",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=120,
)
response.raise_for_status()
data = response.json()
print(json.dumps(data, indent=2))
Nota che json=payload fa sì che requests imposti automaticamente l'header Content-Type e serializzi il corpo della richiesta. timeout è importante perché la generazione di immagini può richiedere più tempo di una tipica chat completion; 120 secondi è un punto di partenza ragionevole. raise_for_status() trasforma i codici di stato di errore in eccezioni, così un fallimento non passa inosservato.
Eseguendo questo script dovresti ottenere lo stesso JSON visto con curl. In caso contrario, il tuo ambiente differisce dalla shell in cui curl ha funzionato: la causa più comune è la variabile della chiave.
Leggere la risposta e gestire l'output dell'immagine
La risposta segue la struttura delle chat completion, quindi l'immagine generata si ottiene attraverso lo stesso percorso usato per le risposte testuali. Controlla prima il JSON stampato; la struttura sarà familiare:
{
"choices": [
{
"message": {
"role": "assistant",
"content": "..."
}
}
]
}
L'immagine generata compare nel contenuto del messaggio dell'assistente, di solito sotto forma di URL o di payload codificato in base64, a seconda di come il modello restituisce i media. Non dare per scontato quale dei due sia; leggi il valore e gestisci il caso in base al suo prefisso:
content = data["choices"][0]["message"]["content"]
if isinstance(content, str) and content.startswith("http"):
image_url = content
# Scarica e salva se vuoi una copia locale
image_bytes = requests.get(image_url, timeout=60).content
with open("output.png", "wb") as f:
f.write(image_bytes)
print("salvato output.png da URL")
else:
# Tratta come dati immagine codificati in base64
import base64
image_bytes = base64.b64decode(content)
with open("output.png", "wb") as f:
f.write(image_bytes)
print("salvato output.png da base64")
Due note pratiche. Se il contenuto è un URL, trattalo come un link temporaneo e scaricalo al più presto, invece di collegarlo direttamente nel prodotto. Se è base64, isola la fase di decodifica in modo che un payload malformato generi un errore catturabile. Registra sempre la risposta grezza in un file di log prima di analizzarla, così puoi fare debug senza rieseguire una richiesta potenzialmente lenta.
Checklist per le richieste fallite
Quando una richiesta fallisce, non riscrivere subito l'intera chiamata. Esegui i controlli seguenti in ordine e fermati al primo che fallisce. Ogni controllo isola una variabile.
1. Autenticazione
Controlla prima il codice di stato. 401 significa chiave mancante, scaduta o malformata. Verifica che la variabile d'ambiente sia impostata nella shell corrente, che tu abbia usato il prefisso Bearer e che l'header non abbia spazi finali.
2. Identificatore del modello
Un errore di modello non trovato significa che il valore di model non corrisponde esattamente a un modello disponibile. Maiuscole/minuscole e suffissi contano. Confronta il tuo valore carattere per carattere con la pagina della documentazione del modello.
3. Struttura del payload
400 deriva di solito da un corpo della richiesta malformato. Verifica che messages sia un array, che ogni messaggio contenga role e content e che il JSON sia valido. Elaborare il payload con jq o python -m json.tool prima di inviarlo può intercettare errori di sintassi.
4. Gestione della risposta
Se la richiesta ha successo ma lo script va in crash, il problema è nel codice di parsing, non nell'API. Registra il corpo grezzo della risposta prima di estrarre i campi e verifica che il percorso che leggi esista davvero. L'immagine può essere restituita come URL in una chiamata e come base64 in un'altra, quindi gestisci i casi in base al contenuto invece di presupporre.
5. Timeout e retry
La generazione di immagini può essere lenta. Se incontri un timeout, aumenta il timeout del client e riprova una volta. Evita di riprovare sugli errori 4xx, perché falliranno di nuovo allo stesso modo.
Un'abitudine utile: conserva una copia di una richiesta che sai funzionare e confrontala con quella fallita. La maggior parte dei fallimenti differisce per un solo campo.
Incapsulare in un client riutilizzabile
Una volta che la chiamata funziona, incapsulala dietro una piccola funzione in modo che le modifiche al modello e ai parametri siano concentrate in un unico punto. Questo wrapper centralizza il recupero della chiave, gli header e la gestione degli errori:
import base64
import os
import requests
HIAPI_BASE = "https://api.hiapi.ai/v1"
DEFAULT_MODEL = "qwen-image-2.0-pro"
def generate_image(prompt: str, model: str = DEFAULT_MODEL) -> bytes:
"""Genera un'immagine e ne restituisce i byte grezzi."""
api_key = os.environ["HIAPI_API_KEY"]
payload = {
"model": model,
"messages": [{"role": "user", "content": prompt}],
}
response = requests.post(
f"{HIAPI_BASE}/chat/completions",
headers={"Authorization": f"Bearer {api_key}"},
json=payload,
timeout=120,
)
response.raise_for_status()
content = response.json()["choices"][0]["message"]["content"]
if isinstance(content, str) and content.startswith("http"):
return requests.get(content, timeout=60).content
return base64.b64decode(content)
Il codice di chiamata diventa una riga: open("out.png", "wb").write(generate_image("A ceramic mug on a wooden table")). Se in seguito passi a un altro modello di immagine o aggiungi parametri, devi modificare solo questa funzione. L'identificatore del modello e qualsiasi dettaglio sui parametri si trovano nella pagina del modello: puoi consultare i dettagli del modello qwen-image-2.0-pro prima di integrarlo.
Inizia con la chiamata curl, poi con lo script Python e infine con il wrapper. Ogni passaggio conferma una parte più piccola prima che tu costruisca il livello successivo.
Articoli correlati
Vedi tutti gli articoli →-
Tutoriale
kling-image-4.0 scenari applicativi in pratica: 5 utilizzi ad alto valore e punti chiave di integrazione
-
Tutoriale
Come chiamare gemini-omni-1.1-flash tramite l'API HiAPI: guida con curl e Python
-
Tutoriale
Come chiamare l'API veo-3.1 text-to-video: esempi curl e Python
Guida pratica all'integrazione per sviluppatori