Blog

Tutoriale

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

Autenticazione, struttura della richiesta, esempi curl e Python eseguibili e risoluzione dei problemi

Nov 10, 2026
Copertina: sezione trasversale di minerale piatto e sfaccettato in verde acqua e malachite su blu petrolio profondo, come una tavola stampata di gemmologia.
In questa pagina

Come appare questa integrazione end-to-end

Ogni chiamata di generazione di immagini da testo su HiAPI segue lo stesso ciclo di vita, e vale la pena comprenderlo prima di scrivere qualsiasi codice. La tua applicazione costruisce una richiesta JSON che descrive l'immagine desiderata, la invia insieme alle credenziali API all'endpoint HiAPI corrispondente a gpt-image-2.6-sunburst/text-to-image, e riceve una risposta contenente i dati dell'immagine generata o un URL da cui recuperarla. Una volta comprese queste tre fasi, il resto della guida è solo un approfondimento dei dettagli.

Le fasi sono suddivise così:

  1. Autenticazione — allega la tua API key HiAPI alla richiesta, di solito sotto forma di header HTTP. Non è necessario negoziare un token per ogni chiamata.
  2. Costruzione della richiesta — assembla un corpo JSON contenente il tuo prompt e, facoltativamente, parametri come dimensione e numero di immagini.
  3. Trasporto — invia il corpo tramite POST all'endpoint. La chiamata è sincrona, quindi il client attende il completamento della generazione dell'immagine.
  4. Gestione della risposta — l'API restituisce JSON strutturato. A seconda della configurazione dell'endpoint, i dati dell'immagine arrivano come URL oppure come contenuto immagine codificato, che devi decodificare e scrivere su disco.

Un dettaglio da notare subito: l'identificatore del modello gpt-image-2.6-sunburst/text-to-image contiene una barra. Trattalo come una stringa opaca. Non tentare di dividerlo in nome del provider e nome del modello, e non eseguire codifica URL o normalizzazione di tua iniziativa. Copialo esattamente come appare nella documentazione e inseriscilo in un unico punto del codice, così non dovrai più cercarlo in futuro.

Le sezioni seguenti illustrano ogni fase in ordine. Le parti relative a curl e Python usano deliberatamente lo stesso payload della richiesta, così puoi confrontarle riga per riga; la sezione di risoluzione dei problemi mappa invece gli errori più probabili ai campi specifici della richiesta da correggere.

Autenticare le richieste HiAPI

HiAPI utilizza uno schema di autenticazione basato su API key. Ottieni la chiave dalla dashboard del tuo account e la invii a ogni richiesta. La forma standard è un header HTTP sulla richiesta:

Authorization: Bearer YOUR_API_KEY

Alcuni client preferiscono inviare la chiave in un header dedicato, ma a meno che la documentazione del tuo account non indichi diversamente, usa il formato Authorization: Bearer, perché è compatibile fin da subito con la maggior parte degli strumenti HTTP.

Tenere la chiave fuori dal codice sorgente

L'errore di sicurezza più comune durante la prima integrazione è codificare la chiave direttamente nello script e fare commit. Evitalo fin dal primo giorno:

  • Leggi la chiave da una variabile d'ambiente, ad esempio HIAPI_API_KEY, e se la variabile manca, interrompi subito l'avvio.
  • Prima di creare un file .env locale, aggiungilo a .gitignore.
  • In CI o in produzione, inietta la chiave dall'archivio segreti della piattaforma, non leggendola da un file sottoposto a commit.

Una piccola funzione di supporto che legge la chiave una sola volta e genera un errore chiaro se manca ti risparmierà in futuro un debugging confuso:

import os

api_key = os.environ.get("HIAPI_API_KEY")
if not api_key:
    raise RuntimeError("HIAPI_API_KEY is not set")

Trattare la chiave come segreta anche durante le richieste

Quando diagnostichi chiamate non riuscite, non cedere alla tentazione di stampare l'intero oggetto della richiesta, header inclusi. Registra invece endpoint, identificatore del modello e codice di stato. Se devi acquisire gli header per il debug, offusca prima il valore di Authorization. Una chiave finita in un aggregatore di log è esposta tanto quanto una chiave inserita in un repository di codice.

