Blog

Tutoriale

Come chiamare gpt-image-2.6-flare/image-to-image tramite l'API HiAPI: curl e Python

Upload delle immagini di riferimento, richieste sincrone e asincrone e debug di una chiamata funzionante

Nov 10, 2026
Immagine di copertina: piani di cemento sfalsati che si intersecano sotto una luce solare obliqua, su un fondo grigio caldo con un'ombra blu-grigia profonda e sottili giunture color salvia.
In questa pagina

Cosa fa questo endpoint e quando usare image-to-image

I modelli text-to-image sono eccellenti nel creare scene da zero, ma molti compiti di produzione partono da un'immagine già esistente. gpt-image-2.6-flare/image-to-image è proprio l'endpoint che HiAPI offre per questo tipo di compiti: invii un'immagine di riferimento e un prompt, e il modello restituisce un'immagine trasformata che segue le tue istruzioni rimanendo saldamente ancorata all'immagine di riferimento.

Casi d'uso tipici:

  • Trasferimento di stile e ridisegno — trasformare la foto di un prodotto in un'illustrazione stilizzata, oppure ridisegnare una fotografia in un altro linguaggio visivo.
  • Modifica e ritocco — regolare illuminazione, sfondo o composizione di un materiale esistente senza doverlo riscattare.
  • Generazione di varianti — produrre più varianti visive di un design di base per test A/B o esplorazione creativa.
  • Adattamento dei materiali — ridimensionare o ricomporre un'immagine di riferimento per canali diversi mantenendone il soggetto principale.

Se il tuo compito è "descrivere qualcosa e ottenere un'immagine", text-to-image è la scelta più semplice. Usa image-to-image solo quando l'output deve derivare chiaramente da una specifica immagine di input: quella immagine di riferimento è l'intero senso della chiamata. Nel resto dell'articolo costruiremo una richiesta reale da capo a fondo: prima con curl per dimostrare che funziona, poi in Python per integrarla nel tuo servizio.

Prerequisiti e struttura della richiesta

Prima di chiamare l'endpoint, assicurati che siano pronti i seguenti elementi:

  • Un account HiAPI e una API key. La key viene inviata come bearer token nell'header Authorization. Non inserirla nei repository di codice: caricala da una variabile d'ambiente (ad esempio HIAPI_API_KEY).
  • L'id del modello. Usa esattamente gpt-image-2.6-flare/image-to-image: gli id dei modelli distinguono maiuscole e minuscole e la barra fa parte dell'identificatore.
  • Il percorso dell'endpoint. La generazione di immagini si trova sotto le rotte di generazione immagini dell'host API HiAPI. Consulta la pagina del modello per ottenere l'URL di base e il percorso correnti, invece di codificare a mano un host visto in vecchi frammenti di codice.
  • Un file immagine di riferimento in un formato comune (PNG o JPEG sono scelte predefinite sicure). Mantieni dimensioni ragionevoli: file troppo grandi rallentano l'upload e possono attivare limiti di richiesta.

Una richiesta gpt-image-2.6-flare/image-to-image contiene tre parti essenziali:

  1. Selettore del modello — indica a HiAPI a quale modello instradare la richiesta.
  2. Prompt — l'istruzione testuale che descrive la trasformazione desiderata. Non è opzionale: è il prompt a guidare la modifica.
  3. Immagine di riferimento — l'immagine di input su cui il modello deve lavorare. Come passarla dipende dal metodo di richiesta (vedi la sezione successiva).

Oltre a questi, passa solo i parametri documentati per il modello nella sua pagina HiAPI. Se ti accorgi di inventare un campo perché "sembra giusto", fermati e consulta la documentazione: i parametri sconosciuti sono una causa frequente di errori 4xx confusi.

Come passare l'immagine di riferimento

Concettualmente l'immagine di riferimento è solo un altro campo di input nel corpo della richiesta, ma le sue dimensioni la rendono speciale. Ci sono due modi pratici per inviare i byte all'API, e questa scelta influenza molto più il codice client che l'API stessa.

