Blog

Tutoriale

Come chiamare fibo-edit-1.5 image-to-image tramite l'API HiAPI: guida con curl e Python

Guida pratica a una richiesta funzionante per la modifica delle immagini guidata da istruzioni

Nov 17, 2026
Immagine di copertina: su uno sfondo quasi nero, una fascia di punti verde menta che va da rada a densa, con un gruppo di punti blu petrolio lungo il bordo destro.
In questa pagina

Cosa può fare l'endpoint image-to-image di fibo-edit-1.5

fibo-edit-1.5/image-to-image è un endpoint di modifica delle immagini guidato da istruzioni. Non descrive una scena da zero: riceve un'immagine di riferimento e un'istruzione in linguaggio naturale, e restituisce una nuova immagine in cui la modifica è stata applicata mantenendo invariato il resto della composizione.

Questa impostazione influisce direttamente sul modo in cui progetti la richiesta. L'immagine di riferimento fornisce il contesto visivo — soggetto, inquadratura, illuminazione, stile — mentre l'istruzione fornisce la modifica. Una buona istruzione specifica chiaramente cosa cambiare e tace su ciò che deve restare invariato. "Sostituisci il cielo con un tramonto nuvoloso, mantenendo invariati l'edificio e il primo piano" comunica molto più di "rendila più bella".

Una chiamata riuscita produce una risorsa immagine modificata. A seconda di come viene invocato l'endpoint, la risposta restituisce l'output generato in una forma che puoi salvare o recuperare — consulta il riferimento dell'endpoint per conoscere la struttura esatta della risposta e i parametri supportati. Considera quel riferimento come l'unica fonte autorevole per i nomi dei campi, i formati immagine accettati e i limiti di dimensione, perché questi dettagli possono evolvere indipendentemente da questo documento.

Gli usi tipici includono il ritocco di foto di prodotto, la sostituzione dello sfondo, gli aggiustamenti di stile e le modifiche locali in cui una rigenerazione completa dell'immagine comprometterebbe la fedeltà. Se il tuo compito è generare da testo anziché modificare, questo endpoint non è lo strumento adatto; usa invece un modello text-to-image.

Un'aspettativa da stabilire subito: la modifica è per natura iterativa. La tua prima istruzione raramente centra il risultato perfetto, quindi costruisci il flusso di lavoro attorno a iterazioni a basso costo — cambia una sola variabile alla volta, mantieni invariata l'immagine di riferimento e confronta gli output prima di passare al passo successivo.

La struttura di una richiesta funzionante

Prima di scrivere qualsiasi codice, chiarisci quali input richiede una richiesta. Ogni chiamata a fibo-edit-1.5/image-to-image combina quattro tipi di informazione.

Autenticazione

Tutte le richieste passano attraverso l'interfaccia unificata di HiAPI e portano la tua chiave API nell'header Authorization. Conserva la chiave in una variabile d'ambiente anziché nel codice sorgente, e non fare mai commit di essa.

Immagine di riferimento

Devi fornire l'immagine sorgente su cui applicare la modifica. Ci sono due forme comuni: un URL pubblico che il servizio può recuperare, oppure dati codificati in base64 incorporati nel corpo JSON della richiesta. Gli URL sono più comodi per l'iterazione; il base64 evita la dipendenza da un hosting esterno. Consulta il riferimento dell'endpoint per sapere quali forme sono accettate e se esistono vincoli di dimensione o risoluzione.

Istruzione di modifica

È una stringa in linguaggio naturale che descrive la modifica. Scrivila all'imperativo, indica la regione o l'elemento da modificare e specifica cosa va conservato. Evita di accatastare più modifiche non correlate nella stessa istruzione — suddividile in più chiamate, così puoi capire quale ha causato un risultato scadente.

Controllo dell'output

Parametri opzionali, come dimensioni, formato di output o numero di immagini candidate. Alla prima chiamata mantieni i valori predefiniti, poi modificali consapevolmente. Ogni parametro che imposti è un'altra variabile da escludere quando qualcosa va storto.

