Come chiamare gpt-image-2.5-sunburst/text-to-image tramite l'API HiAPI: curl e Python

Cosa offre questo endpoint modello

gpt-image-2.5-sunburst/text-to-image è un modello di generazione di immagini esposto tramite l'API unificata HiAPI. Lo si richiama tramite l'ID modello, inviando il prompt in un corpo richiesta con la stessa forma di chat-completions usata per i modelli testuali, per poi ottenere i dati dell'immagine generata nella risposta.

L'impatto pratico è questo: se il tuo codice gestisce già il testo tramite HiAPI, non serve un secondo SDK, né uno schema di autenticazione separato, né imparare una nuova famiglia di endpoint. L'unica cosa che cambia è l'ID modello.

Scegli questo endpoint quando il tuo compito è la generazione da prompt a immagine, ovvero creare nuove immagini da una descrizione testuale, facoltativamente guidate da immagini di riferimento fornite nella richiesta. Se devi analizzare o descrivere immagini esistenti anziché generarle, è più adatto un modello di chat con capacità visive; lascia la generazione di immagini a questo endpoint e la comprensione delle immagini altrove.

Un'aspettativa da fissare subito: le chiamate per immagini sono più lente delle completamenti testuali. Tempi di risposta nell'ordine di alcuni secondi sono normali; il timeout del client va calibrato su questa realtà, non ereditato da una configurazione pensata per il solo testo.

Prima di inviare la prima richiesta

Servono tre cose.

Una chiave API

Crea una chiave nel tuo account HiAPI e conservala come variabile d'ambiente, non scritta nel codice sorgente:

export HIAPI_API_KEY="your-key-here"

L'ID modello esatto

La stringa è gpt-image-2.5-sunburst/text-to-image. Trattala come un identificatore opaco: copiala, non ridigitarla a memoria. La barra fa parte dell'ID. Un errore di battitura qui è la causa più comune di fallimento alla prima chiamata, e si manifesta come errore di modello non trovato, non come problema di payload.

Un client in grado di effettuare richieste HTTPS

Per la prima verifica basta curl, preinstallato sulla maggior parte dei sistemi. Per il codice applicativo è sufficiente Python con la libreria requests (o qualsiasi client HTTP). Questo endpoint non richiede librerie dedicate alle immagini lato client; si invia JSON e si rilegge JSON.

Prima della prima chiamata di solo testo non devi precaricare immagini né configurare storage. Parti dalla richiesta minimale qui sotto e aggiungi le immagini di riferimento solo dopo che il round-trip di base funziona.

Una richiesta minimale funzionante con curl

Questa è la chiamata corretta minimale:

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "messages": [
      {
        "role": "user",
        "content": "A sunlit coastal cliff at golden hour, wide angle, high detail"
      }
    ]
  }'

Spiegazione campo per campo:

• URL: il percorso standard chat-completions di HiAPI. I modelli per immagini usano lo stesso routing dei modelli testuali.
• Authorization: token bearer con la chiave API. Se questo header è malformato, ricevi un 401 prima ancora di raggiungere il modello.
• Content-Type: deve essere application/json.
• model: l'ID modello esatto della sezione precedente.
• messages: l'array standard di oggetti role/content. Il tuo prompt è il content del messaggio user.

In caso di successo ricevi una risposta JSON contenente i dati dell'immagine generata insieme ai consueti metadati di completamento. Salva prima la risposta grezza su file, controllala, poi collega la logica di parsing allo script:

curl -sS ... -o response.json

Una volta che questa restituisce un'immagine, le tue credenziali e la forma del payload sono corrette, e tutti i problemi successivi riguardano la logica applicativa, non la configurazione.

Scrivere la stessa richiesta in Python

La convenzione della richiesta resta invariata: cambiano solo l'impostazione del client, i timeout e la gestione della risposta.

import os
import requests

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

payload = {
    "model": "gpt-image-2.5-sunburst/text-to-image",
    "messages": [
        {
            "role": "user",
            "content": "A sunlit coastal cliff at golden hour, wide angle, high detail",
        }
    ],
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=(10, 180),  # connect, read
)

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

Tre dettagli da notare:

Il timeout è esplicito e asimmetrico

La tupla (10, 180) imposta un timeout di connessione breve e un timeout di lettura più tollerante. La generazione di immagini richiede naturalmente tempo; un timeout unico e piatto copiato da un client testuale produce falsi fallimenti. Mantieni breve il timeout di connessione, così i problemi di rete falliscono rapidamente.

Usa json=payload invece di data=

Passare un dizionario tramite json= gestisce la serializzazione e imposta il content type per te. Se passi una stringa già serializzata con data=, imposta l'header manualmente.

Parsing difensivo

La risposta è JSON; prima di accedere agli indici, registra l'intero corpo della risposta in caso di forma inattesa. Non presumere una profondità di annidamento fissa prima di aver visto una risposta reale, e non presumere mai una forma di successo per stati non 2xx.

Se preferisci una libreria client configurata per HiAPI, il payload inviato è identico; cambia solo il punto di chiamata.

Passare correttamente le immagini di riferimento

Le immagini di riferimento vanno fornite all'interno del contenuto del messaggio, non come campo temporaneo di primo livello. È la parte dell'integrazione in cui è più facile sbagliare in modo sottile, perché un riferimento malformato spesso non genera errore: la richiesta va a buon fine e l'output ignora la tua immagine.

