Tutoriale
Come chiamare qwen-image-3.0-pro/image-to-image tramite l'API di HiAPI: curl, Python e una richiesta che funziona
Una guida pratica all'integrazione che copre il pattern delle attività asincrone, i client curl e Python e la gestione degli errori
In questa pagina
Perché la generazione di immagini (image-to-image) è un'attività asincrona
Quando chiami un modello di generazione di immagini, non stai richiedendo il completamento di una stringa che può essere restituito in streaming in poche centinaia di millisecondi. Il modello deve caricare la tua immagine sorgente, eseguire l'intero processo di generazione diffusionale condizionato da essa e codificare l'output. Questo può richiedere da pochi secondi a decine di secondi, e la durata varia con la risoluzione e le impostazioni. Mantenere aperta una connessione HTTP per tutta questa finestra non conviene a nessuno: i proxy vanno in timeout, i bilanciatori di carico scartano i socket inattivi, e i tuoi thread di lavoro restano bloccati su una richiesta che potrebbe anche fallire più tardi.
Per questo l'endpoint adotta un modello "invia prima, interroga poi". La tua prima richiesta invia un'attività e restituisce immediatamente un handle dell'attività. La generazione dell'immagine avviene dietro quell'handle. Poi invii richieste separate e a basso costo per controllare lo stato dell'attività finché non segnala il completamento, momento in cui la risposta trasporta il risultato che hai richiesto.
Ci sono alcune conseguenze pratiche che dovresti incorporare nel design fin dall'inizio:
- Inviare non significa completare. Il successo della chiamata di invio significa solo che la piattaforma ha accettato la tua attività, nient'altro. Nel codice, distingui questi due stati.
- L'ID attività è il tuo unico handle. Salvalo in modo persistente. Se il tuo processo si blocca tra l'invio e il polling, l'ID attività è la base per riprendere senza reinviare (e pagare di nuovo) lo stesso lavoro.
- Il polling è economico ma non gratuito. I controlli di stato sono leggeri, ma un ciclo serrato genera comunque traffico e può attivare limiti di frequenza. Distanzia gli intervalli.
- I fallimenti arrivano in modo asincrono. Un'immagine corrotta o parametri rifiutati possono manifestarsi come errori a livello di attività, non come errori HTTP all'invio. Il tuo codice di polling deve leggere lo stato dell'attività, non solo il codice di stato.
Tieni a mente questo modello e l'integrazione successiva sarà immediata: una chiamata crea il lavoro, un ciclo lo attende, e una gestione intenzionale dei tre casi che possono andare storto.
Prima di scrivere codice: cosa preparare
Prima di toccare il terminale, raccogli alcune cose da cui dipende ogni chiamata in questa guida.
Credenziali HiAPI
Ti serve una chiave API di HiAPI. Trattala come un segreto: caricala da una variabile d'ambiente, non incollarla in uno script che potresti committare. Gli esempi seguenti la leggono come HIAPI_API_KEY. L'URL di base dell'API e l'identificatore esatto del modello qwen-image-3.0-pro/image-to-image sono le due costanti a cui farai riferimento per tutto il tempo.
Un'immagine sorgente
Image-to-image richiede un input. Preparane una e decidi come fornirla:
- come URL accessibile pubblicamente, oppure
- come asset caricato o payload codificato, a seconda di quale forma accetta l'endpoint.
Prima di scrivere la chiamata, consulta lo schema della richiesta del modello per confermare i nomi esatti dei campi e i formati di immagine sorgente accettati. Fornire un'immagine sorgente che l'endpoint non accetta è la causa più comune di rifiuto dell'attività, ed è molto più facile escluderla in anticipo che debugarla dai messaggi di errore.
Un client in grado di fare polling
Poiché la chiamata è asincrona, lo strumento che usi per inviare richieste deve anche essere in grado di emettere richieste successive ripetutamente. curl va bene per un primo smoke test; qualsiasi uso più duraturo dovrebbe essere uno script. Non c'è alcun URL di callback da configurare né webhook da ospitare: il polling è il meccanismo, quindi pianifica un ciclo.
Un posto dove vedere il risultato
Decidi in anticipo che aspetto ha per te "completato": un URL che puoi aprire nel browser, oppure i byte che scrivi su disco. Saperlo prima di iniziare rende ovvio a colpo d'occhio quando l'integrazione funziona davvero.
Con queste quattro cose a portata di mano, la prima richiesta è breve.
Inviare una richiesta funzionante con curl
Il modo più rapido per verificare che chiave, endpoint e ciclo di vita dell'attività funzionino è una sessione curl in due passaggi. Prima invia; poi interroga.
Passaggio 1: inviare l'attività
curl -sS -X POST "$HIAPI_BASE_URL/qwen-image-3.0-pro/image-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "https://example.com/source.jpg",
"prompt": "restyle as a soft watercolor illustration"
}'
Voce per voce:
-X POST—— l'invio è un'operazione di creazione.- L'intestazione
Authorizationtrasporta la tua chiave. Esportando una variabile d'ambiente invece di digitarla inline, eviti che rimanga nella cronologia della shell. Content-Type: application/json—— il corpo della richiesta è JSON.-d—— il payload JSON. Il campoimagepunta alla tua immagine sorgente,promptdescrive la trasformazione da eseguire. I nomi dei parametri e le opzioni accettate provengono dallo schema della richiesta del modello; verificaLi lì, non indovinare.
La risposta a un invio riuscito è un oggetto attività. Conterrà un identificatore — chiamalo ID attività — e un campo di stato che dovrebbe indicare che l'attività è in coda o in esecuzione. Annota l'ID attività; tutto il resto dipende da esso.
Passaggio 2: interrogare l'attività
export TASK_ID="<the id from the submit response>"
curl -sS "$HIAPI_BASE_URL/tasks/$TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY"
A ogni chiamata, leggi il campo di stato. Quando riporta in attesa o in esecuzione, attendi qualche secondo prima di controllare di nuovo. Quando riporta successo, la risposta contiene l'immagine generata — di solito un URL recuperabile, oppure dati codificati. Quando riporta fallimento, la risposta trasporta una descrizione dell'errore che spiega il motivo.
L'intero ciclo di vita è questo: un invio, poi controlli di stato fino allo stato terminale. Qualsiasi cosa tu costruisca in seguito è solo una versione più comoda di questi due comandi, con attesa e gestione degli errori.
Implementare la stessa chiamata in Python
Ripetere a mano questi due passaggi curl diventa presto noioso, e copiare e incollare il ciclo di polling in ogni script è esattamente il modo in cui si diffondono bug sottili. Avvolgi il pattern di invio e polling in una funzione riutilizzabile.
import os
import time
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL_PATH = "/qwen-image-3.0-pro/image-to-image"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def submit_task(source_image: str, prompt: str) -> str:
resp = requests.post(
BASE_URL + MODEL_PATH,
headers={**HEADERS, "Content-Type": "application/json"},
json={"image": source_image, "prompt": prompt},
timeout=30,
)
resp.raise_for_status()
return resp.json()["id"]
def wait_for_task(task_id: str, poll_interval: float = 3.0,
max_wait: float = 300.0) -> dict:
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
resp = requests.get(
f"{BASE_URL}/tasks/{task_id}",
headers=HEADERS,
timeout=30,
)
resp.raise_for_status()
task = resp.json()
status = task["status"]
if status == "succeeded":
return task
if status == "failed":
raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
time.sleep(poll_interval)
raise TimeoutError(f"task {task_id} did not finish within {max_wait}s")
def generate(source_image: str, prompt: str) -> dict:
task_id = submit_task(source_image, prompt)
return wait_for_task(task_id)
Ci sono alcune scelte deliberate che vale la pena evidenziare:
- Separare invio e attesa. Se l'invio fallisce, lo sai prima che avvenga qualsiasi polling. Se in futuro vorrai inviare in un processo e raccogliere in un altro, la separazione è già pronta.
- Ogni richiesta ha un
timeout. Una richiesta senza timeout può bloccarsi all'infinito, che è esattamente il tipo di modalità di errore che un'API asincrona dovrebbe aiutarti a evitare. - Il ciclo di polling ha sia un intervallo sia una scadenza complessiva. Senza scadenza, un'attività bloccata in stato di esecuzione andrebbe in ciclo per sempre. Senza intervallo, martelleresti l'endpoint.
- Le stringhe di stato sono confrontate in modo esplicito. Qualsiasi stato che non sia né successo né fallimento ricade nell'iterazione successiva, che è il comportamento predefinito corretto per gli stati intermedi.
Chiamala come chiameresti qualsiasi funzione: generate(source_url, "make the background a dusk cityscape"). L'oggetto restituito è il payload dell'attività in stato terminale, da cui estrai il riferimento all'immagine.
Gestire errori e attività fallite
Gli errori nei flussi di lavoro asincroni ricadono in tre categorie, e ciascuna richiede una risposta diversa.
Rifiuto a livello di richiesta
Si tratta di normali risposte di errore HTTP alla chiamata di invio — credenziali errate o mancanti, JSON malformato, parametri non supportati, immagine sorgente irraggiungibile. Arrivano prima che esista qualsiasi attività.
La risposta corretta è quasi sempre fermarsi e presentare il messaggio. Riprovare un payload malformato non fa che sprecare quota e tempo. Registra il codice di stato e il corpo della risposta verbatim; il messaggio di validazione di solito indica il campo problematico. Due casi meritano una gestione speciale: gli errori di autenticazione dovrebbero fallire rapidamente e in modo evidente, perché indicano un problema di configurazione; le risposte di limite di frequenza possono essere ritentate dopo un backoff.
Fallimenti a livello di attività
Qui l'invio è riuscito, l'ID attività esiste, ma il lavoro è fallito. La risposta di polling riporta lo stato di fallimento insieme a un errore.
Questa categoria copre i problemi del modello stesso: immagine sorgente decodificabile ma inutilizzabile, prompt rifiutato, generazione che raggiunge un limite interno. Poiché questi sono specifici dell'input, riprovare alla cieca di solito riproduce lo stesso fallimento. Decidi caso per caso: un errore interno temporaneo può valere un tentativo; un'immagine sorgente rifiutata non lo vale mai. Registra l'ID attività insieme all'errore, per poterlo correlare a una richiesta di supporto.
Polling che non finisce mai
L'invio è riuscito, l'attività esiste, il polling è in esecuzione — ma lo stato terminale non arriva mai. Questo non è un errore restituito dalla piattaforma; è un'assunzione nel tuo codice che deve scadere.
Proteggilo con una scadenza, come mostrato nell'esempio Python. Quando la scadenza scatta, interrompi il polling. Non restituire silenziosamente un risultato parziale; lancia o restituisci un risultato di timeout esplicito, e lascia decidere al chiamante. Conserva l'ID attività — l'attività potrebbe ancora completarsi dopo la tua scadenza, e potresti volerla raccogliere più tardi senza reinviarla.
Regola pratica per queste tre categorie: tratta lo stato dell'attività come unica fonte di verità. Il codice di stato HTTP ti dice se la richiesta è stata accettata; lo stato dell'attività e il campo errore ti dicono se il lavoro è riuscito. Leggi entrambi, e i fallimenti diventano diagnosticabili invece che misteriosi.
Integrarlo nel codice di produzione
La funzione sopra è un'integrazione funzionante, non un servizio completo. Prima che gestisca traffico reale, stringi quattro cose.
Timeout ovunque
Imposta timeout espliciti di connessione e lettura per ogni chiamata — invio, polling e qualsiasi recupero successivo dell'immagine risultante. Poi imposta una scadenza complessiva per l'intero ciclo di vita dell'attività. Il timeout a livello HTTP protegge la singola richiesta; la scadenza dell'attività protegge l'intera operazione.
Retry con criterio
Riprova solo ciò che è sicuro riprovare. I limiti di frequenza durante il polling e gli errori di rete temporanei sono idonei. Un payload rifiutato non lo è. Per i fallimenti a livello di attività, riprovare significa inviare una nuova attività, che è un'operazione diversa e più costosa del ricontrollare lo stato — trattala come una decisione intenzionale, preferibilmente con un limite.
Log che includono l'ID attività
Registra l'ID attività al momento dell'invio e a ogni successiva transizione di stato, insieme alle informazioni temporali. L'intervallo tra l'invio e il primo stato terminale è la metrica che vorrai davvero quando le cose sembrano lente. Quando un utente segnala un risultato scadente, l'ID attività è la chiave per trasformare un aneddoto in una traccia verificabile.
Tenere il polling fuori dal percorso della richiesta
Se la tua funzione gira dentro un handler web, un ciclo di polling sincrono tiene aperta la richiesta per tutta la durata della generazione — esattamente il problema che il design asincrono vuole evitare. Invece, invia nell'handler, restituisci l'ID attività al chiamante ed esegui l'attesa in un processo di lavoro in background, in una coda o in un'attività pianificata. Poi è il client a interrogare il tuo servizio, non il modello.
Costruita in questo ordine, l'integrazione passa da "funziona sulla mia macchina" a qualcosa su cui puoi contare: invia, salva l'handle, attendi con dei limiti, e lascia che sia lo stato dell'attività — non la speranza — a dirti quando fermarti.
Articoli correlati
Vedi tutti gli articoli →-
Tutoriale
Guida pratica a gpt-6.2-sol: 5 utilizzi ad alto valore dei modelli testuali nel business
-
Tutoriale
Guida pratica a gpt-6.2-astra: integrazione e punti chiave per 5 scenari testuali ad alto valore
Checklist dal punto di vista dello sviluppatore, dalla selezione degli scenari all'implementazione ingegneristica
-
Tutoriale
Scenari pratici di Tripo H3.1: 5 utilizzi ad alto valore e punti di implementazione
Da text-to-3D alla ricostruzione multi-view: scegliere modalità e parametri giusti per ogni scenario di business