Di conseguenza, un corpo di richiesta minimo ha due campi sostanziali — l'immagine e l'istruzione — racchiusi in un oggetto JSON, con l'eventuale aggiunta delle tue preferenze di output. Se sai rispondere a "quale immagine, quale modifica, in quale formato voglio il risultato", hai tutto ciò che serve per scrivere la chiamata.

Effettuare la chiamata con curl

Inizia da curl: isola il livello HTTP, così se qualcosa va storto sai che il problema è nella richiesta e non nel codice dell'applicazione.

Per prima cosa esporta la tua chiave:

 export HIAPI_API_KEY="your-api-key"

Poi invia il corpo JSON con l'URL dell'immagine di riferimento e l'istruzione:

curl -sS https://api.hiapi.ai/v1/fibo-edit-1.5/image-to-image \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "https://example.com/input.jpg",
    "prompt": "Sostituisci il cielo piatto con una morbida sfumatura di tramonto; mantieni invariati l'edificio e il primo piano."
  }'

Alcuni consigli pratici:

  • Verifica l'URL di base e il percorso sul riferimento dell'endpoint, non copiarli a memoria.
  • Usa -sS, così curl resta silenzioso in caso di successo ma mostra comunque gli errori di trasferimento.
  • Se non vuoi dipendere da un hosting esterno, codifica il file in base64 e sostituisci il valore di image con la stringa codificata, rispettando il nome del campo indicato nel riferimento.
  • In fase di esplorazione, passa l'output attraverso jq . per rendere la risposta più leggibile.

Per verificare la risposta, cerca il payload o l'URL dell'immagine restituita e aprilo. Se il corpo della risposta contiene un oggetto di errore, annota i campi type e message — ti diranno se il problema riguarda l'immagine, l'istruzione o la struttura della richiesta. Salva una risposta grezza riuscita in un file; diventerà la tua fixture di test quando scriverai il client Python, e in futuro una prova in caso di cambiamenti di comportamento.

Effettuare la stessa richiesta con Python

La versione Python deve corrispondere esattamente alla chiamata curl — stesso percorso, stessi header, stesso corpo — così ogni differenza sarà un bug nel tuo codice e non una differenza in ciò che stai richiedendo.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/fibo-edit-1.5/image-to-image"

payload = {
    "image": "https://example.com/input.jpg",
    "prompt": (
        "Sostituisci il cielo piatto con una morbida sfumatura di tramonto; "
        "mantieni invariati l'edificio e il primo piano."
    ),
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)
response.raise_for_status()
result = response.json()
print(result)

Inviare un file locale

Se stai modificando un file presente sul disco, codificalo e invia la stringa anziché l'URL:

import base64

