Come usare flux-2/image-to-image tramite l'API hiapi: curl, Python ed esempi di richiesta disponibili

In breve

• Di cosa si tratta: la soluzione disponibile per chiamare l'API flux-2/image-to-image su hiapi — creare un'attività, fare polling sullo stato, scaricare il risultato.
• Endpoint: usa POST https://api.hiapi.ai/v1/tasks specificando "model": "flux-2/image-to-image", poi GET /v1/tasks/<taskId> finché l'attività non raggiunge lo stato terminale.
• Campi di input obbligatori (tutti e quattro): prompt, image_urls (da 1 a 8 URL pubblici — è questa la funzionalità multi-immagine di riferimento), aspect_ratio e resolution (1K o 2K).
• Lo schema è rigoroso. Campi come strength o fidelity non esistono e vengono rifiutati con 400. La fedeltà è controllata dalle immagini di riferimento, dal prompt e da resolution — non da una manopola dedicata.

Cosa costruirai e cosa ti serve preparare

Obiettivo: inviare a flux-2 una o più immagini di riferimento più un prompt testuale e ricevere indietro un'immagine modificata/ridisegnata scaricabile — con curl o Python, senza SDK.

Prerequisiti:

1. Una chiave API hiapi — creala nella console hiapi. La chiave ha la forma sk-... e va inserita nell'header Authorization: Bearer.
2. Almeno un URL di immagine accessibile pubblicamente da usare come immagine di riferimento. L'API recupera image_urls lato server, quindi i link localhost o gli URL di bucket privati non funzionano — usa un bucket pubblico, una CDN o un URL pre-firmato.
3. curl, oppure Python 3.8+ con requests (pip install requests).

Schema della richiesta

flux-2/image-to-image gira sull'interfaccia unificata delle attività di hiapi. L'oggetto input accetta esattamente i seguenti campi:

Campo	Tipo	Obbligatorio	Descrizione
prompt	string	Sì	Cosa modificare o generare. Almeno 3 caratteri.
image_urls	string[]	Sì	Da 1 a 8 URL di immagini pubbliche. Più di una = multi-immagine di riferimento: flux-2 fonde indizi di identità, prodotto o stile tra tutte le immagini di riferimento.
aspect_ratio	string	Sì	Uno tra 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3 o auto (segue l'immagine di riferimento).
resolution	string	Sì	1K o 2K.

Qualsiasi altro campo viene rifiutato. Ad esempio, inviare un campo strength o fidelity restituisce:

{
  "code": 400,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'fidelity', 'strength' not allowed"
}

Vale la pena tenerlo a mente: la modalità image-to-image di flux-2 non ha una manopola per l'intensità di denoising. Quanto l'output resta fedele all'immagine di riferimento (modifica "ad alta fedeltà" vs. ridisegno libero) dipende da come scrivi il prompt — ad esempio "Mantieni il prodotto, la sua etichetta e le proporzioni esattamente come nell'immagine di riferimento; sostituisci solo lo sfondo" — più l'uso di resolution: "2K" per lavori che richiedono dettaglio.

Esempio minimo funzionante: curl

Passo 1 — crea l'attività:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/image-to-image",
    "input": {
      "prompt": "Place this product on a white marble countertop with soft morning light, keep the product itself unchanged",
      "image_urls": ["https://your-cdn.example.com/product.jpg"],
      "aspect_ratio": "1:1",
      "resolution": "2K"
    }
  }'

In caso di creazione riuscita, l'ID dell'attività viene restituito in data.taskId.

Passo 2 — fai polling finché non è completata:

curl -s https://api.hiapi.ai/v1/tasks/TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Finché data.status non è terminale, continua a fare polling ogni pochi secondi. Quando "status": "success", l'URL dell'immagine si trova in data.output[0].url.

Passo 3 — scarica subito il risultato:

curl -s -o result.jpg "OUTPUT_URL"

Gli URL di output hanno un timestamp expireAt — sono temporanei. Scarica i byte immediatamente dopo il successo dell'attività (o copiali nel tuo storage); non fare hotlinking diretto degli output delle attività in produzione.

Esempio minimo funzionante: Python

Uno script completo — creazione, polling, download — usando solo requests:

import time
import requests