Se ruoti la chiave, quella vecchia diventa immediatamente invalida al termine della rotazione, quindi pianifica la rotazione come operazione periodica, non come emergenza.

Anatomia di una richiesta di generazione di immagini da testo

Il corpo della richiesta è un oggetto JSON. Per gpt-image-2.6-sunburst/text-to-image i campi principali sono pochi, ed è proprio per questo che vale la pena capire esattamente cosa fa ciascun campo, invece di copiare il payload alla cieca.

Il campo model

"model": "gpt-image-2.6-sunburst/text-to-image"

Questo campo seleziona il modello ed è obbligatorio. Mantieni la stringa identica byte per byte all'identificatore della documentazione. Una barra mancante, uno spazio in più o un cambio di maiuscole/minuscole faranno rifiutare la richiesta come modello sconosciuto.

Il campo prompt

"prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus"

Questa è la descrizione in linguaggio naturale dell'immagine, obbligatoria. Consigli pratici sul prompt stesso:

  • Scrivi prima il soggetto, poi la scena, infine gli indizi di stile o illuminazione.
  • Preferisci nomi concreti a concetti astratti; "una tazza di ceramica rossa su un tavolo di legno" batte "una bella scena con una tazza".
  • Se devi mantenere una coerenza di output tra più chiamate, mantieni stabile la formulazione delle parti non variabili e sostituisci solo le parti variabili via codice.

Parametri facoltativi

A seconda dell'endpoint, puoi anche inviare parametri che controllano la forma e la quantità dell'output, i più comuni dei quali sono:

  • size — dimensioni di output, espresse nel formato previsto dalla documentazione, ad esempio 1024x1024. Se omesso, si applica il valore predefinito; se invii un valore non supportato, aspettati un errore di validazione.
  • n — numero di immagini generate per un prompt. Ogni immagine generata viene addebitata separatamente, quindi mantienilo al minimo necessario per il tuo flusso di lavoro.

Invia solo i parametri di cui hai davvero bisogno. Campi sconosciuti possono causare errori di validazione severi che puntano a un campo che non intendevi affatto inviare.

Un esempio completo di corpo della richiesta

{
  "model": "gpt-image-2.6-sunburst/text-to-image",
  "prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
  "size": "1024x1024",
  "n": 1
}

Questo è l'intero contratto. Tutto il resto in questa guida riguarda il trasporto, la gestione degli errori e il ciclo di vita di questo payload.

Inviare una richiesta funzionante con curl

Prima di costruire il client Python, verifica con curl che endpoint e credenziali funzionino. Questo isola i problemi di autenticazione da quelli del codice.

Il comando di chiamata

curl -sS -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.6-sunburst/text-to-image",
    "prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
    "size": "1024x1024",
    "n": 1
  }'

Alcune note su questi flag:

  • -sS mantiene l'output pulito pur continuando a mostrare gli errori di trasporto.
  • -X POST specifica il metodo; il corpo viene passato tramite -d.
  • Gli apici singoli attorno al corpo JSON impediscono alla shell di alterarlo. In cmd di Windows le regole per le virgolette JSON sono diverse, quindi usa curl.exe con virgolette doppie ed esegui l'escape delle virgolette interne, oppure esegui la chiamata da uno script shell o da Python.

Se utilizzi il percorso esatto dell'endpoint indicato nella documentazione del tuo account, sostituiscilo qui; la forma della richiesta non cambia.

Ispezionare la risposta grezza

Quando qualcosa va storto, ti servono il codice di stato e il corpo della risposta. Aggiungi -i per includere gli header di risposta, oppure -w "\nHTTP %{http_code}\n" per stampare lo stato alla fine:

curl -sS -o response.json -w "HTTP %{http_code}\n" -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json

Salvare il payload in payload.json e referenziarlo tramite @payload.json vale la pena: eviti errori di quoting della shell e puoi modificare il prompt senza riscrivere il comando. Se il prompt contiene testo sensibile, escludi quel file dal controllo versione.

Effettuare la stessa chiamata con Python

La versione Python mantiene il corpo JSON identico byte per byte. Cambia solo il trasporto. Usare requests aggiunge una dipendenza, ma mantiene il codice leggibile; vale la pena installarlo per qualsiasi uso che vada oltre uno script temporaneo.

