Black Forest Labs

FLUX 3 Image

flux-3-image

Modello orientato alle immagini della famiglia multimodale di Black Forest Labs, condivide con video e audio l'architettura di addestramento congiunto e il framework Self-Flow, ideale per l'aggiornamento delle pipeline di generazione di immagini basate sul sistema FLUX

flux-3-image

Prova flux-3-image

Input

Creazioni

Vedi tutte le creazioni

Output

image

Compila i parametri e genera: i risultati appariranno qui.

Prezzi

flux-3-image per image

Specifiche	Prezzo unitario
768S	$0.041
1K	$0.048
1.5K	$0.070
2K	$0.100
4K	$0.607

Presentazione e posizionamento

flux-3-image è il modello orientato alle immagini della famiglia multimodale FLUX 3 di Black Forest Labs, accessibile tramite l'interfaccia unificata di HiAPI.ai. Accetta sia prompt puramente testuali per generare immagini direttamente, sia fino a 10 immagini di riferimento che partecipano alla generazione e alle modifiche locali; il formato di output, i livelli di risoluzione e la tolleranza alla sicurezza dei contenuti sono tutti regolabili. È adatto agli sviluppatori che stanno costruendo pipeline di generazione di contenuti visivi e ai team che desiderano integrare un modello di nuova generazione nei flussi di lavoro FLUX esistenti.

Punti salienti

Controllo combinato di immagini di riferimento e prompt: è possibile passare fino a 10 immagini di riferimento e indicare nel prompt, una per una, il ruolo che ciascuna assume come soggetto, stile o composizione.
Ricerca web opzionale per integrare informazioni visive: il grounding è attivo per impostazione predefinita; prima della generazione vengono consultati pagine web e immagini per arricchire il prompt con dettagli su entità e scene.
Risoluzione e formato ampiamente selezionabili: l'output copre cinque livelli di pixel da 768 a 4K e 16 rapporti d'aspetto; la modalità auto determina automaticamente il formato in base al prompt e alle immagini di riferimento.

Descrizione delle capacità

Generazione da testo e generazione guidata da immagini di riferimento: una singola richiesta genera un'immagine dal prompt; quando si forniscono immagini di riferimento, basta indicare nel prompt i contenuti da modificare e da mantenere per ottenere l'adeguamento desiderato, senza flussi a più passaggi.

Combinazione di più riferimenti: è possibile usare fino a 10 immagini di riferimento per richiesta, ciascuna con il ruolo di soggetto, stile o composizione, ideale per far convergere più materiali visivi in un'unica scena.

Controllo di formato e risoluzione: aspect_ratio offre 16 rapporti, dal formato orizzontale 21:9 a quello verticale 9:21, con selezione automatica; resolution copre da 768 a 4K, facilitando la generazione in batch in base al canale di distribuzione e ai requisiti di nitidezza.

Regolazione della tolleranza alla sicurezza dei contenuti: safety_tolerance è regolabile da 0 a 4, con valore predefinito 2; i team possono stringere o allentare l'intensità del filtro in base ai propri requisiti di conformità.

Scenari d'uso

Generazione stilizzata per team di design creativo: inserendo specifiche di design e immagini di riferimento stilistiche si producono bozze visive conformi alla composizione e al formato indicati, per materiali pubblicitari e proposte concettuali.
Aggiornamento del modello nelle pipeline FLUX esistenti: sostituendo le chiamate di generazione immagini esistenti con prompt testuali, l'output mantiene la forma dell'interfaccia originale, facilitando l'aggiornamento del modello senza modificare i flussi di livello superiore.
Produzione di immagini di scena con dettagli fattuali: con il grounding attivo, basta un prompt breve che descriva il soggetto per ottenere immagini arricchite con informazioni recuperate, utili per illustrazioni di contenuti e rappresentazioni di scene.
Composizione di più materiali e revisione di immagini: caricando più immagini di riferimento e annotando il ruolo di ciascuna si ottengono composizioni o modifiche dallo stile coerente, per immagini e-commerce e riutilizzo di materiali.

Limiti e consigli di selezione

