Tutoriale
Come usare minimax-h3-image per la generazione di immagini text-to-image tramite l'API HiAPI: curl e Python
In questa pagina
Cosa copre questo tutorial e cosa devi preparare prima
Questo tutorial affronta una sola cosa concreta: inviare un prompt di generazione immagine al modello text-to-image minimax-h3-image tramite l'API HiAPI, prima con una richiesta curl e poi con una piccola funzione Python che puoi inserire nella tua applicazione. Copre la struttura della richiesta, come interpretare la risposta, come si manifestano gli errori e cosa bisogna stringere prima di andare in produzione.
Volutamente non tratta teoria del prompt engineering, post-processing delle immagini o costruzione di UI. L'obiettivo è più mirato: alla fine dovresti avere una richiesta affidabile e sapere esattamente perché l'ultima volta è fallita.
Prerequisiti
- Un account HiAPI. Prima di tutto il resto ti servono un progetto e una chiave API — ogni richiesta sottostante richiede autenticazione.
- Conserva la chiave in un posto sicuro. Mettila in una variabile d'ambiente (
HIAPI_API_KEY), non in un file sorgente, così lo stesso codice funziona in locale e in CI. - L'identificatore del modello. Questo tutorial usa
minimax-h3-imagee la sua capacitàtext-to-image. Tratta sia il nome del modello sia il percorso del task come valori di configurazione nel codice, non come stringhe magiche sparse ovunque. - Strumenti.
curlper la prima richiesta, Python 3.9+ erequestsper la seconda. Nessun'altra libreria necessaria. - Un modo per vedere l'immagine. Leggerai un payload di risposta che contiene i dati dell'immagine o un riferimento ad essa — ispeziona manualmente una volta i campi della risposta prima di dare per scontato qualsiasi schema.
Un'abitudine da coltivare subito
Genera la prima richiesta riuscita fuori dal codice dell'applicazione. Un comando curl funzionante è la verità di riferimento: ogni volta che la versione Python si comporta in modo strano, confrontala con quello. Se la chiamata curl riesce e Python no, il problema è nel tuo client, non nel modello o nella rete.
Costruire una richiesta text-to-image funzionante con curl
Inizia con la richiesta più piccola possibile, poi aggiungi un'impostazione alla volta. Una richiesta di generazione è composta da tre parti: l'endpoint, l'header di autenticazione e il corpo JSON della richiesta.
La richiesta
curl -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-h3-image",
"task": "text-to-image",
"prompt": "una ciotola di ceramica su una tovaglia di lino, luce morbida da finestra a nord, obiettivo 50mm, profondità di campo ridotta",
"size": "1024x1024",
"n": 1
}'
Tre cose da notare in quel comando:
- La chiave viene passata come bearer token nell'header
Authorization. Non metterla mai nell'URL o nel corpo della richiesta, altrimenti finirà nei log e nella cronologia della shell. modeletaskdescrivono cosa vuoi — la famiglia del modello e la capacità. Scrivi esplicitamente entrambi anche se esistono dei default; le richieste esplicite reggono meglio nel tempo.promptè una stringa normale. Tutto il resto (size,n) sono impostazioni dell'immagine, non descrizioni del soggetto.
Interpretare la risposta
Passa l'output attraverso un formattatore, così puoi davvero leggerlo:
curl -s -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json | python -m json.tool
Durante l'iterazione, metti il corpo della richiesta in un file (request.json) — così i prompt restano leggibili e modificare un prompt diventa un diff di una riga, non un indovinello di virgolette.
Ispeziona il payload prima di scrivere un parser. Nota se l'immagine viene restituita inline o come URL, quali campi portano l'identificatore dell'immagine e qualsiasi prompt modificato, e se la risposta include metadati di utilizzo. Annota quei nomi di campo; il tuo client Python dipenderà da essi.
Conferma l'intero flusso end-to-end
Salva l'immagine restituita, aprila e verifica che sia ciò che hai richiesto. Una risposta 200 con un corpo JSON plausibile non equivale a un'immagine corretta — è esattamente a questo punto che i problemi di prompt e parametri si scoprono a basso costo.
Tradurre la richiesta in Python
Ora porta la stessa identica richiesta. Mantienila banale: una funzione, timeout espliciti, nessun retry nascosto per ora.
import os
import requests
HIAPI_API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/images/generations"
def generate_image(prompt: str, size: str = "1024x1024", n: int = 1) -> dict:
"""Genera un'immagine con minimax-h3-image tramite HiAPI."""
payload = {
"model": "minimax-h3-image",
"task": "text-to-image",
"prompt": prompt,
"size": size,
"n": n,
}
response = requests.post(
ENDPOINT,
headers={
"Authorization": f"Bearer {HIAPI_API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=(5, 120), # timeout di connessione, timeout di lettura
)
response.raise_for_status()
return response.json()
Ci sono quattro scelte deliberate in quella funzione:
- Timeout a tupla. Il timeout di connessione è breve, perché una connessione lenta a stabilirsi indica un problema; il timeout di lettura è più ampio, perché la generazione di immagini richiede naturalmente tempo. Un unico valore di timeout ti costringe a fare male su una sola modalità di fallimento.
json=payload. Lascia che sia la libreria a serializzare il corpo. Le stringhe JSON costruite a mano sono terreno fertile per bug di virgolette.raise_for_status()prima del parsing. Il controllo dello stato non è opzionale — interpretare un corpo di errore come un successo è il tipo di bug più confuso in questo genere di integrazioni.- Restituisce un semplice
dict. Potrai decorarlo in seguito con modelli tipizzati; prima assicurati di sapere quali campi contiene davvero la risposta.
Isola il recupero della chiave
Se la variabile manca, os.environ["HIAPI_API_KEY"] solleva immediatamente un'eccezione. È intenzionale: fallire all'avvio, non alla prima richiesta dell'utente. In un codebase più grande, risolvi la chiave una volta durante il caricamento della configurazione, poi passa un client già configurato invece di leggere la variabile d'ambiente nel punto di chiamata.
Eseguilo
if __name__ == "__main__":
result = generate_image("un aquilone rosso sopra una spiaggia bagnata con la bassa marea, luce nuvolosa")
print(result)
Esegui e confronta con l'output di curl. La struttura del payload dovrebbe essere coerente. Se non lo è, hai trovato una discrepanza che vale la pena chiarire prima di continuare a costruire.
Gestire gli errori invece di indovinare
Il bug di integrazione più comune è riprovare un errore che non avrà mai successo. Dividi i fallimenti in tre categorie e trattale diversamente.
Fallimenti di autenticazione e autorizzazione
Di solito si manifestano come 401 o 403. Cause: header mancante, prefisso Bearer malformato, chiave revocata o configurata male, oppure il progetto non ha accesso a quel modello. Sono non ritentabili. Riprovare fa solo perdere tempo e sporca i log con lo stesso fallimento. Sistema le credenziali e vai avanti.
Fallimenti di validazione della richiesta
Di solito sono risposte di livello 400: valori di model o task sconosciuti, size non supportata dal modello, n fuori intervallo, prompt vuoto, JSON malformato. Anche questi sono non ritentabili — la stessa richiesta fallirà allo stesso modo. Il lavoro utile è presentare il messaggio di errore così com'è allo sviluppatore che ha scritto la richiesta, invece di inghiottirlo in un'eccezione generica.
Fallimenti transitori del server e della rete
Le risposte 429 e 5xx, insieme alle connessioni resettate e ai timeout di lettura, sono la vera categoria ritentabile. Gestiscile con backoff esponenziale limitato e jitter:
import time, random, requests
def post_with_retry(session, url, payload, max_attempts=4):
for attempt in range(max_attempts):
try:
r = session.post(url, json=payload, timeout=(5, 120))
if r.status_code in (429, 500, 502, 503, 504):
raise requests.HTTPError(f"errore transitorio {r.status_code}", response=r)
r.raise_for_status()
return r.json()
except (requests.ConnectionError, requests.Timeout, requests.HTTPError) as exc:
if attempt == max_attempts - 1:
raise
time.sleep(min(2 ** attempt + random.random(), 30))
Due avvertenze. Primo, un HTTPError sollevato da un 4xx che non sia 429 deve propagarsi immediatamente — non lasciare che la clausola except assorba i fallimenti di validazione. Secondo, segui qualsiasi indicazione di retry presente nella risposta, invece di inventare tu il ritardo.
Qui il retry non è idempotente
Ogni generazione ritentata è una nuova generazione fatturata. Se la richiesta va in timeout, l'immagine potrebbe essere comunque stata generata e fatturata. Mantieni basso il numero di retry, registra nei log il numero di tentativi insieme ai metadati della richiesta e preferisci mostrare un fallimento esplicito piuttosto che generare silenziosamente la stessa immagine quattro volte.
Abitudini pratiche per prompt e parametri
Il valore di queste abitudini è la comparabilità: quando cambi una cosa, dovresti poter determinare se il cambiamento dell'output è dovuto a essa.
Scrivere prompt che nominano ciò che è nell'inquadratura
Descrivi nell'ordine soggetto, scena, illuminazione, composizione. Nomi specifici e termini fotografici (come "luce morbida da finestra a nord", "profondità di campo ridotta") portano più segnale di una pila di aggettivi estetici. Evita un largo uso di prompt negativi; descrivi ciò che dovrebbe esserci.
Cambiare una sola variabile alla volta
Mantieni un piccolo file di prompt per progetto, modificalo tra un'esecuzione e l'altra invece di riscriverlo da zero. Se un'esecuzione delude, cambia o il prompt o le impostazioni — non entrambi. Altrimenti non puoi sapere quale modifica ha fatto la differenza.
Trattare le impostazioni come un contratto esplicito
size e n influenzano sia l'output sia il costo. Fissale in un oggetto di configurazione invece di passare valori letterali attraverso i punti di chiamata, così cambiare il formato per l'intera funzionalità è una sola modifica. Se hai bisogno di più immagini per confrontarle, richiedile in un'unica chiamata, non in più chiamate — meno round-trip, log più leggibili.
Memorizzare i prompt insieme agli output
Persisti accanto a ogni immagine generata l'esatta stringa del prompt, le impostazioni e l'identificatore del modello. Un prompt irriproducibile è un'immagine che non puoi rigenerare, fare debug o migliorare. Questa singola abitudine fa risparmiare più tempo di qualsiasi trucco sui prompt.
Stabilire un seed per i confronti
Lo stesso prompt può produrre immagini diverse tra un'esecuzione e l'altra. Quando valuti una modifica, confronta risultati aggregati — più immagini per configurazione — invece di fidarti di un singolo campione fortunato o sfortunato.
Versionare i prompt
Tratta il testo dei prompt come codice: conservalo in file, revisiona le modifiche e registra quale versione del prompt ha prodotto quale asset. Questo rende "perché martedì scorso le immagini sono peggiorate?" una domanda a cui si può rispondere.
Checklist di produzione prima del lancio
Una richiesta funzionante è solo la parte facile. Questi controlli distinguono una demo da un'integrazione.
- Timeout su ogni chiamata. Imposta esplicitamente timeout di connessione e di lettura, mai i default. Un endpoint di generazione senza timeout di lettura finirà per bloccare un worker.
- Retry limitati, solo su errori ritentabili. Limita i tentativi, aggiungi jitter e assicurati che i fallimenti di validazione e autenticazione bypassino del tutto il percorso di retry.
- Gestione delle chiavi. Leggi la chiave dall'ambiente o da un vault dei segreti, mai dal codice sorgente. Ruotala senza modificare il codice.
- Log strutturati. Registra identificatore del modello, prompt (o il suo hash più un riferimento), impostazioni, stato HTTP, numero di tentativi e qualsiasi identificatore di richiesta presente nella risposta. Senza questi, i problemi delle immagini diventano irriproducibili.
- Visibilità dei costi. La generazione viene fatturata sull'output, quindi il consumo dipende da quante immagini chiedi e con quanta frequenza riprovi. Decidi in anticipo se le richieste sono per utente, per task o in background, e traccia i volumi di conseguenza — consulta il pannello prezzi in tempo reale sul sito per le tariffe attuali, invece di codificare ipotesi.
- Definisci il comportamento in caso di fallimento. Decidi cosa vede l'utente quando la generazione fallisce dopo il tentativo finale: stato di errore, segnaposto o retry in coda. Un fallback non definito diventa un'esperienza utente non definita.
- Fissa lo schema del payload. Memorizza e valida i campi della risposta su cui fai affidamento, così una modifica del payload si manifesta come errore esplicito e non come un
Nonesilenzioso.
Passo di verifica finale
Esegui il comando curl, la funzione Python e una richiesta volutamente rotta (prima con una chiave errata, poi con un parametro errato), e conferma che ognuna produca il fallimento che ti aspetti. Quest'ultimo passo è ciò che ti dice che la gestione degli errori è reale, non decorativa.
Una volta che la richiesta è autenticata, portata in Python, ritentata in modo sensato e registrata nei log, l'integrazione può passare dietro il resto dell'applicazione.
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