Come usare flux-2-klein-4b/image-to-image tramite l'API hiapi

FLUX.2 [klein] 4B è un modello compatto e veloce per la modifica delle immagini creato da Black Forest Labs: gli fornisci un'immagine di riferimento e un'istruzione in linguaggio naturale, e restituisce un'immagine modificata fino a 4 MP. Su hiapi funziona come tutti gli altri modelli tramite la stessa Unified Async API: crea un task con POST /v1/tasks, poi esegui il polling o ricevi un callback per ottenere il risultato. Questa guida illustra la struttura esatta della richiesta, esempi funzionanti in curl/Python e come integrarlo in un ambiente di produzione.

Cosa ti serve

• Una chiave API hiapi. Puoi ottenerla dalla dashboard: la chiave ha la forma sk-... e va inserita nell'intestazione Authorization: Bearer.
• Un URL dell'immagine di riferimento accessibile pubblicamente (jpeg, png o webp — svg non supportato). Le immagini oltre 4 MP vengono ridimensionate automaticamente a 4 MP.
• Il prezzo attuale di flux-2-klein-4b/image-to-image è a scaglioni in base alla risoluzione (da 0.25 MP a 4 MP) — consulta hiapi pricing per il prezzo in tempo reale, non codificarlo qui in modo fisso.

Esempio minimo funzionante

L'ID del modello è flux-2-klein-4b/image-to-image — usalo esattamente così (con la barra), come valore di model (non nel percorso dell'URL). Tutti i modelli hiapi condividono lo stesso endpoint; solo i campi dell'oggetto input variano da modello a modello.

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-klein-4b/image-to-image",
    "input": {
      "prompt": "Mantieni il soggetto e l'angolazione della fotocamera. Sostituisci lo sfondo con un gradiente da studio blu intenso e aggiungi una morbida luce di contorno.",
      "image_urls": ["https://your-cdn.example.com/product-shot.jpg"],
      "resolution": "2 MP",
      "aspect_ratio": "16:9"
    }
  }'

La richiesta restituisce immediatamente un taskId — la generazione è asincrona:

{"code": 0, "message": "success", "data": {"taskId": "task_..."}}

Esegui il polling per ottenere il risultato:

curl "https://api.hiapi.ai/v1/tasks/task_..." \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

Quando status diventa "success", l'immagine modificata si trova in data.output[0].url. L'URL è temporaneo (con expireAt), quindi scarica o ricarica subito il file — non memorizzare direttamente il link temporaneo.

La stessa procedura in Python:

import time
import requests

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

def create_task(prompt: str, image_url: str) -> str:
    payload = {
        "model": "flux-2-klein-4b/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": [image_url],
            "resolution": "2 MP",
            "aspect_ratio": "16:9",
        },
    }
    resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]

def wait_task(task_id: str, timeout_s: int = 300, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30)
        task = r.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

task_id = create_task(
    "Mantieni il soggetto e l'angolazione della fotocamera. Sostituisci lo sfondo con un gradiente "
    "da studio blu intenso e aggiungi una morbida luce di contorno.",
    "https://your-cdn.example.com/product-shot.jpg",
)
result = wait_task(task_id)
print(result["output"][0]["url"])

Parametri della richiesta

flux-2-klein-4b/image-to-image accetta uno schema di input rigoroso — i campi aggiuntivi non elencati qui vengono rifiutati con un 400:

Campo	Obbligatorio	Descrizione
prompt	Sì	Descrizione in linguaggio naturale della modifica da applicare.
image_urls	Sì	Array contenente esattamente un URL di immagine di riferimento. Se ne passi più di uno restituisce maxItems: got N, want 1.
resolution	No	Uno dei valori: 0.25 MP, 0.5 MP, 1 MP (predefinito), 2 MP, 4 MP. Usa 0.25/0.5 MP per bozze a basso costo e 2/4 MP per l'output finale.
aspect_ratio	No	Uno dei valori: match_input_image (predefinito), 1:1, 16:9, 9:16, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 21:9, 9:21.
seed	No	Numero intero per ottenere output riproducibili tra richieste altrimenti identiche.
output_format	No	jpg (predefinito), png o webp.
output_quality	No	Numero intero, qualità di compressione per jpg/webp (predefinito 95).