with open("input.jpg", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")

payload = {
    "image": encoded,
    "prompt": "Cambia lo sfondo in un grigio neutro pulito; mantieni il prodotto nitido.",
}

Prima di affidarti a questo metodo, verifica sul riferimento dell'endpoint il nome esatto del campo e la codifica prevista.

Salvare l'output

Scrivi su disco l'immagine restituita, così puoi confrontare affiancati i risultati delle iterazioni e registrare quale istruzione ha prodotto quale risultato. Una piccola funzione di supporto che salva l'output con un nome derivato dall'hash dell'istruzione renderà i confronti successivi molto semplici.

Imposta sempre un timeout esplicito. La modifica delle immagini richiede più tempo di una semplice chiamata testuale, e una richiesta senza timeout può bloccare indefinitamente un processo worker in caso di stallo della rete.

Gestire gli errori e ripetere in sicurezza

I fallimenti possono essere raggruppati in alcune grandi categorie, ciascuna delle quali richiede una risposta diversa.

Errori del client

La richiesta stessa è errata: JSON malformato, campo immagine mancante, formato immagine non supportato, istruzione che il modello non può eseguire oppure problemi di autenticazione. Ripetere questi errori così come sono spreca solo tempo e quota — falliranno nello stesso identico modo. Correggi invece la richiesta. Quando incontri questo tipo di errore, registra il corpo completo della richiesta (con la parte dell'immagine troncata) e il messaggio di errore, poi correggi l'input.

Limiti di frequenza

Stai inviando richieste più velocemente del consentito. La risposta corretta è fare un passo indietro e riprovare, non martellare l'endpoint. Segui eventuali suggerimenti di retry forniti nella risposta; in caso contrario usa un backoff esponenziale.

Errori del server e transitori

Timeout, reset della connessione e malfunzionamenti a monte meritano un nuovo tentativo. È qui che entra in gioco una logica di retry idempotente.

Strategia di retry pratica

  • Riprova solo in caso di timeout, errori di connessione e risposte di limite di frequenza o del server.
  • Usa un backoff esponenziale con limite massimo — ad esempio, parti da un ritardo breve, raddoppia a ogni tentativo e fermati dopo un numero fisso e ridotto di tentativi.
  • Aggiungi un jitter al ritardo, così i processi worker paralleli non riprovano tutti nello stesso istante.
  • Non riprovare mai le richieste rifiutate per problemi di schema, formato o istruzione.
  • Registra ogni tentativo con il relativo numero e risultato, così puoi capire se i fallimenti si concentrano.
import random, time, requests

def edit_with_retry(payload, attempts=4):
    delay = 1.0
    for i in range(attempts):
        try:
            r = requests.post(URL, headers=HEADERS, json=payload, timeout=120)
        except (requests.Timeout, requests.ConnectionError):
            pass
        else:
            if r.status_code < 400:
                return r.json()
            if r.status_code not in (429, 500, 502, 503, 504):
                r.raise_for_status()
        time.sleep(delay + random.uniform(0, 0.5))
        delay = min(delay * 2, 30)
    raise RuntimeError("La modifica continua a fallire dopo i tentativi ripetuti")

Consideralo uno scheletro: allinea i codici di stato ritentabili con ciò che l'endpoint restituisce realmente e centralizza la strategia in un unico punto, così tutti i chiamanti la condividono.

Controlli prima della messa in produzione

Prima di collegare l'endpoint all'ambiente di produzione, completa una breve lista di controllo.

Verifica due volte il percorso felice

Esegui di nuovo la chiamata curl salvata e il client Python sugli stessi input, e conferma che producano risultati equivalenti. Se divergono, il tuo corpo di richiesta in realtà non è lo stesso.

Calibra le istruzioni su input reali

Prova le tue istruzioni con immagini rappresentative, non solo con un singolo campione. La qualità della modifica dipende in larga misura dalla specificità dell'istruzione e da quanto l'immagine di riferimento supporta quella modifica. Conserva un piccolo insieme di coppie prompt-output come suite di test di regressione; quando modifichi la formulazione, potrai vedere cosa è migliorato e cosa è peggiorato.

Controlla limiti e formati

Verifica sul riferimento dell'endpoint i formati immagine accettati, le dimensioni massime e gli eventuali limiti di dimensione della richiesta. Esegui la validazione localmente prima dell'invio — rifiutare un'immagine scadente sul client è più rapido ed economico di un round-trip.

Verifica chiavi e log

Assicurati che la chiave API provenga da una variabile d'ambiente, che i log delle richieste tronchino il payload dell'immagine e che nessuna chiave compaia nei report degli errori.

Conferma il comportamento in caso di errore

In un ambiente di pre-produzione, forza un timeout e un corpo di richiesta malformato, e verifica che la tua strategia di retry si comporti correttamente e che i fallimenti permanenti vengano esposti al chiamante anziché svanire silenziosamente.

Una volta che tutto questo è superato, l'integrazione diventa banale nel migliore dei modi. Ottieni l'elenco autorevole dei parametri dal riferimento dell'endpoint image-to-image di fibo-edit-1.5, poi costruisci a partire da una chiamata curl funzionante.

Inizia a creare con artefatti IA persistenti

Ottieni la tua chiave API e chiama modelli di immagini, video e audio tramite un'unica API basata sui task.

Leggi la documentazione API