Come si usa l'API FIBO 1.5? Generazione ed editing operativi in 5 minuti

TL;DR

• FIBO 1.5 è una coppia di endpoint «generazione + editing»: fibo-gen-1.5/text-to-image genera immagini realistiche da testo (anche il testo nell'immagine viene reso accuratamente), fibo-edit-1.5/image-to-image modifica un'immagine con una frase (fino a 4 immagini di riferimento, con possibilità di modificare solo una parte tramite maschera). Apri la pagina del modello Gen per provarlo: i nuovi utenti ricevono 200 crediti alla registrazione.
• Stesso prezzo: $0.0575 per immagine; una pipeline generazione + editing costa $0.115 (vedi la pagina dei prezzi).
• Le chiamate passano dall'endpoint HiAPI /v1/tasks: si invia il task e si ottiene un taskId, poi si interroga il risultato; il campo dell'istruzione per l'endpoint di editing si chiama instruction, non prompt.

Cosa sa fare

• Immagini realistiche + testo accurato: testi nell'immagine come etichette di prodotto o insegne vengono scritti lettera per lettera (l'etichetta nell'esempio sotto è NOIR 07).
• Modifica con una frase: Edit usa instruction per descrivere cosa cambiare; ciò che non viene menzionato (posa, volto, sfondo) resta invariato.
• Composizione con un massimo di 4 immagini: cambio di vestiti, sfondo, inserimento di prodotti in una scena; image_urls fa riferimento in ordine.
• Modifica locale con maschera: bianco = area da modificare, nero = da mantenere.

Qui sotto un risultato reale di Gen:

Luxury product photo of an amber glass perfume bottle on wet black marble, gold cap, soft rim light, droplets on the glass, the label reads 'NOIR 07' in elegant serif letters

(Significato: foto di prodotto di lusso: bottiglia di vetro ambra su marmo nero bagnato, tappo dorato, luce di contorno morbida, goccioline sul vetro, etichetta con scritto NOIR 07. Proporzioni 4:5.)

fibo-gen-1.5/text-to-image, 4:5, 768×960, $0.0575.

Genera con questo prompt →

Quale dei due endpoint scegliere

	fibo-gen-1.5/text-to-image	fibo-edit-1.5/image-to-image
Cosa fa	Genera immagini realistiche da testo	Modifica un'immagine esistente con una frase
Input obbligatorio	prompt	image_urls (1–4 immagini) + instruction
Prezzo	$0.0575/immagine	$0.0575/immagine
Parametri distintivi	aspect_ratio 9 opzioni, seed (predefinito 5555)	mask_url maschera, seed (predefinito 5555)
Adatto a	Creare nuove immagini, materiali con testo	Cambio vestiti/sfondo/composizione, ritocchi locali

Pipeline tipica: Gen crea l'immagine base → Edit la trasforma in un set coordinato (cambio sfondo, colore, aggiunta elementi). Per scegliere i prompt in base allo scenario vedi la raccolta di prompt.

Due percorsi per iniziare

Browser in 3 passi: apri la pagina del modello → incolla il prompt, scegli le proporzioni → clicca genera, $0.0575 per immagine.

API in 3 passi: POST /v1/tasks per inviare → ottieni taskId → GET /v1/tasks/<taskId> per verificare success e scaricare.

curl: la prima immagine

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "fibo-gen-1.5/text-to-image",
  "input": {
    "prompt": "Luxury product photo of an amber glass perfume bottle on wet black marble, gold cap, soft rim light, droplets on the glass, the label reads '"'"'NOIR 07'"'"' in elegant serif letters",
    "aspect_ratio": "4:5",
    "seed": 2026
  }
}'

Endpoint di editing: cambia model in fibo-edit-1.5/image-to-image, scrivi l'istruzione in instruction e fai riferimento alle immagini in ordine (prova virtuale con due immagini):

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "fibo-edit-1.5/image-to-image",
  "input": {
    "image_urls": [
      "https://static.hiapi.ai/gallery/2026/10/78f963cb21d0242c.jpg",
      "https://static.hiapi.ai/gallery/2026/10/36246b7cabde4a1a.jpg"
    ],
    "instruction": "Dress the woman in image 1 with the mustard corduroy jacket from image 2, worn open over her white t-shirt. Keep her pose, face and the studio background.",
    "aspect_ratio": "3:4"
  }
}'