import os
import requests

api_key = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "gpt-image-2.6-sunburst/text-to-image",
    "prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
    "size": "1024x1024",
    "n": 1,
}

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

response = requests.post(
    "https://api.hiapi.ai/v1/images/generations",
    headers=headers,
    json=payload,
    timeout=120,
)

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

Perché usare json=payload invece di data=json.dumps(payload): passare il dict al parametro keyword json lo serializza e imposta automaticamente l'header Content-Type. Passare una stringa a data funziona, ma è facile dimenticare di impostare l'header, cosa che in seguito si manifesta come un errore di validazione confuso.

Se preferisci usare la libreria standard

Per evitare dipendenze, puoi usare urllib.request della libreria standard. Il dizionario del payload resta invariato:

import json, os, urllib.request

payload = {
    "model": "gpt-image-2.6-sunburst/text-to-image",
    "prompt": "A sunlit alpine meadow at golden hour, wildflowers in the foreground, sharp focus",
}

request = urllib.request.Request(
    "https://api.hiapi.ai/v1/images/generations",
    method="POST",
    headers={
        "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    data=json.dumps(payload).encode("utf-8"),
)

with urllib.request.urlopen(request, timeout=120) as response:
    data = json.loads(response.read().decode("utf-8"))

In entrambi i casi, la generazione di immagini è più lenta di una tipica chiamata API JSON. Imposta timeout ampi, altrimenti andrai in timeout su una richiesta quasi riuscita e la pagherai due volte al tentativo successivo.

Gestire la risposta e salvare le immagini

Una risposta riuscita è JSON. L'output dell'immagine arriva solitamente come URL (che devi recuperare separatamente) oppure come contenuto immagine codificato nel payload. Consulta la documentazione dell'endpoint per confermare quale forma si applica, poi gestisci entrambe le forme in modo difensivo, perché la forma esatta può variare al cambiare dei parametri.

Leggere la struttura della risposta

La risposta è un oggetto JSON contenente l'output generato e i metadati. Ispezionalo una volta in modo interattivo prima di scrivere il codice di parsing:

print(json.dumps(data, indent=2)[:2000])

Individua dove si trova l'immagine. Se vedi un campo URL, scaricalo. Se vedi contenuto base64, decodificalo. Evita di assumere che l'URL sia valido in modo permanente: trattalo come di breve durata e copia subito i byte nel tuo storage.

Salvare risultati basati su URL

image_url = data["data"][0]["url"]
img = requests.get(image_url, timeout=60)
img.raise_for_status()
with open("output.png", "wb") as f:
    f.write(img.content)

Salvare risultati codificati

import base64

encoded = data["data"][0].get("b64_json") or data["data"][0].get("image")
if encoded:
    with open("output.png", "wb") as f:
        f.write(base64.b64decode(encoded))

In carichi di lavoro reali, usa un nome file diverso per ogni chiamata — timestamp, ID richiesta o uno slug derivato dal prompt. Se prevedi di rigenerare o verificare gli output in seguito, salva il prompt insieme all'immagine in un file JSON sidecar.

Gestire la risposta di successo in un unico punto

Incapsula il parsing della risposta in una funzione che restituisce un elenco di stringhe di byte, una per immagine. In questo modo ogni chiamante deve solo scrivere o caricare i byte, senza sapere se provengono da un URL o da contenuto codificato. Questa astrazione ripaga quando in futuro cambi modello.

Diagnosticare gli errori comuni

La maggior parte dei fallimenti nella prima integrazione rientra in poche categorie. Prima di modificare qualsiasi altra cosa, abbina il codice di stato e il messaggio alla soluzione indicata di seguito.

Errori di autenticazione

Una richiesta rifiutata per credenziali mancanti o non valide significa che l'header Authorization manca, è malformato o contiene una chiave revocata. Controlla in questo ordine:

  1. Verifica il nome dell'header e il formato del valore, incluso il termine letterale Bearer seguito da uno spazio.
  2. Verifica che la variabile d'ambiente sia effettivamente popolata nella shell o nel processo che esegue la chiamata — una chiave impostata in un terminale non esiste in un altro.
  3. Verifica che la chiave non sia stata ruotata o troncata durante la copia.

Errori di validazione del corpo della richiesta

L'API rifiuta i corpi che mancano campi obbligatori o contengono valori non validi. Il messaggio di solito indica il campo problematico:

  • model o prompt mancanti — entrambi sono obbligatori. Inviali esplicitamente a ogni chiamata, invece di affidarti ai valori predefiniti.
  • Modello sconosciuto — ricontrolla l'identificatore gpt-image-2.6-sunburst/text-to-image, inclusa la barra e le maiuscole/minuscole. Non inserire spazi bianchi attorno ad esso.
  • Dimensione non valida — usa una stringa di dimensione supportata nel formato previsto dalla documentazione. Se ometti intenzionalmente size, rimuovilo invece di inviare null.
  • JSON malformato — di solito è un problema di quoting della shell in curl o di codifica delle stringhe in Python. Prima dell'invio, verifica con json.dumps(payload) e controlla cosa viene effettivamente trasmesso.

Limiti di frequenza e quota

Se ricevi una risposta di throttling, fai un backoff e riprova con jitter, invece di riprovare immediatamente. Se il messaggio indica un problema di quota, controlla il piano e il pannello di utilizzo dell'account, non il corpo della richiesta — il payload è probabilmente corretto.

Errori del server

Gli errori 5xx durante la generazione sono solitamente temporanei. Riprova una o due volte con backoff esponenziale. Se persistono con prompt e payload diversi, il problema non è dalla tua parte; acquisisci il corpo della risposta e contatta il supporto indicando l'ora della richiesta e l'identificatore del modello.

Errore di tipo di contenuto

Inviare il corpo della richiesta senza impostare Content-Type: application/json può produrre errori di validazione confusi, perché il server non riesce a interpretare il payload. In curl imposta esplicitamente l'header; in Python lascia che sia il parametro json= a impostarlo.

Rendere l'integrazione pronta per la produzione

La prima chiamata riuscita è la parte facile. Le seguenti regolazioni mantengono basso il costo operativo e di modifica dell'integrazione.

Configurare l'identificatore del modello

Memorizza l'identificatore del modello in una costante o in un valore di configurazione guidato dall'ambiente, mai inline in più punti di chiamata. Quando in futuro valuterai modelli diversi, basterà cambiare un valore e rieseguire i test. Mantieni nei log i campi di ogni richiesta per registrare quale modello ha generato ogni immagine, così puoi confrontare la qualità al cambio di modello senza rieseguire tutto.

Riprova in modo strategico

Riprova con backoff esponenziale e jitter per errori di rete, timeout e risposte 5xx. Non riprovare mai errori di validazione o autenticazione — la richiesta fallirà allo stesso modo e consumerai solo il limite di frequenza. Limita il numero di tentativi e registra il numero del tentativo e lo stato finale.

Scegliere timeout adatti al carico di lavoro

La generazione di immagini è lenta. Timeout troppo brevi fanno fallire richieste che sarebbero riuscite e, se riprovi, potresti pagare per una generazione già completata. Imposta un timeout ampio per richiesta e considera i timeout oltre una soglia come segnale per indagare sulla latenza, non come motivo per riprovare in modo aggressivo.

Suddividere il client in livelli

Mantieni separati i tre componenti: un builder del payload che converte gli input dell'applicazione in un dizionario di richiesta; una funzione di trasporto che esegue la chiamata HTTP; un handler che decodifica la risposta in byte. Testare il builder senza chiamate di rete è molto facile; sostituire il trasporto con un mock è altrettanto facile. Questa suddivisione rende anche la modifica del modello un intervento su un solo file, invece di una ricerca in tutto il codice.

Registrare le informazioni che ti serviranno durante un incidente

Registra timestamp, endpoint, identificatore del modello, stato HTTP, un hash o una forma troncata del prompt e la durata della richiesta. Non registrare mai le API key o gli header completi. Se memorizzi le immagini generate, imposta il percorso di archiviazione in base all'ID richiesta, così i ticket di supporto possono risalire alla chiamata effettiva.

Con l'autenticazione gestita dalle variabili d'ambiente e il payload isolato in una funzione builder, il pattern che hai sperimentato con gpt-image-2.6-sunburst/text-to-image è direttamente trasferibile a qualsiasi altro modello di immagini sullo stesso endpoint HiAPI.

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