---

slug: flux-2-klein-4b-text-to-image-api-guide locale: en title: Come usare flux-2-klein-4b/text-to-image tramite l'API hiapi category: tutorial summary:

• Esempi curl e Python minimi per chiamare flux-2-klein-4b/text-to-image tramite l'endpoint unificato /v1/tasks di hiapi.
• 'Tabella completa dei parametri: prompt, valori dell'enum aspect_ratio e seed — uno schema rigoroso rifiuta i campi sconosciuti.'
• 'Note per la produzione: compromesso tra callback.url e polling, header Idempotency-Key e le due strutture di risposta di errore.' takeaways:
• Crea un task con POST /v1/tasks, poi esegui il polling di GET /v1/tasks/{taskId} oppure usa callback.url per ricevere il risultato.
• aspect_ratio supporta 11 rapporti denominati; questo modello non ha i campi size o n.
• Ripetere la richiesta con lo stesso header Idempotency-Key restituisce lo stesso taskId — riutilizzabile in sicurezza in caso di timeout.
• Gli errori 400 usano error_code, gli errori di autenticazione 401 usano error.code annidato — controlla prima il codice di stato HTTP. meta_title: Guida all'API text-to-image di flux-2-klein-4b meta_description: 'Chiama flux-2-klein-4b/text-to-image con curl e Python: crea il task, esegui il polling per ottenere l'immagine e gestisci callback, idempotenza ed errori in produzione.' keywords:
• api text-to-image flux-2-klein-4b
• esempio api flux-2-klein-4b
• api di generazione immagini hiapi
• flux api curl python tags:
• api-guide
• image-generation
• flux author_name: hiapi is_published: false cover_image: https://static.hiapi.ai/blog/_default/recipe-cover.jpg

---

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

Cosa costruirai

Uno script che invia un prompt a flux-2-klein-4b/text-to-image, attende la generazione dell'immagine e poi la scarica — oltre ai dettagli di produzione da conoscere prima di un'esecuzione non presidiata (callback, idempotenza, struttura degli errori).

Prerequisiti: ottieni una API key dalla console hiapi. Ogni richiesta qui sotto si autentica con Authorization: Bearer sk-<your-api-key>.

Esempio minimo funzionante

I modelli generativi di hiapi girano dietro un unico endpoint asincrono: POST /v1/tasks crea il task e restituisce subito un taskId; poi esegui il polling di GET /v1/tasks/{taskId} finché non raggiunge uno stato finale.

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/text-to-image",
    "input": {
      "prompt": "a red fox walking through fresh snow, golden hour light",
      "aspect_ratio": "16:9"
    }
  }'

Risposta:

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

Esegui il polling dello stesso task finché data.status non passa da handling a success (passando brevemente per archiving):

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01K... \
  -H "Authorization: Bearer sk-<your-api-key>"

{
  "code": 200,
  "data": {
    "status": "success",
    "output": [
      {"type": "image", "url": "https://temp.hiapi.ai/.../01K...-0.jpg", "expireAt": 1785939579}
    ]
  },
  "message": "success"
}

data.output[0].url è l'immagine generata. È un link temporaneo — nei test scade circa 7 giorni dopo la generazione — quindi scarica i byte dell'immagine e conservali tu, invece di collegarti direttamente a quell'indirizzo.

Lo stesso flusso in Python (con polling)

import time
import requests

API_KEY = "sk-<your-api-key>"
BASE = "https://api.hiapi.ai/v1"
headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

resp = requests.post(f"{BASE}/tasks", headers=headers, json={
    "model": "flux-2-klein-4b/text-to-image",
    "input": {
        "prompt": "a red fox walking through fresh snow, golden hour light",
        "aspect_ratio": "16:9",
    },
})
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]

while True:
    task = requests.get(f"{BASE}/tasks/{task_id}", headers=headers).json()["data"]
    if task["status"] == "success":
        image_url = task["output"][0]["url"]
        break
    if task["status"] == "failed":
        raise RuntimeError(f"generation failed: {task}")
    time.sleep(3)

image_bytes = requests.get(image_url).content
open("fox.jpg", "wb").write(image_bytes)

Parametri importanti