Modifica locale con maschera: mask_url può essere abbinata a una sola immagine; bianco = area da modificare (esattamente il contrario di Ideogram 4.5 Edit):

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "fibo-edit-1.5/image-to-image",
  "input": {
    "image_urls": ["https://static.hiapi.ai/gallery/2026/10/d9037da1559e78a6.jpg"],
    "mask_url": "https://static.hiapi.ai/gallery/2026/10/cae371f9e4689db5.png",
    "instruction": "Replace the floor under the sneaker with light wooden planks."
  }
}'

Python: invio, polling, download

import time, uuid, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "fibo-gen-1.5/text-to-image",
    "input": {
        "prompt": "Luxury product photo of an amber glass perfume bottle on wet black marble, gold cap, soft rim light, droplets on the glass, the label reads 'NOIR 07' in elegant serif letters",
        "aspect_ratio": "4:5",
        "seed": 2026,
    },
}

resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(3)

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # indirizzo temporaneo, scarica e salva al più presto
    img = requests.get(image_url, timeout=60)
    with open("output_image", "wb") as f:
        f.write(img.content)
    print("saved")

Tabella dei parametri

fibo-gen-1.5/text-to-image

Campo	Obbligatorio	Valori	Descrizione
prompt	Sì	1–10000 caratteri	Descrizione dell'immagine; il testo da mostrare va tra virgolette (the label reads '…')
aspect_ratio	No	1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 4:5 / 5:4 / 9:16 / 16:9, predefinito 1:1	9 proporzioni allo stesso prezzo
seed	No	Intero, predefinito 5555	Fisso anche se non specificato: stesso prompt, stesso risultato; per variare cambia seed

fibo-edit-1.5/image-to-image

Campo	Obbligatorio	Valori	Descrizione
image_urls	Sì	1–4 immagini	L'ordine è significativo; instruction fa riferimento in ordine (image 1, image 2)
instruction	Sì	≥1 carattere	Cosa modificare; ciò che non è menzionato resta invariato
aspect_ratio	No	Le stesse 9 opzioni	Valido solo con 2 o più immagini; con una sola immagine l'output mantiene le proporzioni originali
mask_url	No	URL dell'immagine	Solo per modifica a immagine singola; bianco = modifica, nero = mantieni; le dimensioni devono corrispondere all'immagine originale
seed	No	Intero, predefinito 5555	Riproducibilità con lo stesso input

Campi non previsti dalla tabella nel corpo della richiesta restituiscono direttamente 400.

Errori che incontrerai (testo originale dell'API)

Cosa hai fatto	Risposta
Gen senza prompt	400 invalid input: prompt: missing required field "prompt"
seed di Gen passato come stringa	400 invalid input: seed: got string, want integer
aspect_ratio scritto male	400 invalid input: aspect_ratio: value must be one of '1:1', '2:3', '3:2', '3:4', '4:3', '4:5', '5:4', '9:16', '16:9'
Edit senza instruction	400 invalid input: instruction: missing required field "instruction"
Edit con 5 immagini	400 invalid input: image_urls: maxItems: got 5, want 4
Maschera con 2 immagini	400 (quando è presente mask_url, image_urls può contenerne solo 1)
Saldo insufficiente	402 insufficient account balance; top up and retry

Inviare di nuovo lo stesso Idempotency-Key restituisce 409 o 422: prova con una nuova key.

Da tenere presente prima di andare in produzione

• Callback: passa al livello superiore del corpo della richiesta "callback": {"url": "https://..."}, notifica automatica allo stato finale, niente polling.
• Salva subito: output[0].url è un indirizzo temporaneo, scaricalo appena lo ricevi.
• Indica l'ordine delle immagini nell'istruzione: per la composizione multi-immagine usa image 1 / image 2; l'ordine è quello di image_urls.
• Semantica bianco/nero della maschera: in FIBO bianco = modifica, nero = mantieni; se migri script da altri modelli di editing, inverti prima la maschera.

Domande frequenti

Come si chiama il campo dell'istruzione di editing?

Si chiama instruction, non prompt; se sbagli il nome del campo ti segnala campo mancante.

Quante immagini di input si possono inviare al massimo?

Al massimo 4; la quinta restituisce direttamente 400.

A cosa serve seed?

Il predefinito è 5555 ed è fisso: lo stesso input viene riprodotto; per risultati diversi cambia esplicitamente seed.

Prezzo e modalità di chiamata dei due endpoint sono uguali?

Sì. Cambiano solo i campi model e input; sia generazione che editing costano $0.0575 per immagine.

Prossimo passo: prendi il prompt del profumo e genera un'immagine dalla pagina del modello, poi trasformala nella versione che vuoi con una instruction; per i template di scenario vedi la raccolta di prompt.