Tutoriale
Come chiamare minimax-h3-image image-to-image su hiapi con curl e Python
In questa pagina
Cosa si aspetta l'endpoint image-to-image
Prima di scrivere qualsiasi codice, è utile capire la struttura di una chiamata image-to-image. L'endpoint image-to-image di minimax-h3-image riceve la tua immagine di riferimento (una o più) e un prompt testuale, e restituisce un nuovo risultato generato che segue il prompt, restando ancorato all'immagine di riferimento.
Concettualmente, ogni richiesta contiene tre parti:
- Routing del modello — indirizzi
minimax-h3-imagecon l'attivitàimage-to-image, il tutto attraverso un unico endpoint hiapi. Non ti servono credenziali o host separati per ogni capacità. - Input — una stringa di prompt, una o più immagini di riferimento (URL o payload base64) e controlli di generazione come il livello di risoluzione.
- Contratto di output — la chiamata è asincrona. Ricevi un identificatore di attività, poi interroghi lo stato e recuperi l'URL dell'immagine generata quando l'attività è completata.
Quest'ultimo punto è importante. Image-to-image non è una chiamata bloccante che restituisce i pixel nella stessa risposta. Considera la chiamata di invio come "accodare un lavoro" e progetta il client fin dall'inizio attorno al ciclo di vita dell'attività. Se progetti prima per un comportamento sincrono, dovrai riscrivere il codice di integrazione più avanti.
Poiché tutto passa attraverso la stessa interfaccia hiapi, header, autenticazione e wrapper delle risposte restano coerenti tra modelli e attività. Impara una volta per minimax-h3-image e lo stesso schema vale per il resto della piattaforma.
Una richiesta minima eseguibile
Inizia con la richiesta più piccola che dimostri che credenziali, endpoint e struttura del payload sono corretti. Non affrettarti ad aggiungere subito tutti i campi opzionali.
Il corpo minimo della richiesta contiene:
- Il nome del modello
minimax-h3-image - Il tipo di attività
image-to-image - Un
promptche descrive che tipo di trasformazione vuoi - Un singolo campo per l'immagine di riferimento
- Un livello di risoluzione
Concettualmente, il payload è più o meno così:
{
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": "Trasforma questo schizzo in un rendering di prodotto pulito su sfondo bianco",
"image": "https://example.com/reference.png",
"resolution": "1024"
}
}
Invia la richiesta, verifica che venga restituito un id attività, poi interroga manualmente un paio di volte per osservare le transizioni di stato. Se ottieni un id attività, connettività e autenticazione funzionano e puoi passare a costruire il client vero e proprio. In caso contrario, fermati e leggi il corpo della risposta di errore — di solito indica direttamente il campo problematico.
Salva questa richiesta come smoke test. Quando modifiche successive rompono la tua pipeline, rieseguire questa richiesta minima ti dirà subito se il problema è nel payload o nel codice circostante.
Chiamata con curl
curl è il modo più rapido per vedere la richiesta e la risposta grezze. Scrivi il corpo JSON in un file, così durante le modifiche non devi combattere con le virgolette della shell.
cat > payload.json <<'JSON'
{
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": "Trasforma questa foto in uno stile illustrazione ad acquerello",
"image": "https://example.com/reference.png",
"resolution": "1024"
}
}
JSON
curl -sS -X POST "$HIAPI_BASE_URL/v1/tasks" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
--data @payload.json
Due header fanno il lavoro principale: Authorization con il bearer token e Content-Type: application/json. Tienili entrambi fuori dal controllo versione — leggi la chiave da una variabile d'ambiente invece di incollarla nel comando.
Quando l'invio riesce, cattura l'id attività restituito e interrogalo:
curl -sS "$HIAPI_BASE_URL/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY"
La risposta contiene un campo di stato e, al completamento, il risultato. Usa jq per estrarre solo i campi che ti interessano:
curl -sS "$HIAPI_BASE_URL/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY" | jq '.status, .result'
È anche il modo più semplice per fare debug del payload: curl mostra esattamente cosa hai inviato e cosa è stato restituito, senza che nulla venga nascosto da una libreria client.
Chiamata con Python
La versione Python dovrebbe rispecchiare il flusso curl: invia, cattura l'id, interroga fino allo stato terminale, recupera il risultato. Usa requests e Session, così il riutilizzo della connessione e gli header predefiniti vanno gestiti una sola volta.
import os
import time
import requests
BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {
"Authorization": f"Bearer {KEY}",
"Content-Type": "application/json",
}
def submit(prompt: str, image: str, resolution: str = "1024") -> str:
body = {
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": prompt,
"image": image,
"resolution": resolution,
},
}
resp = requests.post(f"{BASE}/v1/tasks", json=body, headers=HEADERS, timeout=30)
resp.raise_for_status()
return resp.json()["id"]
def poll(task_id: str, timeout: float = 300, interval: float = 2.0) -> dict:
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
resp = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
resp.raise_for_status()
data = resp.json()
status = data.get("status")
if status in ("succeeded", "failed"):
return data
time.sleep(interval)
raise TimeoutError(f"L'attività {task_id} non è stata completata entro {timeout} secondi")
if __name__ == "__main__":
task_id = submit(
"Trasforma questa immagine in un poster vettoriale piatto",
"https://example.com/reference.png",
)
print("Inviato:", task_id)
result = poll(task_id)
print(result)
Dettagli chiave: raise_for_status() trasforma gli errori HTTP in eccezioni invece di farli fallire silenziosamente; il ciclo di polling ha sia una scadenza sia un intervallo; gli stati terminali sono controllati esplicitamente. Estrai l'URL dell'immagine dall'oggetto risultato solo dopo che lo stato ha raggiunto uno stato terminale, mai prima.
Usare più immagini di riferimento
Spesso una singola immagine di riferimento non basta. Potresti voler conservare il volto di una foto e prendere in prestito la composizione di un'altra, oppure fondere una texture e un profilo. Minimax-h3-image image-to-image supporta input con più riferimenti tramite il campo plurale image.
Strutturalmente, l'oggetto input può portare una singola immagine di riferimento nel campo image, oppure un array images quando ne hai più di una:
{
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": "Mantieni la persona nella prima immagine, usa lo stile dello sfondo della seconda immagine",
"images": [
"https://example.com/person.png",
"https://example.com/background.png"
],
"resolution": "1024"
}
}
L'ordine ha significato. L'indice di riferimento 0 è il tuo soggetto principale, le voci successive sono contesto ausiliario, quindi formula il prompt in modo coerente con l'ordine in cui invii le immagini. Se il risultato ignora un'immagine di riferimento, di solito la causa è un prompt ambiguo, non un campo rotto — fai in modo che il prompt dica esplicitamente quale immagine determina quale attributo.
Regole pratiche per il lavoro con più riferimenti:
- Mantieni il numero essenziale. Usa solo le immagini di riferimento realmente necessarie al prompt specifico; aggiungerne altre diluisce il controllo.
- Allinea il più possibile le proporzioni, così il modello non deve conciliare composizioni in conflitto.
- Usa coerentemente URL pubblici o base64 nella stessa richiesta, senza mescolare i metodi di trasporto.
Durante l'integrazione, invia una volta una richiesta con due immagini per verificare che entrambi i riferimenti influenzino chiaramente l'output, poi costruisci sopra logiche più complesse.
Scegliere il livello di risoluzione
Il campo resolution seleziona il livello di output per image-to-image di minimax-h3-image. Non è solo una manopola estetica — cambia il carico computazionale, la latenza della risposta e la dimensione del payload che finirai per gestire.
Come valutare i compromessi:
- Scegli il livello più basso che soddisfa il caso d'uso. Le miniature di una vista elenco non richiedono lo stesso livello di un banner principale. Ridurre la risoluzione di un output ad alta risoluzione in seguito spreca tempo e denaro.
- Aspettati che la latenza cresca con la risoluzione. I livelli più alti fanno più lavoro per richiesta, quindi il budget di timeout e intervallo di polling deve riflettere il livello scelto.
- Osserva la dimensione del payload. Gli input di riferimento base64 e gli output ad alta risoluzione aumentano entrambi il volume di trasferimento; se sposti molte immagini, tieni d'occhio i corpi di richiesta e risposta.
La fatturazione segue il livello di risoluzione richiesto — le richieste sono fatturate in base al livello con cui vengono eseguite, quindi usare un livello troppo alto per casi d'uso piccoli costa silenziosamente di più. Consulta le tariffe aggiornate sul pannello prezzi invece di codificare ipotesi fisse.
Una strategia di integrazione ragionevole: durante lo sviluppo usa un livello medio per la velocità, poi, una volta definiti prompt e set di immagini di riferimento, porta gli asset critici a un livello più alto. Cambiare risoluzione più tardi invalida le tue misurazioni di latenza, quindi fai i benchmark al livello con cui prevedi realmente di andare in produzione.
Gestire il ciclo di vita asincrono
Ogni chiamata image-to-image su hiapi segue lo stesso ciclo: invia, cattura l'id attività, interroga fino allo stato terminale, poi recupera il risultato. Rendere robusto questo ciclo è la maggior parte del lavoro di un client di produzione.
Invia e registra
Tratta l'id attività come la tua maniglia persistente. Registralo non appena arriva la risposta di invio, prima di qualsiasi altra cosa — se il processo si interrompe durante il polling, questo id ti permette di riprendere invece di rigenerare.
Interroga con backoff
Un polling fisso ogni due secondi va bene per l'uso interattivo, ma è dispendioso per i lotti lunghi. Parti con un intervallo breve e aumentalo gradualmente, con un tetto massimo, così puoi comunque rilevare il completamento in modo tempestivo.
def next_interval(current: float, cap: float = 15.0, factor: float = 1.5) -> float:
return min(current * factor, cap)
Rispetta gli stati terminali
Esci dal ciclo solo in caso di successo o fallimento. Trattare qualsiasi risposta non vuota come "completata" è il bug asincrono più comune — finiresti per leggere un risultato che non esiste ancora.
Metti limiti a tutto
Imposta timeout per ogni chiamata HTTP e una scadenza complessiva per l'attività. Se la scadenza passa, lancia un errore chiaro invece di continuare a girare a vuoto. Per errori di rete transitori, riprova il polling con backoff; non reinviare ciecamente, perché creeresti lavoro duplicato.
Pulisci
Una volta recuperato il risultato, salva tempestivamente l'URL o i byte dell'immagine nel tuo storage. I risultati delle attività sono maniglie temporanee, non la CDN a lungo termine della tua applicazione.
Risoluzione dei problemi e checklist di produzione
Questi sono i fallimenti che gli sviluppatori incontrano più spesso con image-to-image di minimax-h3-image, insieme ai controlli che li prevengono.
Fallimenti al primo avvio
- 401 / 403 — bearer token mancante, scaduto o con spazi bianchi iniziali o finali. Verifica che la variabile d'ambiente sia esportata nella shell che esegue la richiesta.
- 422 o errori di validazione — controlla il corpo della risposta di errore; di solito indica il campo. La causa comune è mettere
promptal livello superiore invece che dentroinput. - JSON malformato — valida il file del payload con
jq .prima di inviarlo.
Fallimenti a runtime
- L'attività non si completa mai — verifica di interrogare con l'id realmente ricevuto, non con un segnaposto. Controlla che la tua scadenza sia abbastanza lunga per il livello di risoluzione scelto.
- Risultato vuoto per un'attività "completata" — leggi con precisione il campo di stato; anche gli stati di fallimento restituiscono un corpo di risposta.
- Immagine di riferimento ignorata — prima di dare la colpa al modello, ricontrolla la formulazione del prompt e l'ordine delle immagini di riferimento.
Checklist prima del rilascio
- Chiave API e URL di base letti da variabili d'ambiente, mai committati nel repository.
- Ogni chiamata HTTP ha un timeout esplicito.
- Il polling usa un backoff limitato, con una scadenza complessiva rigida.
- Gli stati terminali sono gestiti esplicitamente; non si cade nel ramo di parsing del risultato.
- I risultati vengono scaricati e archiviati dalla tua applicazione, non collegati direttamente dalla risposta dell'attività.
- I prompt con più riferimenti specificano quale immagine controlla quale attributo.
- Il livello di risoluzione è stato sottoposto a benchmark sui valori con cui prevedi di andare in produzione.
- I log registrano l'id attività, così i lavori falliti sono tracciabili e ripristinabili.
Ogni volta che qualcosa non va, riesegui la richiesta minima vista prima — isola se il problema è nel payload o nel codice circostante. Con la struttura delle richieste, i client curl e Python, la gestione di più riferimenti e un ciclo di polling disciplinato, hai tutto ciò che serve per mettere in produzione in modo affidabile image-to-image di minimax-h3-image su hiapi.
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