API_KEY = "sk-YOUR_KEY"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def create_task() -> str:
    resp = requests.post(BASE, headers=HEADERS, json={
        "model": "flux-2/image-to-image",
        "input": {
            "prompt": ("Combine the person from the first image with the jacket "
                       "from the second image, studio lighting, neutral backdrop"),
            "image_urls": [
                "https://your-cdn.example.com/person.jpg",
                "https://your-cdn.example.com/jacket.jpg",
            ],
            "aspect_ratio": "3:4",
            "resolution": "2K",
        },
    }, timeout=30)
    body = resp.json()
    task_id = (body.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {body}")
    return task_id

def wait_task(task_id: str, timeout_s: int = 600, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        task = requests.get(f"{BASE}/{task_id}", headers=HEADERS,
                            timeout=30).json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")

task_id = create_task()
print("task:", task_id)
task = wait_task(task_id)
url = task["output"][0]["url"]          # URL temporaneo — salvalo subito
img = requests.get(url, timeout=120).content
with open("result.jpg", "wb") as f:
    f.write(img)
print("saved result.jpg,", len(img), "bytes")

Nota che qui image_urls contiene due immagini — è così che si usa concretamente la multi-immagine di riferimento. Sono accettate fino a 8 immagini di riferimento; il modello le combina tra loro (persona + abbigliamento, prodotto + stile dello sfondo, personaggio + riferimento di posa, ecc.).

Note pratiche per la produzione

Usa i callback invece del polling. Per qualsiasi scenario oltre a uno script, registra un callback al momento della creazione dell'attività, così che hiapi invii il risultato terminale al tuo servizio:

{
  "model": "flux-2/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://your-app.example.com/hooks/hiapi", "when": "final" }
}

Con "when": "final" riceverai un solo POST quando l'attività raggiunge lo stato terminale. Regola pratica: il polling va bene per CLI, elaborazioni batch e qualsiasi scenario di breve durata; i callback sono migliori per le applicazioni rivolte agli utenti, perché tenere un worker impegnato in un ciclo di polling per ogni immagine non scala. Se non puoi esporre un endpoint di callback pubblico, allora fai polling — ma con un intervallo che si allontana oltre i 5 secondi.

Rendi sicuri i retry. Tratta la creazione dell'attività come l'effetto collaterale che è: salva il taskId restituito nella tua registrazione dei job prima di agire in base al risultato; in caso di retry, ricontrolla lo stato dell'attività memorizzata invece di creare ciecamente una nuova attività (ogni creazione riuscita viene addebitata separatamente). Se il tuo job runner può scattare due volte, deduplica prima in base al tuo ID job.

Gestisci gli errori che incontrerai davvero:

• 401 permission_denied — chiave errata, o chiave che non ha il permesso di usare quel modello. Il corpo della risposta è:

  {"error": {"code": "permission_denied",
             "message": "This API key cannot use the selected model. ...",
             "type": "hiapi_error"}}
  

  Controlla la chiave nella console; la nostra checklist per chiavi API non valide copre le cause comuni.

• 400 INVALID_REQUEST — violazione dello schema. message elenca tutti i campi non validi in un colpo solo (campi obbligatori mancanti, valori di enum errati, campi extra sconosciuti), quindi leggilo per intero invece di correggere un campo per retry.

• Attività status: "fail" — l'attività è stata accettata ma la generazione è fallita; l'errore si trova in data.error. Gestiscilo nel percorso di polling/callback, non al momento della creazione.

• URL di output scaduto — se il download restituisce 4xx qualche minuto dopo il successo, hai aspettato troppo. Ricontrolla expireAt e scarica sempre immediatamente.

Letture correlate

• Pagina del modello flux-2/image-to-image — parametri e prezzo attuale
• Pagina del modello flux-2/text-to-image — stessa famiglia, senza immagini di riferimento
• flux-2 per immagini di prodotto e-commerce — soluzione end-to-end basata sul lato text-to-image
• FLUX 1.1 Pro su hiapi — confronto con l'opzione della generazione precedente
• Prezzi hiapi — costo per immagine per ciascuna risoluzione

Domande frequenti

Quante immagini di riferimento posso passare a flux-2 image-to-image? Da 1 a 8, come URL pubblici in image_urls. Oltre 8 la convalida fallisce (maxItems: got N, want 8).

Esiste un parametro strength o fidelity? No. Lo schema di input accetta solo prompt, image_urls, aspect_ratio e resolution; i campi sconosciuti vengono rifiutati con 400. Controlla la fedeltà tramite la formulazione del prompt (specifica chiaramente cosa deve rimanere invariato) e usa 2K quando i dettagli contano.

Quali risoluzioni e rapporti d'aspetto sono supportati? resolution è 1K o 2K. aspect_ratio è uno tra 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3 o auto — auto segue la tua immagine di riferimento, che di solito è ciò che si vuole in fase di modifica.

Posso inviare immagini in base64 invece che come URL? No — image_urls accetta URL, che devono essere accessibili pubblicamente affinché l'API possa recuperarli. Carica prima su un bucket o una CDN, poi passa l'URL generato (gli URL pre-firmati funzionano).

Quanto costa flux-2 image-to-image per immagine? Il prezzo varia con la risoluzione — consulta la pagina del modello flux-2/image-to-image e la pagina dei prezzi per la tariffa attuale per immagine.

Quanto durano gli URL delle immagini generate? Gli URL di output sono temporanei e includono un campo expireAt. Scarica i byte dell'immagine immediatamente dopo il successo dell'attività e conservali tu stesso.

Qual è la differenza tra flux-2/image-to-image e flux-2/text-to-image? Stessa famiglia di modelli, modalità diverse: text-to-image genera solo dal prompt, mentre image-to-image richiede da 1 a 8 immagini di riferimento e modifica o combina in base a esse. I loro schemi di input sono diversi, quindi i corpi delle richieste non sono intercambiabili.