Le informazioni pubbliche riguardano principalmente la famiglia FLUX 3 nel suo complesso e la direzione video, mentre le specifiche dettagliate di questa versione per immagini sono limitate; le descrizioni sull'addestramento congiunto e sulle capacità video a livello di famiglia non equivalgono direttamente a tutte le capacità di questo modello. Il grounding esegue prima la ricerca e poi la generazione, il che può aumentare la durata di una singola richiesta. Per quanto riguarda velocità di generazione, stabilità e comportamento con prompt estremamente difficili, si consiglia di verificare con esempi propri prima di adottarlo in produzione. Se l'esigenza è la generazione di video o audio, occorre scegliere il modello corrispondente della stessa famiglia.

Domande frequenti

Vedi tutte le domande →

Un'unica interfaccia può generare e modificare?

Sì. Senza immagini di riferimento, genera dal testo; fornendo da 1 a 10 immagini di riferimento, modifica in base ai materiali esistenti. Basta preparare il testo o le immagini in base all'obiettivo creativo.
Come scegliere tra i cinque livelli di risoluzione?

Inizia con 768 o 1K per definire la direzione; considera 1.5K o 2K quando servono più dettagli, e 4K quando servono immagini più grandi e spazio per il ritaglio. I livelli non corrispondono a dimensioni fisse in pixel: verifica larghezza e altezza dell'immagine restituita.
Come vengono assegnati i ruoli alle immagini di riferimento?

Indica in ordine quale immagine fornisce il soggetto, quale fornisce l'ambiente e quale fornisce solo la combinazione di colori o lo stile, specificando anche gli elementi da non includere.
Quante immagini vengono generate ogni volta?

Ogni attività restituisce un'immagine. Per ottenere un'altra direzione, modifica la descrizione e invia un'attività separata.

Crea un'attività di generazione

POST https://api.hiapi.ai/v1/tasks

Header

AuthorizationstringObbligatorio

Chiave API dell'account. Obbligatoria in ogni richiesta. Esempio: Bearer YOUR_HIAPI_API_KEY. Ottieni una chiave API

Content-TypestringOpzionale

Il corpo della richiesta viene sempre interpretato come JSON; se inviato, è accettato solo application/json (charset facoltativo) — qualsiasi altro valore restituisce 415. Esempio: application/json.

Idempotency-KeystringOpzionale

Chiave di idempotenza, fino a 255 byte. I retry con la stessa chiave dello stesso account creano l'attività una sola volta; i replay restituiscono il taskId originale.

Chiave di idempotenza

In caso di timeout di rete o retry automatici del client, la stessa chiave crea l'attività una sola volta, senza doppi addebiti (ambito = l'account della chiave API). Usa un identificatore univoco di business (es. "order-42"); i replay restituiscono il taskId originale e le chiavi scadono 24 ore dopo la prima richiesta. La matrice completa degli scenari è nell'introduzione dell'API asincrona unificata.

Corpo

modelstringObbligatorio

Valore fisso attuale: flux-3-image

routestringOpzionale

Valore fisso attuale: default

inputobjectObbligatorio

Oggetto di parametri di business per flux-3-image e la route default — vedi la tabella dei parametri sotto.

promptstringObbligatoriominLength 1maxLength 5000

Descrivi il contenuto visivo che desideri generare; quando fornisci un'immagine di riferimento, puoi anche indicare qui le parti dell'immagine da modificare e quelle da mantenere.

groundingbooleanOpzionalePredefinito: true

Valore booleano che controlla se effettuare una ricerca online di pagine web e immagini prima della generazione, per integrare le informazioni visive nel prompt; il valore predefinito è true.

image_urlsarrayOpzionaleminItems 1maxItems 10

Array di URL di immagini di riferimento, utilizzato per fornire riferimenti visivi alla generazione; il soggetto, lo stile o il ruolo compositivo di ciascuna immagine devono essere specificati nel prompt.

Array [ string ]

resolutionstringOpzionalePredefinito: "1K"

Livello di risoluzione dell'output; le dimensioni esatte in larghezza e altezza variano in base al formato; il valore predefinito è 1K.

Opzioni:7681K1.5K2K4K

aspect_ratiostringOpzionalePredefinito: "auto"

Proporzioni del formato di output, selezionabili tra orizzontale, verticale o quadrato; auto indica la determinazione automatica del formato in base al prompt e alle immagini di riferimento; il valore predefinito è auto.