Metodo A: inline nel corpo della richiesta

Le immagini piccole possono essere incorporate direttamente nel payload JSON, di solito come stringa codificata in base64. Leggi il file, lo codifichi e inserisci la stringa nel campo image della richiesta. Tutto sta in una sola richiesta: ideale per miniature, icone e fixture di test.

Il prezzo da pagare: base64 gonfia il payload di circa un terzo, i codificatori JSON possono non gestire stringhe molto lunghe, e fare debug di corpi da diversi megabyte nei log è molto scomodo. L'inline è comodo, non adatto a materiali grandi.

Metodo B: prima carica, poi referenzia tramite URL

Per qualsiasi cosa più grande di una piccola immagine, carica prima il file su uno storage che controlli, poi passa il suo URL come riferimento. Il corpo della richiesta resta piccolo, i retry costano poco e la stessa immagine può essere riutilizzata in più chiamate senza ricaricarla ogni volta.

Con gli URL tieni presente alcuni punti:

  • L'URL deve essere accessibile pubblicamente dall'API: non dietro autenticazione, non su localhost, non un link firmato che scade a metà richiesta.
  • Usa un content type accettato dal modello; se l'URL restituisce HTML invece di un'immagine, la validazione fallisce.
  • Preferisci nomi di file stabili, così puoi correlare i log tra il tuo storage e le richieste HiAPI.

Qualunque metodo scegli, immagine di riferimento e prompt viaggiano nella stessa richiesta. L'API non richiede un handshake separato "prima carica, poi genera": la chiamata al modello è un'unica operazione logica.

Chiamate sincrone e asincrone

La generazione di immagini richiede tempo, ed è per questo che molte API di immagini offrono sia un metodo sincrono sia un metodo asincrono a task. Anche qui vale lo stesso compromesso.

Sincrono

Invii la richiesta e mantieni la connessione aperta finché l'immagine non torna. Il tuo codice è una linea retta: costruisci la richiesta, POST, leggi la risposta, fatto.

Usa la chiamata sincrona quando:

  • Stai facendo prototipazione o debug e vuoi vedere il risultato completo in un solo passaggio.
  • La richiesta gira in un ambiente in cui un blocco di qualche tempo è accettabile (strumenti CLI, worker in background).
  • Vuoi un client il più semplice possibile, senza logica di polling.

Lo svantaggio è che una generazione lunga significa una connessione tenuta aperta a lungo, e qualsiasi proxy o load balancer tra te e l'API può imporre i propri timeout.

Asincrono

Invii la richiesta come task, ottieni subito un identificatore del task, poi fai polling (o ricevi una callback) finché il task non è completo. Il client ha bisogno di una piccola macchina a stati: invia, attendi, recupera il risultato, gestisci il fallimento.

Usa la chiamata asincrona quando:

  • Stai servendo traffico verso utenti e non puoi permetterti di bloccare i thread delle richieste.
  • Stai generando in batch molte immagini e vuoi distribuirle in parallelo e raccogliere i risultati.
  • La tua infrastruttura ha timeout brevi sulle richieste che non controlli.

Come scegliere: se c'è una persona in attesa del risultato dentro una richiesta web, usa l'asincrono. Se uno script o un worker attende offline, il sincrono è più semplice e va bene. Non complicare troppo: parti dal sincrono e passa all'asincrono quando timeout reali o limiti di concorrenza te lo impongono.

Nel resto dell'articolo usiamo il metodo sincrono perché rende visibile ogni passaggio, ma il corpo della richiesta che costruisci è identico nelle due modalità: cambia solo l'infrastruttura attorno.

Una richiesta curl funzionante

Costruiamo la chiamata dal terminale. Prima imposta la tua key:

export HIAPI_API_KEY="your-api-key-here"

Passo 1: prepara l'immagine di riferimento

Parti da un'immagine piccola e di cui sei certo, così un fallimento non lascia ambiguità sulla causa:

ls -lh reference.png
file reference.png

file deve riportare PNG image data o JPEG image data. Se riporta altro, correggi prima di proseguire.

