Come usare l'API GPT Image 2: guida alla generazione di immagini da testo e da immagine

Cosa offre l'API GPT Image 2 agli sviluppatori

L'API GPT Image 2 ti offre un'interfaccia unificata e coerente per generare immagini a partire da un prompt. Non devi assemblare più fornitori né mantenere più SDK: basta inviare una singola richiesta HTTP a HiAPI.ai per ottenere i dati dell'immagine. Questo è importante quando costruisci funzionalità come generatori di materiali di marketing, illustrazioni per l'onboarding di un'app o strumenti creativi rivolti agli utenti, perché latenza, uptime e una struttura di richiesta prevedibile sono fondamentali.

Utilizzerai due modalità di generazione:

• Testo-immagine: fornisci un prompt e una dimensione target, e il modello genera l'immagine da zero.
• Immagine-immagine: fornisci un prompt più una o più immagini di riferimento, e il modello genera l'immagine guidato da tali riferimenti.

Entrambe le modalità condividono la stessa autenticazione e la stessa struttura di risposta, quindi una volta che hai una chiamata funzionante, la seconda è solo una piccola modifica, non un'integrazione da zero. Questa guida illustra in sequenza come scegliere tra le due varianti, una richiesta curl minima, la gestione delle immagini di riferimento, la richiesta di output 4K, il porting in Python e i pattern di gestione degli errori che evitano fallimenti silenziosi in una pipeline di immagini in produzione.

Se stai costruendo qualsiasi funzionalità che richieda la generazione di immagini tramite un contratto API stabile, il resto di questo articolo è il percorso più breve da zero a una richiesta funzionante.

Testo-immagine e immagine-immagine: scegliere la variante

Prima di scrivere codice, determina quale variante serve effettivamente al tuo prodotto. La scelta dipende principalmente da quanto controllo vuoi sull'output e da quanto contenuto ti aspetti che gli utenti forniscano.

Quando usare testo-immagine

Testo-immagine è la scelta predefinita appropriata quando:

• Gli utenti descrivono a parole ciò che vogliono, senza materiale di partenza.
• Devi generare immagini segnaposto, key visual o varianti basate su un template di prompt fisso.
• Vuoi un corpo della richiesta il più semplice possibile — un prompt e una dimensione — per mantenere la richiesta compatta e la latenza prevedibile.

Quando usare immagine-immagine

Immagine-immagine è la scelta giusta quando l'output deve restare vicino a qualcosa che esiste già:

• Ristilizzare o renderizzare di nuovo foto di prodotti caricate.
• Applicare un trattamento visivo coerente su un insieme di materiali di riferimento.
• Guidare composizione, palette o soggetto affinché il risultato corrisponda a un brand o a una scena esistente.

Regola pratica

Se il solo prompt può determinare completamente l'output, usa testo-immagine. Se parte dell'intento risiede nell'immagine e non nel testo — e descriverlo a parole sarebbe limitante, prolisso o inaffidabile — usa immagine-immagine e passa le immagini di riferimento.

Un errore comune è ricorrere a immagine-immagine quando un prompt migliore risolverebbe la questione. Le immagini di riferimento aggiungono overhead di upload e aumentano le possibilità di fallimenti nella validazione della richiesta. Inizia con testo-immagine e passa alla variante con riferimento solo quando riesci a indicare un attributo visivo specifico che il prompt non riesce a catturare.

Inviare la prima richiesta testo-immagine con curl

Inizia con curl. Elimina la variabile del comportamento dell'SDK, così quando qualcosa fallisce puoi essere certo che il problema risieda nell'autenticazione o nella struttura della richiesta, non nella libreria client.

Imposta prima la chiave API come variabile d'ambiente, così non finisce nella cronologia della shell né nel controllo di versione:

export HIAPI_API_KEY="your_api_key_here"

Poi invia una richiesta minima:

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A flat-design illustration of a lighthouse at dusk, soft gradient sky, minimal palette",
    "size": "1024x1024"
  }'

Cosa controllare nella risposta:

1. Codice di stato HTTP.200 significa che la richiesta è stata accettata ed elaborata. Per qualsiasi altro codice, leggi prima il corpo della risposta di errore prima di modificare qualcosa.
2. Autenticazione.401 indica quasi sempre che la chiave è mancante, malformata o scaduta — verifica che l'intestazione Authorization abbia il formato Bearer seguito dalla chiave.
3. Corpo della richiesta.400 di solito indica un campo specifico: un parametro scritto male, una stringa di dimensione non accettata dal modello o un prompt che non supera la validazione.
4. Payload dell'immagine.A seconda della modalità di risposta, otterrai un URL scaricabile o dati immagine in base64. Gestisci entrambi, così il tuo client non sarà colto impreparato in futuro.

Una volta che questa chiamata riesce, hai verificato tre cose contemporaneamente: la chiave è valida, il percorso dell'endpoint è corretto e la struttura JSON è accettabile. Ogni modifica successiva in questa guida parte da questa base nota e funzionante.

Guidare l'output con le immagini di riferimento

Le richieste immagine-immagine mantengono lo stesso involucro della richiesta testo-immagine e aggiungono un input di immagine di riferimento. Il prompt porta ancora le istruzioni — le immagini di riferimento portano il contesto visivo.

La differenza nel corpo della richiesta è che ora fornisci i dati dell'immagine oltre al prompt. In pratica, questo significa fornire un URL che il servizio può scaricare oppure un'immagine codificata in base64 inline, a seconda di quale forma supporta la tua integrazione. Tieni presenti le seguenti regole:

• Prompt e immagini di riferimento devono essere coerenti.Se il prompt descrive un prodotto rosso mentre l'immagine di riferimento è blu, il modello riceve segnali contraddittori. Scrivi il prompt come istruzione sull'immagine di riferimento ("ridipingi questa scena in stile acquerello"), non come descrizione che la contraddice.
• Invia solo ciò che serve.Una singola immagine di riferimento forte è di solito meglio di più riferimenti deboli. Più immagini di riferimento aumentano il volume di upload e rendono più difficile capire quale abbia guidato l'output.
• Attenzione al volume della richiesta.Le immagini codificate in base64 gonfiano notevolmente il payload. Se carichi foto grandi, è il primo punto da controllare quando una richiesta diventa lenta o viene rifiutata.
• Valida prima di inviare.Verifica che l'immagine sia in un formato supportato e che si decodifichi correttamente. Una stringa base64 malformata produce fallimenti incomprensibili e dispendiosi da diagnosticare.

La struttura della richiesta utilizzabile è la seguente:

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Restyle this scene as a soft watercolor painting, keep composition intact",
    "image": "https://example.com/reference.jpg",
    "size": "1024x1024"
  }'

Poiché l'involucro della richiesta non cambia, la chiamata curl che hai già verificato resta il tuo strumento di debug: sostituisci il corpo, mantieni le intestazioni, confronta le risposte campo per campo.

Richiedere output 4K

La risoluzione dell'output viene specificata nella richiesta, non presunta dal modello. Se ti serve un output ad alta risoluzione, indicalo esplicitamente con il parametro size — non aspettarti che il valore predefinito sia grande.

{
  "model": "gpt-image-2",
  "prompt": "A detailed isometric illustration of a city block, warm evening light",
  "size": "3840x2160"
}

Quando passi a risoluzioni più elevate, verifica quanto segue:

• Stringhe di dimensione supportate.I valori di dimensione vengono validati in base all'intervallo accettato dal modello. Una dimensione rifiutata restituisce 400, non una degradazione silenziosa — quindi conferma la stringa di dimensione esatta richiesta invece di indovinare un valore vicino ma errato.
• Volume della risposta.I dati di un'immagine 4K sono molto più grandi di quelli di un risultato 1K. Se la risposta trasporta base64 o un URL che scaricherai subito, prevedi un budget adeguato in memoria e nei timeout.
• Latenza.La generazione a risoluzione più alta richiede più tempo. Imposta timeout client generosi, invece di lasciare che una richiesta lenta ma destinata a riuscire vada in timeout dalla tua parte.
• Modello di costo.La fatturazione dipende dalla dimensione e dal numero di output richiesti, quindi scegli consapevolmente: genera alla risoluzione effettivamente necessaria alla funzionalità e, se l'interfaccia utente non richiede la risoluzione piena, ridimensiona nella tua pipeline. I prezzi attuali sono nel pannello prezzi del sito.
• Upscaling con cautela.Se ti serve un output più grande di quello che il modello produce, l'upscaling dopo la generazione è un passaggio separato con i propri compromessi di qualità. Decidi consapevolmente quale percorso seguire.

