Tutoriale
Come chiamare gpt-image-2.6-flare/text-to-image tramite l'API HiAPI: curl, Python e richieste eseguibili
In questa pagina
Cosa costruirai in questo tutorial
La maggior parte dei tutorial sulla generazione di immagini da testo si ferma a uno screenshot di una risposta riuscita. Non basta per mettere qualcosa in produzione. Questo tutorial ti porta da zero a un'integrazione riutilizzabile e funzionante con il modello gpt-image-2.6-flare/text-to-image tramite l'API unificata HiAPI.
Alla fine avrai tre cose:
- Una richiesta verificata e funzionante, presentata prima come comando
curle poi come script Python equivalente. - Un modello mentale chiaro di come HiAPI organizza le chiamate di generazione di immagini da testo — percorso dell'endpoint, header di autenticazione, payload del prompt e corpo della risposta — così potrai adattare gli esempi ai tuoi prompt invece di impararli a memoria.
- Modelli per estendere quella singola chiamata all'elaborazione in batch, e un metodo per capire quali errori ritentare e quali correggere.
Manterremo il codice snello e con dipendenze minime. Gli esempi Python usano solo la libreria standard, quindi puoi eseguirli in qualsiasi ambiente con Python installato; quando avrai familiarità con la struttura della richiesta, potrai adattarli a requests o a un client asincrono. Se vuoi passare subito alla chiamata eseguibile, salta alla sezione curl e torna dopo per le spiegazioni.
Prerequisiti e credenziali
Prima della prima chiamata, verifica di avere quanto segue:
- Un account HiAPI. Accedi alla dashboard per generare e gestire le credenziali.
- Una chiave API. Creane una nella sezione API keys della dashboard. Trattala come una password: autorizza ogni richiesta fatturata sul tuo account.
- Un modo per inviare richieste HTTP. O una shell con
curlinstallato, o Python 3 con la libreria standard (urllibejsonsono inclusi in Python).
Gestire la chiave tramite variabili d'ambiente
Non incollare mai la chiave direttamente in file sorgente che potrebbero essere sottoposti a commit. Esportala invece nella shell:
export HIAPI_API_KEY="your-api-key-here"
In Windows PowerShell usa $env:HIAPI_API_KEY = "your-api-key-here". In CI, iniettala come secret. In un servizio di lunga durata, caricala all'avvio da un gestore di segreti.
Capire dove si trova l'URL di base
HiAPI offre un'unica superficie API unificata, quindi l'URL di base rimane stabile tra i modelli. Conservalo in un valore di configurazione — una variabile d'ambiente va benissimo — invece di sparpagliarlo nel codice. Così passare tra staging e produzione, o far puntare i test a un server mock, richiede una sola modifica.
L'identificatore del modello da chiamare è gpt-image-2.6-flare/text-to-image. Nota che contiene una barra; mantieni l'identificatore intatto e posizionalo nel percorso dove il costruttore di richieste se lo aspetta, esattamente come negli esempi che seguono.
Con la chiave esportata e l'URL di base annotato, puoi passare a esaminare la richiesta stessa.
Anatomia di una richiesta di generazione di immagini da testo
Ogni chiamata HiAPI per la generazione di immagini da testo ha gli stessi quattro componenti. Una volta compresi, cambiare modello o prompt diventa meccanico.
1. Il percorso dell'endpoint
La richiesta include l'identificatore del modello come parte del percorso: gpt-image-2.6-flare/text-to-image, aggiunto dopo il tuo URL di base. È l'indirizzo che instrada la chiamata al modello corretto dietro l'interfaccia unificata.
2. L'header di autenticazione
L'autenticazione avviene tramite il token bearer nell'header Authorization:
Authorization: Bearer $HIAPI_API_KEY
Ogni richiesta deve includere questo header. Un header mancante o malformato è la causa più comune di fallimento alla prima chiamata.
3. Il corpo della richiesta
Una chiamata di generazione di immagini da testo è un POST con corpo JSON. Il cuore è il prompt — la descrizione in linguaggio naturale dell'immagine che desideri. Il corpo trasporta anche le impostazioni di generazione. Poiché HiAPI normalizza la struttura delle richieste tra i modelli, puoi riutilizzare il costruttore di richieste e cambiare l'identificatore del modello quando vuoi confrontare gli output.
4. Il corpo della risposta
Una risposta riuscita restituisce l'immagine generata (o un suo riferimento) insieme ai metadati sulla generazione. Il tuo client deve controllare lo stato HTTP prima di tentare di analizzare l'immagine. Tratta la risposta come dati, non come qualcosa da guardare a occhio nudo — per l'automazione ti servono i byte o l'URL dell'immagine, e devi memorizzare insieme a essi qualsiasi identificatore di richiesta per associare il file alla chiamata che l'ha prodotto.
Questo è l'intero modello. Tutto il resto è un'istanza concreta di queste quattro parti.
Inviare una richiesta eseguibile con curl
Questa è la chiamata completa. Sostituisci il prompt con il tuo testo ed eseguila:
curl -X POST "$HIAPI_BASE_URL/gpt-image-2.6-flare/text-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A quiet library at dusk, warm lamp light, deep shadows, cinematic"
}' \
--output response.json
Spiegazione riga per riga:
-X POST— la generazione è una chiamata che modifica lo stato, quindi si usa POST.- URL — l'URL di base preso dalla variabile d'ambiente, seguito dall'identificatore del modello e da
/text-to-image. Le virgolette evitano che la shell interpreti male i caratteri speciali. Authorization: Bearer ...— le credenziali. La forma$HIAPI_API_KEYevita che la chiave in chiaro finisca nella cronologia della shell.Content-Type: application/json— dice al server di analizzare il corpo come JSON. Ometterlo è una causa comune di errori 4xx fuorvianti.-d '{...}'— il payload JSON. Il campopromptè quello che cambierai più spesso; aggiungi qui le impostazioni di generazione mentre ottimizzi l'output.--output response.json— scrive il corpo della risposta su file, così un payload binario dell'immagine non inonda il terminale. Aprilo, oppure, se la risposta è codificata in JSON, passalo ajq.
Verifica rapida di funzionamento
Se il comando restituisce rapidamente e response.json non è vuoto, hai un'integrazione funzionante. Se invece ottieni un 4xx, controlla il corpo della risposta — HiAPI restituisce errori descrittivi, e la sezione sulla gestione degli errori qui sotto copre i sospetti più comuni.
Una volta che funziona, salva il comando in uno script shell accanto al progetto. È il modo più rapido per verificare un cambio di credenziali o confermare se il guasto è dalla tua parte.
Inviare la stessa richiesta in Python
La chiamata curl si traduce direttamente in Python. Questo script usa solo la libreria standard, legge la chiave dalle variabili d'ambiente e scrive la risposta immagine su disco:
import json
import os
import urllib.error
import urllib.request
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
MODEL = "gpt-image-2.6-flare/text-to-image"
def generate_image(prompt: str, settings: dict | None = None) -> bytes:
payload = {"prompt": prompt}
if settings:
payload.update(settings)
request = urllib.request.Request(
f"{BASE_URL}/{MODEL}",
data=json.dumps(payload).encode("utf-8"),
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
method="POST",
)
try:
with urllib.request.urlopen(request, timeout=120) as response:
return response.read()
except urllib.error.HTTPError as exc:
detail = exc.read().decode("utf-8", errors="replace")
raise RuntimeError(f"HTTP {exc.code}: {detail}") from exc
if __name__ == "__main__":
body = generate_image("A quiet library at dusk, warm lamp light, deep shadows, cinematic")
with open("output.bin", "wb") as f:
f.write(body)
print(f"wrote {len(body)} bytes")
Alcune scelte deliberate:
- Timeout generoso. La generazione di immagini è più lenta del completamento di testo; un limite di 120 secondi evita attese infinite pur tollerando chiamate lente ma riuscite.
- La funzione restituisce byte, non un percorso. Questo la rende riutilizzabile — puoi caricare i byte su uno storage a oggetti o restituirli da un gestore web.
- Gli errori sono incapsulati insieme al corpo della risposta. In caso di errore, il messaggio ti dice cosa ha risposto il server, non solo il codice di stato.
- Il costruttore del payload accetta impostazioni opzionali. Quando aggiungi parametri di generazione, estendi il dizionario
settingsinvece di codificarli direttamente nella funzione.
Dopo aver esportato le due variabili d'ambiente, eseguilo con python generate.py. Se preferisci requests, sostituisci la costruzione della richiesta con requests.post(url, json=payload, headers=headers); la struttura è identica.
Modelli di elaborazione in batch e concorrenza
Un prompt è una demo; molti prompt sono lavoro. Questo passaggio introduce due problemi: throughput e debugging.
Iterare sui prompt da un file
Metti i prompt in un file separato da newline o in un array JSON. Assegna a ogni prompt un ID (slug, indice o hash) e usa quell'ID per nominare il file di output. Quando un batch di centinaia di immagini è completo, puoi associare ogni file al suo prompt senza indovinare.
prompts = [
("lib-001", "A quiet library at dusk, warm lamp light, cinematic"),
("lib-002", "A lighthouse in fog, long exposure, muted palette"),
]
for prompt_id, text in prompts:
body = generate_image(text)
with open(f"out/{prompt_id}.bin", "wb") as f:
f.write(body)
Controllare esplicitamente la concorrenza
Le chiamate di generazione sono I/O-intensive, quindi la concorrenza aiuta il throughput — ma una concorrenza illimitata fa scattare i limiti di frequenza e ti fa sprofondare negli errori. Inizia in modo seriale, misura la durata di una singola chiamata, poi aumenta la concorrenza con un pool di worker limitato. Un semplice thread pool con pochi worker fissi (da quattro a otto per iniziare) di solito è sufficiente.
Per attività più grandi, usa un client asincrono o una coda con worker. La disciplina chiave è la stessa: parallelismo limitato, un file di output per ogni ID prompt, una riga di log per ogni richiesta con ID, stato e durata.
Conservare un manifest
Durante l'esecuzione del batch, scrivi un piccolo manifest JSON che registra ogni ID prompt e il suo risultato. Se il processo muore a metà, il manifest ti dice da dove riprendere invece di fatturare di nuovo l'intero batch. Questa pratica fa risparmiare più tempo di qualsiasi ottimizzazione intelligente.
Gestire errori e retry
I fallimenti si dividono in due categorie: quelli che correggi e quelli che ritenti. Confonderli fa perdere tempo e, in una tempesta di retry, anche denaro.
Correggi questi
- 401 / 403 — autenticazione. Chiave mancante, scaduta o senza permessi di accesso. Verifica che
HIAPI_API_KEYsia effettivamente esportata nella shell che esegue il comando — una trappola comune è esportarla in un terminale e lanciare lo script in un altro. - 400 — payload malformato. JSON non valido,
promptmancante o tipi di campo inattesi. Il corpo dell'errore di solito indica il campo problematico. Nella chiamata curl fai molta attenzione alle virgolette del JSON. - 404 — percorso errato. Verifica che l'identificatore del modello sia scritto esattamente come nella documentazione e che il tuo URL di base non abbia segmenti di percorso duplicati o mancanti.
Ritenta questi, con backoff
- 429 — limite di frequenza. Rallenta. Rispetta eventuali suggerimenti retry-after nella risposta e usa un backoff esponenziale con jitter. A lungo termine, limita la concorrenza.
- 5xx — errori del server. Di solito transitori. Ritenta un numero limitato di volte (tre è un valore predefinito ragionevole), con ritardo crescente, poi fallisci in modo esplicito.
Un wrapper di retry minimale
import random, time
def with_retries(fn, attempts=3):
for i in range(attempts):
try:
return fn()
except RuntimeError as exc:
if i == attempts - 1:
raise
time.sleep((2 ** i) + random.uniform(0, 0.5))
Usalo per avvolgere generate_image. La chiave è rendere l'operazione idempotente dal tuo lato: poiché i file di output sono identificati dall'ID del prompt, un retry sovrascrive invece di duplicare. Registra ogni fallimento con l'ID del prompt e il messaggio del server — quando dovrai davvero escalare, quel log è esattamente ciò che serve al team di supporto per riprodurre il problema.
Prossimi passi
Ora hai una richiesta funzionante, una funzione Python che vale la pena conservare e i modelli per eseguirla su larga scala. Per rafforzarla in produzione, aggiungi logging strutturato con ID di richiesta, persisti il manifest su uno storage durevole così che i job batch possano riprendersi dopo un crash, e valida i prompt prima dell'invio, in modo che gli input malformati falliscano rapidamente e a basso costo.
Il prossimo passo più utile è riutilizzare questo stesso client con altri modelli sull'API HiAPI. Poiché il percorso dell'endpoint, gli header di autenticazione e la struttura del payload sono condivisi, adattare lo script a un nuovo modello di solito significa cambiare l'identificatore del modello e, occasionalmente, una o due impostazioni — una piccola modifica al codice può produrre output significativamente diversi.
Inizia con un prompt, verifica che il file venga generato, poi lascia che il runner batch gestisca il resto.
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