Tutoriale
Come usare gpt-image-2.6-sunburst/image-to-image tramite l'API HiAPI: guida pratica con curl e Python
Invia un'immagine di riferimento, interroga attività asincrone ed esegui il debug delle richieste end-to-end
In questa pagina
Quando usare gpt-image-2.6-sunburst/image-to-image
La generazione da testo a immagine restituisce ciò che il modello produce liberamente seguendo un prompt. La generazione da immagine a immagine, invece, parte da materiale che possiedi già: fornisci all'endpoint un'immagine di riferimento e un'istruzione, e il modello genera una nuova immagine derivata da quel riferimento. Su HiAPI, gpt-image-2.6-sunburst/image-to-image è l'endpoint dedicato a questa seconda modalità.
Sceglilo quando l'immagine di partenza è essa stessa parte del requisito — ad esempio per ridisegnare lo stile di un materiale esistente, regolare luce o composizione, applicare un trattamento visivo a una foto di prodotto o generare varianti controllate di un design. L'immagine di riferimento è l'ancora: trasporta soggetto, palette e layout, mentre il tuo prompt descrive la trasformazione, non la scena da zero. Se non hai materiale di partenza e vuoi solo un'immagine da una descrizione, l'endpoint da testo a immagine è più semplice e lascia al modello maggiore libertà.
Due conseguenze pratiche determinano tutto quanto segue. Primo, la richiesta trasporta un input quasi binario (il riferimento immagine), il che influisce su come costruisci il corpo della richiesta. Secondo, la generazione di immagini non è istantanea, quindi l'endpoint opera come attività asincrona invece di restituire l'immagine in linea. Pianifica i due passaggi di "invio" e "recupero", non una singola chiamata bloccante.
Prerequisiti e configurazione dell'autenticazione
Prima di inviare la prima richiesta ti servono tre cose: un account HiAPI, una chiave API e un modo di fare riferimento all'immagine di partenza accettato dall'endpoint. Crea la chiave nella console HiAPI e trattala come una password — autorizza ogni chiamata addebitata sul tuo account.
Passa la chiave come token bearer nell'header Authorization. Non codificarla mai nei file sorgente, nei notebook o nella cronologia dei commit. Esportala come variabile d'ambiente per i test da shell e leggila dall'ambiente (o da un gestore di segreti) nel codice dell'applicazione:
export HIAPI_API_KEY="your_api_key_here"
Decidi in anticipo come fornire l'immagine di riferimento. Di solito puoi caricare il materiale in una posizione temporanea e passare un URL, oppure inviare l'immagine come dati codificati in base64 nel corpo della richiesta. L'URL rende la richiesta più piccola e più facile da registrare; base64 elimina l'hosting aggiuntivo ma gonfia il corpo della richiesta. In entrambi i casi, mantieni il file in un formato supportato dall'endpoint e controlla i limiti di dimensione prima di inviare. Annota anche l'URL di base dell'API HiAPI del tuo account — ogni percorso seguente deve essere preceduto da esso.
Inviare l'immagine di riferimento con curl
Inizia dalla shell, così vedi esattamente cosa viene inviato. La forma della chiamata è una POST all'endpoint da immagine a immagine, con un corpo JSON che contiene immagine di riferimento e istruzione.
curl -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6-sunburst/image-to-image",
"image": "https://your-bucket.example.com/reference.png",
"prompt": "Repaint this scene in warm sunset tones, keep the composition and objects unchanged",
"n": 1
}'
Campo per campo: model seleziona l'endpoint; image trasporta l'immagine di riferimento (qui un URL, oppure una stringa di dati base64 se non ospiti il file); prompt è l'istruzione di modifica e deve descrivere il cambiamento, non ridefinire il soggetto; n è il numero di output desiderati. Mantieni il prompt specifico e circoscritto — istruzioni che contraddicono l'immagine di riferimento tendono a produrre risultati confusi.
Invia la richiesta e controlla il corpo della risposta. Per un endpoint asincrono non ricevi l'immagine completata; ricevi un identificatore di attività o un oggetto di stato. Salva quella risposta prima di procedere — è l'handle per tutte le operazioni successive. Un rapido controllo con curl -i mostra anche il codice di stato HTTP, il modo più rapido per distinguere un problema di autenticazione (un 4xx all'invio) da un problema di contenuto.
Eseguire la stessa chiamata in Python
Una volta che la chiamata da shell funziona, portala in Python. La libreria standard basta, ma requests rende l'esempio più leggibile:
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
payload = {
"model": "gpt-image-2.6-sunburst/image-to-image",
"image": "https://your-bucket.example.com/reference.png",
"prompt": "Repaint this scene in warm sunset tones, keep the composition and objects unchanged",
"n": 1,
}
resp = requests.post(
f"{BASE_URL}/v1/images/generations",
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
timeout=60,
)
resp.raise_for_status()
job = resp.json()
print(job)
Le differenze rispetto a curl sono meccaniche: la chiave viene da os.environ, il corpo è un dict serializzato in JSON, raise_for_status() trasforma un invio fallito in un'eccezione invece che in un errore silenzioso. L'ultima riga è importante — gran parte del dolore del debug nasce dal trattare una risposta 4xx come un successo e poi interrogare un ID attività che non è mai esistito.
Per input binari, leggi il file, codificalo in base64 e metti la stringa in image invece dell'URL. Il resto del corpo resta invariato, quindi puoi cambiare metodo senza toccare la logica della richiesta.
Gestire il ciclo di vita dell'attività asincrona
La generazione di immagini richiede tempo, quindi l'endpoint segue il modello "invia prima, interroga dopo". Comprendi i tre stati e il resto è lavoro di registrazione.
1. Inviare e catturare l'attività
La tua POST restituisce un identificatore di attività. Estrailo subito e rendilo persistente da qualche parte — una riga di database, un messaggio in coda, una riga di log interrogabile. Se il tuo processo va in crash tra l'invio e l'interrogazione, quell'identificatore è l'unica via per recuperare il lavoro che hai già pagato.
2. Interrogare finché l'attività non è completa
Interroga l'endpoint di stato con l'ID attività a intervalli regolari. Inizia in modo prudente — qualche secondo tra un controllo e l'altro — e aumenta progressivamente l'attesa per le attività più lunghe, così non martelli l'API. Fermati allo stato terminale: successo, fallimento o il timeout che hai impostato. Non interrogare mai in un ciclo serrato.
import time
def wait_for_job(job_id, base_url, api_key, timeout=300, interval=2):
deadline = time.time() + timeout
while time.time() < deadline:
r = requests.get(
f"{base_url}/v1/images/jobs/{job_id}",
headers={"Authorization": f"Bearer {api_key}"},
timeout=30,
)
r.raise_for_status()
data = r.json()
if data["status"] in ("succeeded", "failed"):
return data
time.sleep(interval)
interval = min(interval * 1.5, 15)
raise TimeoutError(f"job {job_id} not finished in time")
3. Recuperare e archiviare il risultato
In caso di successo, la risposta punta all'immagine generata. Se l'URL è temporaneo, scaricala subito e scrivila nel tuo storage con un nome che controlli, così i consumatori a valle non dipendono mai da un link temporaneo. Registra l'ID attività insieme al materiale archiviato — è l'aiuto al debug più economico che hai.
In produzione, l'interrogazione dovrebbe essere guidata da un worker in background, non dal gestore delle richieste. Una richiesta web che blocca l'intera durata della generazione di immagini è fragile e occupa connessioni inutilmente.
Errori comuni e come risolverli
Quando una chiamata fallisce, segui questa lista dall'alto verso il basso; il primo elemento intercetta la maggior parte dei problemi.
401 / 403 all'invio
Problema di autenticazione. Controlla che la chiave sia presente nell'header Authorization, che usi lo schema Bearer e che non ci siano spazi o a capo spuri da copia-incolla. Verifica che la variabile d'ambiente sia effettivamente impostata nella shell o nel processo che esegue la richiesta.
400 / 422 sul corpo della richiesta
Corpo malformato o campo errato. Cause comuni: errori di sintassi JSON dovuti a stringhe curl scritte a mano, un valore image che non è né un URL accessibile né base64 valido, un prompt mancante o un formato immagine non supportato. Valida il JSON in locale e verifica che l'immagine di riferimento si carichi davvero nel browser.
404 sul modello o sul percorso
Percorso o nome del modello scritto male. L'identificatore del modello è una stringa esatta — gpt-image-2.6-sunburst/image-to-image è diverso dalla variante da testo a immagine ed è sensibile alle maiuscole.
Timeout e interrogazioni che si bloccano
Distingui le attività lente da quelle guaste. Imposta un timeout per ogni chiamata HTTP, stabilisci una tua scadenza complessiva e, quando rinunci, registra l'ultimo stato dell'attività osservato. Se le attività superano regolarmente la tua scadenza, aumentala, invece di passare a un ciclo di retry serrato.
Output vuoto o inutilizzabile
L'attività è riuscita ma l'immagine non è quella che volevi. Di solito è un problema di prompt: l'istruzione è troppo vaga o entra in conflitto con l'immagine di riferimento. Rendi l'istruzione di modifica più specifica su ciò che deve cambiare e su ciò che deve restare invariato.
Consigli per la produzione di una pipeline da immagine a immagine
Una volta che il prototipo funziona, il lavoro rimanente riguarda affidabilità e prevedibilità.
- Riprova solo gli errori ritentabili. Usa il backoff esponenziale per gli invii falliti a causa di errori 5xx e di rete; non riprovare ciecamente i 4xx, fallirebbero di nuovo. Gestisci tu l'idempotenza legando l'attività a un tuo ID di richiesta, così i retry non duplicano il lavoro.
- Separa invio e interrogazione. Metti invio e interrogazione in worker o fasi diversi. Questo rende la latenza della tua API indipendente dal tempo di generazione e ti consente di scalare l'interrogazione in modo indipendente.
- Controlla il tuo storage. Scarica i risultati nel tuo bucket subito dopo il completamento dell'attività. Tratta l'URL restituito come un link temporaneo.
- Metti i prompt sotto controllo di versione. I prompt sono asset di produzione. Archivia prompt, immagine di riferimento e ID attività insieme a ogni output, così mesi dopo puoi riprodurre o spiegare un risultato.
- Monitora latenza e costi. Le attività di immagini vengono fatturate per output, quindi limita la concorrenza per utente e registra l'utilizzo per attività. Monitora la latenza p95 dall'invio all'archiviazione del materiale — è il numero che gli utenti percepiscono davvero.
Una volta definiti la forma della richiesta e il ciclo di vita, il resto è ingegneria ordinaria. Trovi i dettagli del modello nella documentazione HiAPI e da lì puoi collegare l'endpoint alla tua pipeline.
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