Passo 2: invia la richiesta

La richiesta è un POST all'endpoint di generazione immagini, con corpo JSON contenente il modello, il tuo prompt e l'immagine di riferimento. A seconda del metodo di upload scelto, il campo image è un URL oppure una stringa base64.

curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-flare/image-to-image",
    "prompt": "Recreate this scene as a flat vector illustration with a muted palette",
    "image": "https://your-storage.example.com/reference.png"
  }'

Sui parametri:

  • -sS nasconde la barra di avanzamento ma mostra gli errori: adatto agli script.
  • Authorization: Bearer $HIAPI_API_KEY evita che la chiave compaia nel comando stesso.
  • $HIAPI_BASE_URL si imposta dalla pagina del modello; non indovinare l'host.
  • Qui il campo image usa l'URL; per un'immagine inline sostituiscilo con la stringa base64.

Passo 3: leggi la risposta

Aggiungi -i per includere gli header di risposta e -w '\nHTTP %{http_code}\n' per stampare il codice di stato. Una chiamata riuscita restituisce l'immagine (o un link all'immagine, a seconda del formato della risposta) insieme ai metadati. In caso di fallimento ottieni uno stato 4xx o 5xx e un corpo di errore JSON: leggi il campo message prima di modificare qualsiasi altra cosa.

Passo 4: reindirizza l'output su file

Per ottenere un file pulito reindirizza stdout su file e controllalo di nuovo con file. Se la risposta è JSON con un URL, estrai l'URL e scaricalo con un secondo curl. Prima di collegarlo a qualsiasi automazione verifica sempre che i byte scaricati siano davvero un'immagine.

La stessa richiesta in Python

La base curl si traduce direttamente in Python. Questo esempio usa solo la libreria standard più requests:

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

payload = {
    "model": "gpt-image-2.6-flare/image-to-image",
    "prompt": "Recreate this scene as a flat vector illustration with a muted palette",
    "image": "https://your-storage.example.com/reference.png",
}

response = requests.post(
    f"{BASE_URL}/images/generations",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)

response.raise_for_status()
data = response.json()
print(data)

Gestire la risposta

Il formato della risposta varia: può contenere direttamente l'immagine oppure un URL. Scrivi una piccola funzione di supporto che unifichi i due casi, così il codice a valle non deve sapere quale sia:

def extract_image(data):
    if "url" in data:
        return requests.get(data["url"], timeout=60).content
    if "image" in data:
        import base64
        return base64.b64decode(data["image"])
    raise ValueError(f"Unexpected response shape: {list(data)}")

Gestire gli errori

Non lasciare che raise_for_status() sia la tua unica via d'errore. Avvolgi la chiamata ed esponi il messaggio di errore dell'API:

try:
    response = requests.post(url, headers=headers, json=payload, timeout=120)
    response.raise_for_status()
    image_bytes = extract_image(response.json())
except requests.HTTPError as e:
    print("HTTP", e.response.status_code, e.response.text)
    raise
except requests.Timeout:
    print("Request timed out; consider the async job route instead")
    raise

Variante asincrona

Per il metodo asincrono invia il task con lo stesso payload, leggi l'id del task dalla risposta, poi fai polling sull'endpoint di stato del task con brevi pause tra un tentativo e l'altro. Metti un limite al numero di polling e considera l'esaurimento del budget un fallimento: non fare mai polling infinito dentro un handler delle richieste.

Diagnosticare gli errori comuni

La maggior parte dei fallimenti rientra in poche categorie. Controlla questa lista nell'ordine; ogni passo isola una variabile.

Errori di autenticazione (401 / 403)

  • HIAPI_API_KEY è davvero impostata nella shell o nel processo? echo $HIAPI_API_KEY dovrebbe stamparla.
  • L'header è esattamente Authorization: Bearer <key> — A maiuscola, B maiuscola, uno spazio?
  • La key è stata revocata o ruotata? Rigenerala e riprova con una richiesta minima.

Payload dell'immagine di riferimento non valido