Prima di collegare il 4K a un job batch, testa il 4K con un prompt noto e funzionante, così i fallimenti legati alla risoluzione non si confondono con problemi di autenticazione o del corpo della richiesta.

Portare la richiesta in Python

Non riscrivere la richiesta da zero in Python. Porta lo stesso corpo della richiesta che hai già verificato in curl, poi conferma separatamente la gestione della risposta.

import os
import base64
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/images/generations"

payload = {
    "model": "gpt-image-2",
    "prompt": "A flat-design illustration of a lighthouse at dusk, soft gradient sky, minimal palette",
    "size": "1024x1024",
}

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

item = data["data"][0]
if item.get("b64_json"):
    image_bytes = base64.b64decode(item["b64_json"])
    with open("output.png", "wb") as f:
        f.write(image_bytes)
else:
    image_url = item["url"]
    image_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(image_bytes)

Note sul porting:

• Mantieni la chiave nelle variabili d'ambiente, esattamente come in curl. Non inserirla mai inline.
• Imposta timeout espliciti.La generazione di immagini è più lenta di una tipica chiamata API JSON; usare i timeout brevi predefiniti è una causa comune di falsi fallimenti.
• Gestisci entrambe le modalità di risposta.Ramificare in base a b64_json e url fa funzionare il codice indipendentemente da come è configurata la risposta.
• Riusa la funzione.Incapsula questa parte in un piccolo helper generate_image(prompt, size), così testo-immagine e immagine-immagine differiscono solo per il campo opzionale image nel payload.

Poiché il dizionario payload è lo stesso oggetto che hai testato in curl, qualsiasi cambiamento di comportamento osservato in Python deriva quasi certamente dal lato client — intestazioni, codifica o timeout — il che restringe notevolmente il debug.

Gestire gli errori e validare le risposte

La generazione di immagini è per natura una chiamata soggetta a fallimenti: è più lenta della maggior parte degli endpoint API, trasporta payload grandi e dipende dalla disponibilità del modello. Trattala come un'operazione che ogni tanto fallisce e va ritentata, non come un'operazione una tantum.

Checklist della risposta

1. Controlla lo stato prima di analizzare.Chiama raise_for_status() o controlla il codice di stato e leggi il corpo della risposta di errore — di solito indica il campo problematico.
2. Valida la struttura.Prima di accedere per indice, conferma che data esista e non sia vuoto. Non dare per scontato che data[0] esista.
3. Verifica i byte dell'immagine.Dopo la decodifica, controlla che l'output non sia vuoto e inizi con una firma di immagine valida. Un file di zero byte è un fallimento silenzioso che emerge solo molto più tardi.
4. Registra l'ID della richiesta.Conserva nei log l'identificatore della richiesta della risposta, così una generazione fallita può essere tracciata senza riprodurla.

Strategia di retry

• Ritenta solo i fallimenti temporanei.Timeout, reset di connessione e risposte 5xx meritano un retry.401 o 400 falliranno allo stesso modo ogni volta — correggi la richiesta, non ritentarla.
• Usa un backoff esponenziale con jitter.Inizia con un ritardo breve e aumentalo progressivamente; il jitter evita che un gruppo di worker ritenti in sincrono.
• Limita il numero di tentativi.Di solito due o tre retry sono sufficienti. Oltre, esponi l'errore all'utente o sposta il job su un percorso di dead letter.
• Rendila idempotente.Poiché i retry possono produrre generazioni duplicate, associa il risultato all'ID del job originale, così i retry non addebiteranno mai due volte un'azione visibile all'utente.

Adattarla all'asincrono

La generazione ad alta risoluzione richiede tempo, quindi se la tua architettura lo consente, non tenere occupato il thread della richiesta. Metti il job in coda, restituisci un ID job al chiamante e lascia che i worker eseguano la chiamata con la strategia di retry descritta sopra. Così il tuo livello web resta reattivo e il lavoro lento e soggetto a errori è confinato dove i retry costano poco.

Integra questi controlli fin dalla prima chiamata funzionante, non dopo il primo incidente in produzione — il costo di un piccolo helper di validazione è molto inferiore a quello di fare debug su un file immagine vuoto tre settimane dopo. Quando autenticazione, struttura della richiesta, risoluzione e retry sono tutti confermati, l'API GPT Image 2 diventa un mattone affidabile, non un'integrazione buona solo per le demo.