Opzioni:21:92:116:93:27:54:35:41:1

Mostra tutto (8)

4:53:45:72:39:161:29:21auto

safety_toleranceintegerOpzionalePredefinito: 2min 0max 4

Numero intero che indica la tolleranza di sicurezza dei contenuti, dove 0 è il valore più rigoroso; il valore predefinito è 2.

callbackobjectOpzionale

Configurazione di notifica dello stato terminale. Se omessa, nessun callback: interroga l'attività per conto tuo.

Callback (Webhook)

Fornisci callback.url in creazione e HiAPI invierà un POST al tuo servizio allo stato terminale, senza polling. Il corpo del callback replica la struttura del dettaglio attività; verifica firma, retry e idempotenza sono descritti nell'introduzione dell'API asincrona unificata.

urlstringObbligatorio

Obbligatoria se è presente callback. Allo stato terminale viene inviato un POST a questo URL; deve essere un URL http(s) valido.

whenstringOpzionalePredefinito: "final"

Al momento è supportato solo final: notifica sia su success sia su fail.

Opzioni:final

storagestringOpzionalePredefinito: "temp"

Livello di archiviazione degli artefatti: temp (predefinito, ~7 giorni) o persistent (a lungo termine, fatturato per dimensione). Saldo insufficiente o superamento del limite ⇒ declassamento silenzioso a temp; il livello effettivo è visibile nella risposta di dettaglio.

Opzioni:temppersistent

Esempi di richiesta

# Invia un'attività asincrona; restituisce subito un taskId (senza attendere la generazione)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "flux-3-image",
  "input": {
    "prompt": "…",
    "grounding": true,
    "resolution": "1K",
    "aspect_ratio": "auto",
    "safety_tolerance": 2
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "flux-3-image",
    input: {
      "prompt": "…",
      "grounding": true,
      "resolution": "1K",
      "aspect_ratio": "auto",
      "safety_tolerance": 2
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "flux-3-image",
        "input": {
          "prompt": "…",
          "grounding": True,
          "resolution": "1K",
          "aspect_ratio": "auto",
          "safety_tolerance": 2
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
  }
}

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

Ottieni i dettagli dell'attività

GET https://api.hiapi.ai/v1/tasks/:id

Campi della risposta

taskIdstringObbligatorio

ID attività, sempre con prefisso tk-hiapi-.

modelstringObbligatorio

Nome completo risolto del modello. Le attività inviate con il parametro route restituiscono base@route (es. gpt-image-2/text-to-image@ext); altrimenti coincide con il nome inviato.

routestringOpzionale

Presente solo se è stato usato il parametro route esplicito; restituisce il valore inviato.

statusstringObbligatorio

Stato dell'attività.

Valori di stato

queued In coda, non avviata. handling In elaborazione. archiving Elaborazione conclusa, preparazione artefatti. success Terminale: completato, artefatti disponibili (restituisce output). fail Terminale: errore (restituisce error). Dopo l'invio, segui status: success e fail sono terminali, il resto no. Esegui polling ogni 1–3 s fino allo stato terminale. In caso di successo scarica gli artefatti da output[].url e trasferiscili prima di expireAt; per conservazione lunga usa storage: "persistent" in creazione.

creatednumberObbligatorio

Istante di creazione dell'attività (secondi Unix).

completednumberObbligatorio

Secondi Unix dello stato terminale; 0 finché non terminale.

outputarrayOpzionale

Presente solo con status == success. Elenco artefatti — sempre un array; un'attività può restituire più type contemporaneamente (es. video + first_frame).

Array [ object ]

Elementi dell'array

urlstringObbligatorio

URL dell'artefatto, scaricabile direttamente.

typestringObbligatorio

Valori attualmente possibili: video, image, audio, first_frame, last_frame, thumbnail; potrebbero essere ampliati in futuro.

expireAtnumberObbligatorio

Secondi Unix di disponibilità dell'artefatto; scarica o trasferisci prima della scadenza.

errorobjectOpzionale

Presente solo con status == fail.

codestringObbligatorio

Codice errore di business.

messagestringObbligatorio

Descrizione dell'errore.

Esempi di risposta

Successo

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

In elaborazione (non terminale)

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

Non riuscito

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}