flux-2-klein-4b/text-to-image adotta uno schema di input rigoroso — i campi che non riconosce (size, n, negative_prompt o qualsiasi altro campo accettato da altri modelli immagine di hiapi) vengono rifiutati direttamente, quindi non copiare i parametri da un modello all'altro senza prima consultare la pagina del modello.

Campo	Obbligatorio	Descrizione
prompt	Sì	Stringa che descrive l'immagine.
aspect_ratio	No	Uno dei valori: 1:1, 16:9, 9:16, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 21:9, 9:21. Se omesso, il default è 1:1.
seed	No	Intero. Riutilizzare lo stesso seed rende riproducibili i risultati di più chiamate.

Il riferimento completo dei parametri è nella pagina del modello; il prezzo attuale per immagine è nella pagina dei prezzi — fai riferimento a quella, invece di codificare numeri fissi, perché i prezzi a consumo cambiano.

Note per la produzione

Usa i callback invece del polling. Oltre che negli script rapidi, salta il ciclo di polling e aggiungi callback.url (e "when": "final") nel corpo della richiesta di creazione del task — al termine del task hiapi invierà il risultato via POST al tuo endpoint, con un payload identico a quello restituito da GET /v1/tasks/{taskId}. Per i dettagli sui campi del callback e la verifica della firma, consulta Creare un task.

{
  "model": "flux-2-klein-4b/text-to-image",
  "callback": {"url": "https://yourapp.com/hooks/hiapi", "when": "final"},
  "input": {"prompt": "a red fox walking through fresh snow, golden hour light"}
}

Idempotenza. Imposta l'header Idempotency-Key nella chiamata POST /v1/tasks (massimo 255 byte). Ripetere la stessa richiesta con la stessa key sullo stesso account non crea un secondo task — ricevi indietro il taskId originale. È proprio questo che rende sicuro ripetere una richiesta andata in timeout dalla tua parte, senza doppio addebito.

Gestione degli errori. In pratica si presentano due diverse strutture di errore, quindi controllale entrambe:

• Un input errato (prompt mancante, aspect_ratio fuori intervallo, campi non supportati) restituisce HTTP 400 con corpo di risposta {"error_code": "INVALID_REQUEST", "message": "..."}.
• Una API key non valida o non autorizzata restituisce HTTP 401, con una struttura di risposta diversa: {"error": {"code": "permission_denied", "message": "...", "request_id": "..."}}.

Ramifica prima in base al codice di stato HTTP, poi leggi il campo di errore effettivamente presente — non dare per scontato che tutti gli errori usino la stessa struttura di risposta.

Risorse correlate

• Ottenere i dettagli di un task — riferimento completo sul polling
• Autenticazione — scope delle API key e formato degli header
• flux-2-klein-4b/image-to-image — stessa serie, modifica un'immagine di input invece di generare da zero
• flux-2-klein-9b/text-to-image — il modello più grande della stessa serie klein

Domande frequenti

flux-2-klein-4b/text-to-image supporta l'image-to-image? Non direttamente — quello è un altro modello, flux-2-klein-4b/image-to-image, con un proprio schema di input.

Qual è la differenza tra flux-2-klein-4b e flux-2-klein-9b? Entrambi sono endpoint text-to-image della stessa serie FLUX.2 [klein]; 9b è il più grande dei due. Prima di passare all'altro, consulta la pagina del modello 9b per conoscerne prezzo e parametri attuali.

Posso richiedere più immagini in una sola chiamata? No — lo schema non accetta n né campi di quantità. Serve una richiesta per ogni immagine.

Quanto dura l'URL dell'immagine restituita? output[0].url è un link temporaneo con il proprio timestamp expireAt; consideralo valido per breve tempo (nei test circa una settimana) e scarica i byte dell'immagine subito dopo il successo del task, invece di memorizzare l'URL.

Perché ricevo un errore 401 permission_denied? La tua key è mancante, non valida o non ha accesso a quel modello. Verifica di inviare Authorization: Bearer sk-... e di usare una key presa dalla console, non un segnaposto.

Serve gestire un proprio server per usare questa API? Solo se hai bisogno dei callback. Eseguire il polling di GET /v1/tasks/{taskId} da uno script, da un cron job o da una funzione serverless è del tutto fattibile a basso traffico; quando il volume di generazioni cresce, passa a callback.url.