Questo modello non ha i campi size o n — sono convenzioni di altri fornitori che questo schema non riconosce. Ogni modello hiapi ha il proprio insieme di campi, quindi prima di riadattare una richiesta scritta per un altro modello, consulta la pagina di riferimento del modello.

Considerazioni per la produzione

Preferisci i callback al polling. Aggiungi un oggetto callback di primo livello e hiapi notificherà il tuo servizio, invece di farti eseguire il polling in un ciclo:

{
  "model": "flux-2-klein-4b/image-to-image",
  "input": { "prompt": "...", "image_urls": ["..."] },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}

when accetta solo "final" — invia una sola notifica quando il task raggiunge lo stato terminale (success o fail), non un flusso di avanzamento. Considera il callback come un segnale di risveglio: una volta ricevuto, dovresti comunque eseguire GET /v1/tasks/<taskId> per leggere lo stato autorevole, e rendere il gestore idempotente rispetto a taskId, in caso di consegne duplicate.

Idempotenza. Persisti il taskId subito dopo che create_task lo restituisce, prima di iniziare il polling o attendere il callback. Se il processo si interrompe durante l'attesa, al riavvio dovrebbe riprendere con GET /v1/tasks/<taskId>, invece di ricreare il task — la creazione del task è un evento fatturato, mentre GET può essere ripetuto gratuitamente.

Gestione degli errori. Una chiave non valida o non autorizzata restituisce HTTP 401 con un corpo di risposta strutturato:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key cannot use the selected model. Please check permissions or use another key. If the issue persists, contact support with request ID: ...",
    "request_id": "...",
    "type": "hiapi_error"
  }
}

Registra il request_id — il team di supporto può usarlo per individuare la chiamata esatta. Un input malformato (manca prompt/image_urls, valore aspect_ratio non supportato, o campi aggiuntivi non riconosciuti) restituisce 400 con error_code: "INVALID_REQUEST" e il messaggio indica il campo problematico; correggi il corpo della richiesta invece di riprovare così com'è.

Letture correlate

• Riferimento del modello FLUX.2 [klein] 4B image-to-image — documentazione completa dei parametri e corpi di richiesta di esempio.
• Riferimento del modello FLUX.2 [klein] 4B text-to-image — la variante corrispondente text-to-image, senza immagine di riferimento.
• hiapi pricing — costo attuale per immagine a scaglioni di risoluzione.
• Panoramica della Unified Async API — il contratto POST /v1/tasks / GET /v1/tasks/:id condiviso da ogni modello della piattaforma.

Domande frequenti

Quali formati di immagine accetta image_urls? jpeg, png o webp. svg non è supportato. Le immagini più grandi di 4 MP vengono ridimensionate automaticamente a 4 MP prima della modifica.

Posso passare più immagini di riferimento? No — su questo modello image_urls ha un limite di esattamente un elemento. Passarne di più restituisce 400 (maxItems: got N, want 1).

Perché la mia richiesta viene rifiutata con "additional properties ... not allowed"? Lo schema è rigoroso: qualsiasi campo non presente nella tabella dei parametri sopra (ad esempio size, n o strength di convenzioni di altri fornitori) provoca un 400. Consulta il riferimento del modello per l'esatto insieme di campi accettati.

Come mantengo le proporzioni dell'immagine originale? Imposta aspect_ratio su match_input_image — è anche il valore predefinito se ometti completamente il campo.

Qual è la differenza tra flux-2-klein-4b/image-to-image e la variante 9B? Condividono lo stesso schema di richiesta (prompt, image_urls, resolution, aspect_ratio, seed, output_format, output_quality). La variante 9B sacrifica un po' di velocità e costo in cambio di maggiore realismo, rendering del testo e dettaglio — usa la 4B quando iteri rapidamente e a basso costo, la 9B quando le modifiche devono reggere sui dettagli fini.

Mi serve un URL di callback, o basta il polling? Il polling con GET /v1/tasks/:id va bene per lo sviluppo locale, per task a basso volume, o come fallback quando la consegna del callback viene persa. Per il traffico di produzione, i callback evitano il costo di un ciclo di polling per ogni richiesta.