Tutoriale
Usare flux-2/image-to-image tramite l'API HiAPI: tutorial con curl e Python
In questa pagina
A cosa serve flux-2/image-to-image e in quali casi usarlo
flux-2/image-to-image è un endpoint di editing, non un generatore puro da testo a immagine. Devi fornirgli due cose: un'immagine di riferimento e un'istruzione di modifica scritta in linguaggio naturale. Il modello legge l'immagine di riferimento come contesto visivo — soggetto, composizione, stile, illuminazione — e genera una nuova immagine che segue la tua istruzione restando ancorata a quel riferimento.
Questa distinzione è importante quando progetti la pipeline. Con il testo-a-immagine descrivi tutto da zero e poi speri che il modello si avvicini alla tua intenzione. Con l'immagine-a-immagine hai già un materiale visivo e vuoi una trasformazione controllata: ridisegnare lo stile di una foto prodotto, sostituire lo sfondo, regolare l'atmosfera della scena o iterare un design mantenendo stabile la composizione di fondo.
Scenari adatti
- Varianti di materiale. Generare più trattamenti stilizzati a partire da un'immagine di riferimento già approvata.
- Modifiche guidate. Applicare cambiamenti mirati ("rendi la luce più calda", "sostituisci lo sfondo con una parete da studio a tinta unita") senza rigenerare l'intera scena.
- Coerenza in un insieme di risultati. Riusare la stessa immagine di riferimento per far condividere a un lotto di output lo stesso ancoraggio visivo.
- Strumenti human-in-the-loop. Permettere agli utenti di caricare un'immagine, descrivere una modifica e ricevere il risultato direttamente nella tua interfaccia.
Scenari non adatti
- Ritocco o compositing con precisione a livello di pixel. Questo è un modello generativo, non un editor raster.
- Situazioni senza alcuna immagine di riferimento — in questi casi il testo-a-immagine è un punto di partenza migliore.
- Qualsiasi flusso di lavoro in cui l'istruzione debba portare da sola tutti i dettagli; l'immagine di riferimento conta davvero, e un riferimento scadente produce solo risultati scadenti.
Pensa a questo endpoint come a immagine di riferimento + istruzione -> immagine modificata. Tutto il tutorial si basa su questa forma: come inviare, come leggere il risultato restituito e come mantenerlo in funzione quando la rete non collabora.
Prerequisiti e configurazione dell'autenticazione
Prima della prima chiamata, prepara tre cose.
1. Un account HiAPI
Registrati e apri la console. Tutte le richieste di questo tutorial passano dall'API unificata HiAPI, quindi non serve registrarsi a singoli provider né installare un SDK per ciascuno.
2. Una chiave API
Crea una chiave API nella console. Trattala come una password: non inserirla in un repository di codice, non incollarla nel codice client e non scriverla nei log. La prassi standard è caricarla a runtime da una variabile d'ambiente:
export HIAPI_API_KEY="your-api-key-here"
Poi fai riferimento a HIAPI_API_KEY ovunque serva la chiave. Se esegui il deploy in un container o su una piattaforma serverless, impostala come secret in quell'ambiente invece di incorporarla nell'immagine.
3. Un'immagine di riferimento accessibile
L'endpoint richiede un'immagine di riferimento, quindi decidi in anticipo come fornirla. Due modi comuni:
- Un URL che l'API può scaricare, ad esempio un link firmato verso il tuo object storage.
- Byte codificati in Base64, inviati inline nel corpo della richiesta, così eviti di esporre URL interni ma aumenti la dimensione del payload.
Scegli prima un'immagine di test piccola — qualche centinaio di KB basta per verificare l'integrazione. Gli upload di file grandi rallentano ogni retry e rendono il debug più difficile.
Punto di controllo
A questo punto dovresti avere una chiave memorizzata in una variabile d'ambiente e un'immagine di test accessibile dalla tua macchina. Cerca di non far comparire la chiave nella cronologia della shell (un file .env caricato da uno strumento è di solito più pulito di un export inline da riga di comando).
C'è anche un'abitudine che vale la pena adottare fin da subito: registrare gli ID delle richieste e i tempi di esecuzione fin dal primo giorno. Quando la produzione va storta, la differenza tra una richiesta tracciabile e una non tracciabile è enorme.
Costruire la richiesta: immagine di riferimento e istruzione di modifica
Ogni chiamata image-to-image si costruisce attorno a due input. Se azzecchi questi due, il resto è lavoro di idraulica.
Input uno: l'immagine di riferimento
L'immagine di riferimento è l'ancora. Dice al modello cosa contiene la scena e che aspetto ha prima di qualsiasi modifica. Consigli pratici:
- Fai corrispondere il rapporto d'aspetto dell'output che vuoi. Se il riferimento è un largo formato orizzontale e ti serve un output quadrato, a seconda della configurazione della chiamata prevedi ritagli o deformazioni.
- Parti da un'immagine pulita e ben illuminata. Un riferimento confuso produce modifiche confuse.
- Meglio un solo soggetto chiaro. Un collage disordinato dà al modello troppi ancoraggi in competizione tra loro.
Input due: l'istruzione di modifica
L'istruzione è la descrizione in linguaggio naturale della modifica che vuoi. La maggior parte delle differenze di qualità nasce qui. Trattala come un prompt a cui è allegata un'immagine di riferimento.
- Esprimi la modifica, non l'intera scena. "Sostituisci lo sfondo con una parete da studio bianca a tinta unita" è meglio di "prodotto su sfondo bianco" — quest'ultima induce il modello a ridisegnare tutto.
- Dichiara cosa deve restare invariato. Formulazioni come "mantieni invariati la posa e la composizione del soggetto" riducono molto la deriva.
- Specifica stile e luce. "Luce morbida da cielo coperto, colori poco saturi" dà al modello più informazioni utili di "rendilo più bello".
- Evita le contraddizioni. Se il riferimento è una scena esterna di giorno e chiedi un interno notturno, aspettati che il modello prenda una decisione che potrebbe non piacerti.
Il corpo della richiesta
La richiesta che invii a flux-2/image-to-image contiene l'identificatore del modello, l'immagine di riferimento e l'istruzione. Un modello mentale utile:
{
"model": "flux-2/image-to-image",
"input": {
"image": "<URL o immagine di riferimento base64>",
"prompt": "<istruzione di modifica>"
}
}
Se il riferimento è in base64, costruiscilo come data URI secondo lo schema della richiesta, oppure passa la codifica grezza insieme al tipo MIME. Se è un URL, assicurati che il link sia pubblicamente accessibile durante la chiamata — un link firmato che scade a metà richiesta produce errori incomprensibili.
Prima itera, poi integra
Prima di collegare qualsiasi cosa al codice, scrivi due o tre istruzioni sulla stessa immagine di riferimento e confronta gli output. Il modello si comporta in modo prevedibile quando l'istruzione è specifica, e in modo instabile quando è vaga; scoprirlo ora costa molto meno che scoprirlo in produzione.
Una richiesta curl funzionante
Il modo più rapido per verificare chiave, immagine di riferimento e istruzione è una chiamata curl. L'esempio seguente presume che la chiave sia in HIAPI_API_KEY e che il riferimento sia raggiungibile via URL.
curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "flux-2/image-to-image",
"input": {
"image": "https://your-bucket.example.com/reference.jpg",
"prompt": "Sostituisci lo sfondo con una parete da studio bianca a tinta unita. Mantieni invariati la posa, la composizione del soggetto e l illuminazione sul soggetto."
}
}'
Alcuni punti da notare:
- La chiave viaggia nell'header
Authorizationcome token bearer. Non inserirla mai nell'URL. Content-Typeè JSON. Dimenticarlo è una causa comune di 4xx poco comprensibili.- L'id del modello sta nel corpo della richiesta, così lo stesso endpoint può essere instradato verso altri modelli cambiando un solo campo.
- L'istruzione è una frase completa, non un elenco di parole chiave. È voluto — vedi la sezione precedente.
Leggere l'output grezzo
Esegui una volta e guarda l'intera risposta prima di scrivere qualsiasi codice di parsing. Se ti aiuta, passala a un formattatore:
curl -sS -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
Salvare il corpo della richiesta in un file (request.json) è più comodo da iterare che modificare stringhe quotate nella shell, e ti dà un artefatto persistente che potrai usare in seguito per riprodurre un bug.
Se serve base64 invece dell'URL
Sostituisci il valore di image con un data URI costruito dal tuo file:
python - <<'PY'
import base64, json, pathlib
data = base64.b64encode(pathlib.Path("reference.jpg").read_bytes()).decode()
body = {
"model": "flux-2/image-to-image",
"input": {
"image": f"data:image/jpeg;base64,{data}",
"prompt": "Rendi la luce più calda e abbassa leggermente il contrasto.",
},
}
pathlib.Path("request.json").write_text(json.dumps(body))
PY
Ora la stessa chiamata curl funziona, perché il payload è salvato in request.json. Se la chiamata riesce, hai tutto il necessario per passare a Python.
La stessa chiamata in Python
La versione Python resta volutamente semplice: costruisce lo stesso dizionario, lo invia con lo stesso header e tiene endpoint e modello in costanti, così non divergono dalla versione curl.
import os
import requests
API_URL = "https://api.hiapi.ai/v1/images/generations"
MODEL = "flux-2/image-to-image"
def edit_image(reference_url: str, instruction: str, timeout: float = 60.0) -> dict:
api_key = os.environ["HIAPI_API_KEY"] # fallisce subito se non impostata
payload = {
"model": MODEL,
"input": {
"image": reference_url,
"prompt": instruction,
},
}
response = requests.post(
API_URL,
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=timeout,
)
response.raise_for_status()
return response.json()
if __name__ == "__main__":
result = edit_image(
"https://your-bucket.example.com/reference.jpg",
"Sostituisci lo sfondo con una parete da studio bianca a tinta unita. "
"Mantieni invariati la posa, la composizione del soggetto e l illuminazione sul soggetto.",
)
print(result)
Perché è organizzato così
- Usa
os.environ["HIAPI_API_KEY"]invece di.get(), così una chiave mancante genera subito un errore invece di inviare una richiesta non autenticata. timeoutè esplicito. La generazione di immagini non è istantanea; una richiesta senza timeout finisce per bloccare il processo worker.raise_for_status()viene chiamato prima del parsing. Vuoi un'eccezione su 4xx o 5xx, non unKeyErrorconfuso da qualche altra parte più avanti.- Endpoint e modello sono costanti di modulo, il che rende banale puntare la suite di test a un server stub.
Usare input base64
Se passi byte invece di un URL, codifica il file e costruisci il data URI nello stesso punto in cui costruisci il payload:
import base64, pathlib
def as_data_uri(path: str, mime: str = "image/jpeg") -> str:
raw = pathlib.Path(path).read_bytes()
return f"data:{mime};base64," + base64.b64encode(raw).decode()
Poi chiama edit_image(as_data_uri("reference.jpg"), instruction). Tieni separato il passo di codifica dalla funzione di richiesta, così potrai testare tramite unit test l'assemblaggio di validazione e prompt senza toccare la rete.
Interpretare la risposta
La chiamata restituisce un oggetto JSON. Ora estrai l'immagine modificata in modo che non si rompa anche se in futuro la risposta aggiungerà campi.
Verifica prima, non dare per scontato
Durante lo sviluppo esporta una risposta grezza e nota dove si trova il riferimento all'immagine — di solito un URL o un payload base64 annidato nella struttura del risultato. Poi scrivi accessor che ne verificano la presenza invece di scendere a capofitto nelle chiavi annidate.
def extract_image_url(response: dict) -> str:
data = response.get("data") or []
if not data:
raise ValueError(f"Nessun dato immagine nella risposta: {response}")
first = data[0]
url = first.get("url") or first.get("b64_json")
if not url:
raise ValueError(f"Payload immagine non riconosciuto: {first}")
return url
Due abitudini di questo codice vale la pena conservarle: fallire in modo rumoroso includendo il payload reale nel messaggio di errore e accettare entrambe le forme (URL o base64) invece di codificarne una sola. Il formato delle risposte evolve; un lettore tollerante sopravvive.
Persisti subito
L'URL restituito può essere temporaneo. Se l'immagine è importante, scaricala nello stesso task e salvala nel tuo bucket:
def persist(url: str, dest: str) -> None:
if url.startswith("data:"):
header, b64 = url.split(",", 1)
import base64, pathlib
pathlib.Path(dest).write_bytes(base64.b64decode(b64))
return
with requests.get(url, stream=True, timeout=60) as r:
r.raise_for_status()
with open(dest, "wb") as f:
for chunk in r.iter_content(1 << 16):
f.write(chunk)
La persistenza ti dà anche una chiave stabile da registrare nel database, molto più utile di un link che può corrompersi.
Valida ciò che hai ottenuto
Controlli economici scoprono errori costosi. Verifica che il file non sia vuoto, che il suo magic number corrisponda a un formato immagine e, facoltativamente, che le dimensioni siano quelle attese. Rifiutare un'immagine corrotta o troncata al confine è molto meglio che servirla all'utente.
Registra le informazioni di provenienza
Memorizza insieme all'output l'id del modello, il testo dell'istruzione, la chiave dell'immagine di riferimento e il timestamp. Quando tre settimane dopo qualcuno chiederà perché una certa immagine è così, quella riga di registro sarà la risposta — e rende banale rieseguire una specifica modifica.
Retry e gestione degli errori in produzione
Le chiamate di generazione immagini falliscono per motivi molto diversi, e confonderli è un classico bug di produzione.
Distingui errori transitori ed errori definitivi
- Transitori — timeout, reset della connessione, 429 per rate limiting, risposte 5xx. La stessa richiesta ritentata dopo una pausa ha buone probabilità di riuscire.
- Definitivi — 400 richiesta non valida, 401 chiave errata o mancante, 404 modello sconosciuto, errori di validazione del payload. Ritentarli spreca tempo e denaro e ritarda la vera correzione.
Ritenta solo la prima categoria. Per la seconda, fai fallire subito il task ed esponi il messaggio di errore — quasi sempre ti dice esattamente quale campo è il problema.
Ritenta con backoff e jitter
import random, time, requests
RETRYABLE = {429, 500, 502, 503, 504}
def call_with_retries(fn, attempts: int = 5, base: float = 1.0):
last = None
for i in range(attempts):
try:
return fn()
except requests.HTTPError as e:
status = e.response.status_code if e.response is not None else None
if status not in RETRYABLE:
raise
last = e
except (requests.Timeout, requests.ConnectionError) as e:
last = e
delay = base * (2 ** i) + random.uniform(0, 0.5)
time.sleep(delay)
raise RuntimeError("Tentativi esauriti") from last
Il backoff esponenziale evita di martellare un servizio già in difficoltà; il jitter evita che un lotto di processi worker ritenti in modo sincronizzato. Limita sempre il numero di tentativi e il tempo totale — un ciclo illimitato è peggio di un fallimento pulito.
Rispetta il rate limiting
Quando ricevi un 429, prima di applicare il backoff rispetta qualsiasi indicazione di retry presente negli header della risposta. Se esegui grandi lotti, aggiungi un limite di concorrenza dalla tua parte invece di affidarti al server per limitarti il traffico.
Rendi visibili i fallimenti
- Etichetta i retry con un id di task univoco e registra ogni tentativo con esito e durata.
- Esponi metriche sul tasso di retry; un lento aumento è un segnale precoce che qualcosa a monte si sta degradando.
- Dopo l'ultimo tentativo fallito, sposta il task in una dead-letter queue allegando l'intero corpo della risposta, mai solo un messaggio come "fallito".
Idempotenza e ragionevolezza dei costi
Una richiesta ritentata può essere già riuscita sul server anche se il tuo client non ha mai visto la risposta. Se il tuo prodotto non tollera output duplicati, assegna una chiave ai task con un tuo id e riconcilia prima di ritentare. E poiché le chiamate sono fatturate a consumo, attenzione ai cicli di retry che gonfiano silenziosamente i costi — un consumer bloccato che ritenta all'infinito è il bug più costoso in questo senso.
Insidie comuni e passi successivi
La maggior parte dei problemi di integrazione attorno a flux-2/image-to-image deriva da una breve serie di errori. Prima di rilasciare, controlla il tuo codice rispetto a questi punti.
- Istruzioni vaghe. "Miglioralo" produce risultati casuali; "rimuovi il testo dall'insegna e mantieni la forma dell'insegna" produce risultati utilizzabili. La specificità è la leva più grande sulla qualità.
- Riferimento non adatto. Rapporti d'aspetto sbagliati, sorgenti sfocate o collage disordinati non si salvano con un prompt migliore.
- URL scaduti. Un link firmato che si interrompe durante la richiesta provoca fallimenti che sembrano errori del server. Usa una validità sufficientemente lunga o passa al base64.
- Struttura della risposta codificata rigidamente. Scendere dritto nelle chiavi annidate trasforma una piccola modifica di schema in un guasto. Usa estrattori difensivi con errori chiari.
- Nessun timeout. Un timeout mancante occupa un processo worker a tempo indefinito e maschera il vero problema.
- Retry di errori definitivi. Un 400 non si aggiusta da solo. Leggi il messaggio.
- Output perso. Se l'URL restituito è temporaneo e non hai persistito l'immagine, non hai nulla.
- Logging disattento di segreti e prompt. Le chiavi non devono mai comparire nei log; le istruzioni fornite dall'utente possono richiedere mascheramento in base al tuo dominio.
Passi successivi
Quando il flusso di una singola chiamata è solido, le estensioni naturali sono: incapsulare la chiamata in un task in background per mantenere reattiva la UI; memorizzare le coppie istruzione/risposta per fare A/B test sulla formulazione dei prompt; e, se gli utenti forniscono le proprie immagini, aggiungere uno strato di moderazione o validazione sull'input. Esplora la pagina del modello flux-2/image-to-image e la documentazione HiAPI per vedere quali parametri potrebbe servirti il tuo caso d'uso in seguito. Costruisci la cosa minima che funziona, misurala e lascia che la qualità delle istruzioni faccia il lavoro pesante.
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