Questo è il fallimento più frequente, e di solito non è colpa del modello:

  • URL irraggiungibile: apri l'URL dell'immagine in un browser su un'altra rete. Se restituisce 404 o reindirizza a una pagina di login, neanche l'API può accedervi.
  • Content type errato: gli URL che restituiscono HTML o JSON vengono rifiutati. Con curl -I <url> verifica che la risposta sia Content-Type: image/....
  • File corrotto o illeggibile: esegui file reference.png in locale. Verifica che la stringa base64, una volta decodificata, produca byte identici al file originale.
  • File troppo grande: controlla i limiti di dimensione documentati nella pagina del modello; riduci le dimensioni prima di riprovare.

Formato dei parametri errato

  • Id del modello scritto male: gpt-image-2.6-flare/image-to-image deve corrispondere esattamente, barra inclusa.
  • Prompt mancante: l'istruzione testuale è obbligatoria e non può essere omessa.
  • Campi in eccesso: rimuovi qualsiasi parametro che non trovi nella documentazione. Le chiavi sconosciute spesso causano 4xx.
  • Sintassi JSON: valida il corpo della richiesta con jq . <<< "$BODY" prima di inviarlo.

Timeout

Se la richiesta si interrompe prima che l'immagine torni, la connessione è rimasta aperta troppo a lungo. Accorcia il prompt, riduci l'immagine di riferimento, aumenta il timeout del client e, se il problema persiste, passa al metodo asincrono a task: le generazioni lunghe sono esattamente il caso d'uso dell'asincrono.

Strategia di debug

Cambia un solo parametro per tentativo. Parti da un'immagine di riferimento molto piccola e verificata più un solo prompt per dimostrare che la pipeline funziona, poi introduci gradualmente gli input reali. A ogni fallimento registra il corpo completo della risposta: il campo message di solito indica direttamente quale parte della richiesta è errata.

Integrare nella tua pipeline

Una volta che la base funziona, qualche abitudine mantiene gpt-image-2.6-flare/image-to-image affidabile in produzione.

Valida gli input prima della chiamata. Controlla che l'immagine di riferimento sia in un formato supportato e entro i limiti di dimensione e, se è un URL, che sia raggiungibile. Rifiuta gli input non validi al tuo confine invece di pagare per un round trip fallito.

Valida gli output dopo la chiamata. Verifica che la risposta contenga byte di immagine reali (controlla i magic number) e non una pagina HTML di errore infilata dentro. Un controllo economico degli header risparmia molto debug confuso a valle.

Riprova con backoff, ma solo per gli errori giusti. I 5xx transitori e i timeout di rete meritano un retry con backoff esponenziale e jitter; gli errori 4xx causati da parametri non validi falliranno sempre nello stesso modo, quindi correggi la richiesta invece di ripeterla.

Preferisci l'asincrono per il lavoro rivolto agli utenti. Se qualcuno attende sulla pagina, invia un task e fai polling dal client: non tenere aperta una richiesta web per una generazione lunga.

Tieni gli id dei modelli in configurazione. Gli id dei modelli cambiano nel tempo. Leggili da un unico punto di configurazione, così cambiare modello richiede una sola riga invece di una sostituzione globale.

Combinalo con altri modelli HiAPI. Questo endpoint si sposa naturalmente con text-to-image per flussi ibridi (prima genera un'immagine di base, poi modificala) e, se la tua pipeline lo richiede, con passaggi di upscaling o rimozione dello sfondo. Poiché tutto passa attraverso la stessa interfaccia e la stessa autenticazione HiAPI, aggiungere un passaggio significa solo un'altra chiamata con la stessa key.

Parti dalla base curl, porta il codice in Python e passa all'asincrono quando il traffico lo richiede. La pagina del modello fornisce i parametri di richiesta e i limiti correnti: consultala prima di dare per scontato un nome di campo o un limite di dimensione.

Inizia a creare con artefatti IA persistenti

Ottieni la tua chiave API e chiama modelli di immagini, video e audio tramite un'unica API basata sui task.

Leggi la documentazione API