Tutoriale
Come chiamare fibo-2.0/image-to-image tramite l'API HiAPI: pratica con curl e Python
In questa pagina
Il ruolo di fibo-2.0/image-to-image nella pipeline
I modelli text-to-image partono da un prompt, quelli image-to-image partono da un'immagine che hai già. La differenza sembra minima, ma determina la posizione del modello nella pipeline: fibo-2.0/image-to-image non è più il primo passo che produce il materiale di partenza, bensì il passo di editing che trasforma un'immagine esistente.
Il flusso tipico è questo: ottieni o generi un'immagine di base, la invii a fibo-2.0/image-to-image con un'istruzione che descrive la modifica desiderata, poi passi il risultato alle fasi successive: revisione, compositing, archiviazione o un'altra chiamata al modello. Poiché il modello riceve sia l'immagine di input sia il prompt, può ridipingere lo stile, regolare o trasformare le parti che descrivi mantenendo composizione, posizione del soggetto e struttura complessiva.
Quando scegliere image-to-image invece di text-to-image
Scegli image-to-image quando l'output deve mantenere un legame riconoscibile con un'immagine esistente: ridipingere lo stile di una foto preservando il soggetto, regolare illuminazione o trattamento cromatico, generare varianti di materiale già approvato oppure ripulire una bozza grezza prima dell'uso finale. Se non hai un'immagine di partenza ma solo una descrizione, scegli text-to-image.
Cosa richiede questa interfaccia
La chiamata è l'invio di un job: invii l'immagine di input, il prompt e i parametri che vuoi controllare, e l'API restituisce un job tracciabile. Considera questa interfaccia come una fase ben definita di una catena più ampia, non come un'applicazione di editing completa: come preparare l'immagine di input e come gestire il risultato spetta a te.
Poiché la richiesta è essenzialmente asincrona, anche il design dell'integrazione deve ruotare attorno a questo: invia, salva l'identificatore del job, esegui il polling finché il job non è completato, quindi recupera il riferimento all'output. Il resto di questa guida serve proprio a costruire questo flusso.
Prepararsi prima di inviare la richiesta
Prima della prima chiamata servono tre cose: le credenziali, una corretta comprensione della forma dell'interfaccia e un'immagine di input pronta.
Credenziali
Tutte le richieste all'API HiAPI si autenticano con una chiave API. La chiave deve essere conservata lato server: non inserirla mai nel codice del browser né salvarla nel repository. Il modo più pulito è leggerla da una variabile d'ambiente, così lo stesso codice funziona sia in locale sia nell'ambiente di distribuzione:
export HIAPI_API_KEY="your-api-key"
Se non hai ancora una chiave, creala prima nella console del tuo account HiAPI e poi prosegui.
Forma dell'interfaccia
Il modello è identificato nell'API HiAPI come fibo-2.0/image-to-image. Tutte le chiamate ai modelli condividono lo stesso URL di base e le stesse convenzioni di richiesta: questo significa che, una volta ottenuta una chiamata funzionante, passare a un altro modello consiste principalmente nel cambiare l'identificatore del modello e i campi del payload.
Preparare l'immagine di input
Una richiesta image-to-image richiede un'immagine reale, non un URL che speri venga interpretato. Decidi in anticipo come fornirla: come file locale caricato con la richiesta oppure come riferimento accettato dall'API; e verifica che il formato sia utilizzabile prima di scrivere il codice dell'applicazione. I due fallimenti più comuni nelle prime richieste sono: inviare un percorso che esiste solo sul tuo portatile e inviare un file in un formato che l'interfaccia non accetta.
Checklist pratica prima di costruire la chiamata:
- L'immagine è un file reale che il tuo linguaggio è in grado di leggere.
- Il prompt descrive l'editing desiderato in linguaggio naturale, non è solo un mucchio di parole chiave.
- Sai quali parametri inviare e quali lasciare ai valori predefiniti.
- La tua chiave API è presente nell'ambiente da cui parte la richiesta.
Una volta pronto tutto questo, si può passare alla richiesta stessa.
Analisi riga per riga di una richiesta curl funzionante
Inizia con curl. Elimina ogni astrazione tra te e la richiesta HTTP: se qualcosa va storto, sai che il problema è nella richiesta e non nella libreria client.
curl -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "fibo-2.0/image-to-image",
"prompt": "trasforma la scena in una morbida illustrazione ad acquerello, mantieni il soggetto e l'inquadratura",
"image": "BASE64_ENCODED_IMAGE_OR_ACCEPTED_REFERENCE",
"n": 1
}'
Di seguito il ruolo di ciascuna parte.
Riga di richiesta
-X POST imposta il metodo. L'URL è l'indirizzo di base dell'API HiAPI più il percorso di generazione delle immagini. Metti l'indirizzo di base in una variabile o in un valore di configurazione per evitare di codificarlo in più punti: così le modifiche future richiederanno un solo intervento.
Header
Authorization: Bearer $HIAPI_API_KEY porta le tue credenziali; la shell espande la variabile d'ambiente esportata in precedenza, quindi la chiave non appare in forma letterale nella cronologia dei comandi. Content-Type: application/json indica all'API di interpretare il corpo come JSON. Inviare un corpo JSON senza questo header è una causa comune di errori difficili da capire.
Payload
model identifica fibo-2.0/image-to-image. prompt è la tua istruzione: descrive l'editing, non l'intera immagine di output, perché l'immagine di input contiene già la struttura. image è la forma dell'immagine di input accettata dall'interfaccia; se la incorpori direttamente, è la codifica base64 del contenuto del file. n controlla il numero di output richiesti; lasciare il valore predefinito è il punto di partenza più sicuro.
Se l'immagine è grande, incorporarla direttamente nel comando shell diventa scomodo. Codificala prima in un file e poi referenziala, oppure passa direttamente al metodo Python della sezione successiva: lì leggere il file e codificarlo richiede una sola riga.
Leggere la risposta
Non dare per scontato che la risposta contenga i byte dell'immagine già completata. Esegui la chiamata curl ed esamina il JSON: quello che cerchi è un identificatore di job o un campo di stato per capire se il lavoro è concluso o ancora in corso. Cattura la struttura prima di scrivere qualsiasi codice di parsing, perché la forma della risposta determina come eseguirai il polling.
Portare la richiesta in Python
Python rende la richiesta più facile da mantenere e permette di incapsularla in una funzione riutilizzabile in tutto il codebase. Ecco un client leggero che implementa la stessa richiesta:
import base64
import os
import time
import requests
BASE_URL = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]
def encode_image(path: str) -> str:
with open(path, "rb") as f:
return base64.b64encode(f.read()).decode("utf-8")
def submit_image_edit(image_path: str, prompt: str) -> dict:
payload = {
"model": "fibo-2.0/image-to-image",
"prompt": prompt,
"image": encode_image(image_path),
"n": 1,
}
response = requests.post(
f"{BASE_URL}/images/generations",
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
timeout=60,
)
response.raise_for_status()
return response.json()
Perché questa struttura
Separare encode_image e submit_image_edit rende indipendenti la gestione dei file e quella HTTP, e ciascuna diventa più facile da testare. Leggere la chiave dall'ambiente al momento dell'importazione fa fallire subito se manca, invece di generare un 401 dopo diversi livelli. Impostare esplicitamente un timeout evita che una connessione bloccata faccia restare appeso indefinitamente un processo di lavoro.
Gestire il corpo della risposta
raise_for_status() trasforma un errore a livello HTTP in un'eccezione catturabile con il log del corpo della risposta: molto più utile che interpretare silenziosamente un oggetto di errore come se fosse un successo. Una volta ottenuto il JSON analizzato, registra l'identificatore di job che contiene e, durante lo sviluppo, registra la risposta completa per vedere con precisione quali campi esistono. Non scrivere un parser basato su supposizioni: scrivilo sulla base della risposta che hai effettivamente osservato.
Mantenere la riutilizzabilità
Due piccoli miglioramenti ripagano presto: mettere l'URL di base e il nome del modello in costanti, così altre chiamate ai modelli possono condividere lo stesso client; e far restituire alla funzione di invio una struttura tipizzata (una piccola dataclass o un dict con chiavi note), in modo che il codice di polling abbia un contratto stabile su cui contare.
Gestire il ciclo di vita asincrono e il polling
I lavori sulle immagini non sono istantanei. L'integrazione deve trattare l'invio e il completamento come due eventi distinti.
Passo 1: inviare e persistere
Dopo aver inviato il job, salva l'identificatore in una posizione persistente: una riga di database, un messaggio in coda o almeno una riga di log. Se il processo si interrompe tra l'invio e il completamento, un job non registrato è lavoro perso. Associa l'identificatore all'entità del tuo sistema che possiede quel risultato, così da poter riconciliare in seguito.
Passo 2: polling con backoff
Esegui il polling dell'endpoint di stato del job a intervalli ragionevoli. Un ciclo stretto che martella ripetutamente l'endpoint di stato spreca risorse ed è anche l'errore asincrono più comune:
def wait_for_job(job_id: str, interval: float = 2.0, max_wait: float = 180.0) -> dict:
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
response = requests.get(
f"{BASE_URL}/jobs/{job_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
response.raise_for_status()
job = response.json()
if job.get("status") in {"succeeded", "failed"}:
return job
time.sleep(interval)
interval = min(interval * 1.5, 10.0)
raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")
Partire da un intervallo breve e aumentarlo progressivamente mantiene reattivi i primi controlli ed evita richieste ad alta frequenza nel lungo periodo. Una scadenza rigida impedisce di attendere all'infinito un job che non si completerà mai.
Passo 3: trattare i fallimenti come risultati normali
Un job completato non è necessariamente un job riuscito. Controlla lo stato prima di leggere l'output e gestisci esplicitamente il ramo di errore: registra i dettagli dell'errore restituito dal job, segnala al chiamante che è possibile riprovare e decidi se il nuovo tentativo debba riutilizzare lo stesso input o rigenerarlo. Un job scaduto lato client potrebbe essere ancora in esecuzione sul server, quindi non reinviarlo ciecamente senza aver controllato.
Passo 4: recuperare e memorizzare il risultato
Quando il job segnala il successo, leggi il riferimento all'output che fornisce e scaricalo prontamente. Se vuoi conservare il risultato a lungo termine, copialo nel tuo storage invece di fare affidamento sulla validità permanente del riferimento.
Errori comuni e come correggerli
La maggior parte dei fallimenti rientra in alcune categorie prevedibili. Passa in rassegna questa lista in ordine.
Errori di autenticazione
401 o 403 significano quasi sempre header errato o chiave mancante. Verifica che l'header sia esattamente Authorization: Bearer <key>, con uno spazio dopo Bearer; e controlla che la variabile d'ambiente sia effettivamente impostata nel processo che invia la richiesta, non solo nella tua shell interattiva. Incollare la chiave con spazi finali o virgolette di troppo è responsabile di una buona parte di questi problemi.
Payload malformato
400 o 422 di solito significano che l'API non riesce a interpretare il corpo della richiesta. Controlla tre cose in ordine: se è presente Content-Type: application/json, se il JSON è effettivamente analizzabile (una virgola finale lo rompe), se i campi obbligatori sono presenti con il nome corretto. Se invii dati immagine in base64, verifica che sia base64 valido e che il formato del file sottostante sia supportato: stringhe troncate o codificate due volte producono errori di validazione confusi.
Errori di polling
Se il job sembra non completarsi mai, verifica che stai facendo polling usando l'identificatore effettivamente restituito nella risposta di invio e che stai leggendo il campo di stato corretto. Un ciclo stretto che ignora lo stato failed sembra un blocco. Aggiungi un timeout rigido e registra i cambiamenti di stato osservati: quel log di solito rivela subito il problema.
Trappole nel parsing della risposta
Se il codice solleva un'eccezione durante la lettura del risultato, non tirare a indovinare la forma della risposta. Registra prima il corpo grezzo della risposta. I problemi comuni includono: scambiare un riferimento per dei byte, considerare sempre presenti campi che esistono solo in caso di successo, usare un parser del percorso di errore su una risposta di successo. Costruisci la logica di estrazione sulla base delle risposte che hai effettivamente visto.
Abitudine di triage rapido
Quando qualcosa non funziona, isola prima il livello: esegui il comando curl con lo stesso payload. Se curl riesce e Python fallisce, l'errore è nel client; se falliscono entrambi, l'errore è nella richiesta. Questo semplice test fa risparmiare più tempo di qualsiasi altra abitudine di debug.
Con una chiamata funzionante e un ciclo di polling robusto, fibo-2.0/image-to-image diventa un passo di editing affidabile: parti dalla pagina del modello su HiAPI e adatta la richiesta qui sopra alle tue immagini.
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