Mantieni coerente la struttura del payload tra linguaggi: il messaggio user contiene un array di contenuti, in cui la parte testuale porta il prompt e la parte immagine porta i dati di riferimento. Lo stesso corpo richiesta JSON che costruisci in Python deve poter essere espresso byte per byte in curl; se non riesci a scrivere l'equivalente curl del payload Python, la struttura è andata alla deriva.

Quando il risultato sembra ignorare la tua immagine di riferimento, controlla in questo ordine:

1. Posizione. La parte immagine è dentro messages[].content o è finita per errore al primo livello del corpo richiesta? Il modello vede solo ciò che è nei messaggi.
2. Codifica. L'immagine di riferimento viaggia nella richiesta come dati codificati. Verifica che i dati siano integri e nel formato corretto, non troncati da concatenazioni manuali o da un copia-incolla maldestro.
3. Accoppiamento con il prompt. L'immagine di riferimento guida la generazione; non sostituisce le istruzioni. Indica esplicitamente il ruolo dell'immagine (stile, composizione, soggetto) invece di dare per scontato che il modello lo deduca.
4. Dimensione. Riferimenti molto grandi gonfiano la richiesta e rallentano il round-trip. Ridimensionali prima della codifica alla misura effettivamente necessaria al compito.

Una buona abitudine di debug

Costruisci una volta un payload con immagine di riferimento, salva il corpo richiesta JSON esatto che funziona e riutilizzalo come campione fisso. Quando in seguito una chiamata si comporta in modo anomalo, confronta per differenze il corpo attuale con il campione fisso. La maggior parte delle regressioni sulle immagini di riferimento è strutturale, e un diff le individua in pochi secondi.

Gestire errori, timeout e tentativi

Gli endpoint per immagini falliscono in modo diverso da quelli testuali: sono più lenti, quindi più chiamate ricadono nella finestra attivata dai timeout, e riprovare alla cieca costa di più perché il lavoro è più pesante.

Distinguere errori del client da fallimenti transitori

• 4xx (tranne 429): payload malformato, ID modello errato, autenticazione mancante. Ripetere la stessa richiesta fallirà allo stesso modo. Correggi la richiesta.
• 401/403: problemi di credenziali. Controlla la chiave e il formato dell'header Authorization.
• 429: richieste limitate. Riprova, ma con backoff e jitter, non immediatamente.
• 5xx ed errori di connessione: transitori. Riprova.
• Timeout di lettura: ambiguo: la generazione potrebbe essersi già completata lato server. Considera il timeout ritentabile solo se il tuo flusso di lavoro tollera possibili duplicati.

Riprova solo ciò che è sicuro

Usa un backoff esponenziale con jitter e un limite basso al numero di tentativi: tre di solito bastano. Un pattern semplice:

import time, random

def post_with_retry(session, url, payload, attempts=3):
    for i in range(attempts):
        try:
            r = session.post(url, json=payload, timeout=(10, 180))
            if r.status_code == 429 or r.status_code >= 500:
                raise RuntimeError(f"retryable: {r.status_code}")
            r.raise_for_status()
            return r.json()
        except (RuntimeError, requests.ConnectionError, requests.Timeout):
            if i == attempts - 1:
                raise
            time.sleep((2 ** i) + random.random())

Non ritentare gli errori di payload 4xx dentro questo ciclo: esponili subito, così una richiesta errata fallisce in modo evidente invece di consumare tentativi.

Dimensionare i timeout in base al modello

Il timeout di lettura impostato per le chiamate alle immagini dovrebbe essere alcune volte il valore predefinito per il testo, e va impostato per singola chiamata anziché globalmente, per non penalizzare il traffico testuale. Se la tua piattaforma ha un limite massimo rigido di richieste, mantieni prompt di generazione e immagini di riferimento entro un budget che riesci effettivamente a rispettare.

Checklist di produzione prima del rilascio

Una checklist breve che previene la maggior parte degli incidenti:

• ID modello in un solo punto. Definisci gpt-image-2.5-sunburst/text-to-image come costante o valore di configurazione, non come stringhe letterali sparse.
• Chiave da variabile d'ambiente, mai committata. Ruotala come qualsiasi altro segreto.
• Timeout espliciti, con una finestra di lettura tollerante, impostati sulla richiesta e non come valori predefiniti della sessione.
• Retry solo su 429/5xx/timeout, con backoff e jitter, e numero di tentativi limitato.
• Registra la risposta completa in caso di fallimento: prima del parsing registra stato, corpo della risposta e request ID, così il supporto parte dalle evidenze.
• Conserva campioni fissi di payload funzionanti, sia per il caso standard sia per quello con immagine di riferimento, da usare nei diff quando il comportamento cambia.
• Immagini di riferimento dentro il contenuto del messaggio, ridimensionate in base al compito, con il loro ruolo esplicitato nel prompt.
• Smoke test in CI che effettui una chiamata reale all'ID modello, così un modello rinominato o ritirato emerge prima che lo scoprano gli utenti.

Nessuna di queste abitudini è specifica della generazione di immagini, ma ciascuna affronta modalità di fallimento che le chiamate alle immagini incontrano più spesso di quelle testuali. Impostale una volta e l'endpoint si comporterà come qualsiasi altra parte del tuo stack. Per i parametri e i limiti attuali del modello, consulta la pagina del modello su HiAPI prima di finalizzare la configurazione.