Tutoriale
Come usare grok-imagine/text-to-image tramite l'API HiAPI: guida con curl e Python
In questa pagina
Cosa ti offre grok-imagine/text-to-image
grok-imagine/text-to-image è un endpoint di generazione di immagini da testo disponibile tramite HiAPI: invii un prompt e pochi parametri di generazione in JSON via HTTP, e ricevi un'immagine. Non c'è altro da sapere. Nessun SDK da installare, nessuna sessione da inizializzare, nessun task in background da interrogare per vedere la prima immagine.
La sua collocazione nel flusso di lavoro di uno sviluppatore:
- Validazione di prototipi. Puoi passare dall'idea all'immagine renderizzata con un solo comando da terminale, il che ti permette di testare rapidamente le idee di prompt.
- Pipeline di contenuti. Poiché è una normale chiamata HTTP, puoi richiamarlo da servizi backend, worker in coda o script di build come qualsiasi altra API.
- Funzionalità di prodotto. La generazione di immagini per gli utenti finali richiede in genere una gestione prevedibile di richiesta/risposta, errori strutturati e retry. Un endpoint stateless è ideale per tutti e tre questi aspetti.
Ciò che questo endpoint non è: non memorizza i tuoi prompt, non gestisce una libreria di immagini generate e non sostituisce la tua orchestrazione. La richiesta è responsabilità tua, l'output è responsabilità tua, e la destinazione dei byte è una tua scelta.
Questa guida punta prima a far funzionare la richiesta, poi a renderla affidabile. Che tu chiami con curl o con Python, il pattern è identico, perché in entrambi i casi si tratta della stessa richiesta HTTP autenticata. Inizia dal minimo funzionante, verifica il round-trip, poi aggiungi complessità.
Prerequisiti e autenticazione
Prima della prima chiamata, assicurati di avere:
- Un account HiAPI e una chiave API. Tratta la chiave come un segreto: caricala da una variabile d'ambiente e non codificarla mai direttamente in script che potrebbero essere sottoposti a commit.
- Uno strumento per effettuare richieste HTTP. Per i primi test basta
curl. Per Python, usarequestsohttpx; entrambi sono trattati più avanti. - Accesso di rete all'host dell'API HiAPI. Se sei dietro un proxy aziendale, assicurati di aver impostato
HTTPS_PROXYper la tua shell, in modo che siacurlsia Python possano leggerlo.
La chiave viene passata come bearer token tramite l'header Authorization:
export HIAPI_API_KEY="your-key-here"
Poi ogni richiesta include:
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
Due abitudini da adottare subito:
- Non mettere mai la chiave nell'URL. Nessuna parte della richiesta dovrebbe inserire credenziali nella query string, perché lì finiranno nei log e nella cronologia della shell.
- Usa una chiave per ambiente. Le chiavi di sviluppo e di produzione dovrebbero essere valori diversi, così puoi ruotarne una senza impattare l'altra.
Se non hai ancora generato una chiave, creane una nella dashboard di HiAPI e salvala nel tuo secret manager o in un file .env locale escluso dal controllo di versione. Una volta che echo $HIAPI_API_KEY stampa il valore, sei pronto per la prima richiesta.
Richiesta minima funzionante in curl
La chiamata utile minima invia solo l'identificatore del modello e il prompt. Tutto il resto ha valori predefiniti, quindi non affrettarti a regolare i parametri prima di aver visto restituire un'immagine.
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine/text-to-image",
"prompt": "a lighthouse on a rocky coast at dusk, calm sea, soft overcast light"
}'
Cosa fa ciascuna parte:
-X POSTcon un corpo JSON è la forma standard per gli endpoint di generazione.modelseleziona esplicitamentegrok-imagine/text-to-image. Fissa il nome del modello negli script invece di affidarti ai valori predefiniti, così i cambiamenti dei default non altereranno silenziosamente i tuoi output.promptè l'unico input di contenuto. Per il primo test, mantienilo su una singola frase chiara.
Una risposta riuscita restituisce JSON contenente l'immagine generata, in genere un URL o un payload base64, a seconda del formato di risposta richiesto. Prima di scrivere qualsiasi codice di parsing, leggi la risposta con un formattatore JSON. Se visualizzi l'output nel terminale, passarlo attraverso python -m json.tool rende la struttura più leggibile.
Una volta funzionante, salva la risposta grezza su file, così avrai una baseline nota e valida:
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json \
-o response.json
Mettendo il corpo della richiesta in request.json, potrai modificare il prompt senza combattere con le virgolette della shell, cosa particolarmente importante quando i prompt diventano lunghi o contengono punteggiatura.
La stessa richiesta in Python
La versione Python è la stessa chiamata HTTP, ma con un'esperienza d'uso migliore: un dizionario al posto delle virgolette annidate e la gestione diretta dei byte dell'immagine.
import os
import requests
api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]
payload = {
"model": "grok-imagine/text-to-image",
"prompt": "a lighthouse on a rocky coast at dusk, calm sea, soft overcast light",
}
response = requests.post(
f"{base_url}/v1/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)
Due dettagli meritano una menzione speciale. Primo, timeout=120 — la generazione di immagini non è istantanea, e una richiesta senza timeout lascerebbe un worker bloccato all'infinito se l'upstream si inceppa. Secondo, chiama raise_for_status() prima del parsing, così il corpo di una risposta di errore non verrà scambiato per una risposta immagine riuscita.
Per salvare l'immagine, gestisci le due forme di risposta:
item = data["data"][0]
if item.get("b64_json"):
import base64
image_bytes = base64.b64decode(item["b64_json"])
else:
image_bytes = requests.get(item["url"], timeout=60).content
with open("output.png", "wb") as f:
f.write(image_bytes)
Se preferisci un unico set di dipendenze, httpx si usa allo stesso modo, con httpx.post(..., json=payload). La chiave è che corpo della richiesta e header corrispondono esattamente all'esempio curl — è proprio questa coerenza a rendere i due esempi intercambiabili e il debug prevedibile.
Organizzare il prompt per il rapporto d'aspetto
Gli output wide falliscono in modi specifici: il modello ha molto spazio orizzontale da riempire, quindi tende a ripetere elementi o a far fluttuare un piccolo soggetto in una scena vuota. Devi risolverlo con la struttura del prompt, non accumulando più aggettivi.
Usa uno scheletro in tre parti:
- Soggetto — di cosa parla l'immagine, dichiarato per primo e in modo specifico. "Una nave cargo che entra in porto" è meglio di "una nave".
- Stile — il linguaggio di rendering: fotografia, vettoriale piatto, acquerello, fotogramma cinematografico. Una o due parole bastano.
- Composizione — come è organizzata l'inquadratura, ed è qui che si vince o si perde con il rapporto wide.
Per la composizione, nomina esplicitamente la struttura orizzontale:
- Specifica un ordine di lettura da sinistra a destra o panoramico: "vista ampia, soggetto nel terzo destro, cielo aperto a sinistra".
- Descrivi primo piano, piano medio e sfondo come fasce separate, perché un'immagine wide viene naturalmente letta per livelli.
- Dichiara esplicitamente cosa riempie i bordi: "gru portuali all'estrema sinistra, acqua aperta all'estrema destra". I bordi sono il primo punto in cui un'immagine wide si svuota.
- Evita prompt che suggeriscono composizioni ritratto o quadrate — volti in primo piano, singoli oggetti centrati — e aspettati che vengano allungati o letterboxed.
Quando imposti il parametro del rapporto d'aspetto per un formato panoramico, modifica anche il prompt. Un prompt scritto per un'immagine quadrata produrrà un concetto quadrato su una tela wide. Riscrivilo in una scena che includa distanza orizzontale: un orizzonte, una strada, file di oggetti, gruppi distribuiti in una stanza.
Itera su una sola variabile alla volta. Fissa il rapporto d'aspetto e modifica la formulazione; poi fissa la formulazione e cambia il rapporto. Registra entrambi insieme all'output, così puoi capire quale modifica abbia davvero aiutato.
Gestire errori e codici di risposta
Leggi prima il codice di stato, poi il corpo della risposta. Ogni errore comune indica una soluzione diversa, e confonderli fa perdere tempo.
401 Unauthorized
La chiave è mancante, malformata o revocata. Controlla che l'header sia esattamente Authorization: Bearer <key>, che la variabile d'ambiente sia effettivamente espansa (stampane la lunghezza, non il valore) e che tu non abbia inviato per errore una chiave di un altro ambiente.
400 Bad Request
Il tuo JSON è HTTP valido, ma non valido per questo endpoint. I sospetti più comuni:
modelscritto male o mancante. Deve esseregrok-imagine/text-to-image.promptvuoto o mancante.- Un parametro con il tipo sbagliato — una stringa dove serve un numero, o viceversa.
- Il corpo della richiesta non è affatto JSON valido, spesso per problemi di quoting della shell in
curl. Sposta il corpo in un file e usa-d @request.json.
Leggi il corpo del messaggio di errore; di solito indica il campo problematico.
429 Too Many Requests
Stai inviando richieste più velocemente della tua quota. La correzione è lato client: backoff, accodamento, retry. Non restringere il ciclo di retry perché hai ricevuto un 429 — peggiorerà la situazione.
Errori 5xx del server
Sono condizioni transitorie o upstream. Riprova dopo un ritardo e, se il fallimento persiste dopo diversi tentativi, cattura il payload della richiesta e il corpo della risposta per la diagnosi, invece di riprovare all'infinito.
Timeout ed errori di connessione
Non sono affatto codici di stato HTTP, ma sono in pratica i fallimenti più comuni. Se requests solleva un timeout di connessione, è possibile che la richiesta sia stata comunque elaborata. Prima di scrivere un ciclo di retry, decidi per il tuo caso d'uso se un timeout significhi "riprova" o "rinuncia".
Ottimizzazione e retry in produzione
Una volta che la richiesta di base funziona, ottimizza a piccoli passi: prima la formulazione del prompt, poi il rapporto d'aspetto, poi gli altri parametri, confrontando gli output fianco a fianco. Salva ogni payload di richiesta insieme al suo output, così i risultati restano sempre riproducibili.
Un wrapper di produzione fa tre cose: riprova solo i fallimenti che vale la pena riprovare, registra log sufficienti per il debug e fallisce in modo rumoroso quando rinuncia.
import time
import requests
def generate(payload, max_attempts=4):
for attempt in range(1, max_attempts + 1):
try:
r = requests.post(
f"{base_url}/v1/images/generations",
headers=headers,
json=payload,
timeout=120,
)
except requests.RequestException as exc:
log.warning("request failed attempt=%d err=%s", attempt, exc)
time.sleep(2 ** attempt)
continue
if r.status_code == 429 or r.status_code >= 500:
log.warning("retryable status=%d attempt=%d", r.status_code, attempt)
time.sleep(2 ** attempt)
continue
if r.status_code >= 400:
raise RuntimeError(f"{r.status_code}: {r.text[:500]}")
return r.json()
raise RuntimeError("exhausted retries")
Note su questo pattern:
- Backoff esponenziale con limite massimo (
2 ** attempt) evita che un client soggetto a rate limit martelli ripetutamente l'endpoint. Se esegui molti worker, aggiungi jitter. - Riprova solo 429, 5xx ed errori di rete. Un 400 o un 401 falliranno allo stesso modo a ogni tentativo.
- Registra numero di tentativi e stato, non la chiave API, e non registrare mai il prompt completo se potrebbe contenere dati utente.
- Limita il tempo totale. Un ciclo di retry senza limite trasforma una richiesta lenta in un worker bloccato.
Misura le tue latenze e i tassi di successo invece di supporli; questi due numeri ti dicono se ti serve più parallelismo o più backoff. Inizia dalla richiesta minima di questa guida, avvolgila nella funzione di supporto qui sopra, poi itera da lì.
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