---

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

• Esempi minimi in curl e Python per chiamare flux-2-klein-9b/text-to-image tramite l'endpoint unificato /v1/tasks di hiapi.
• 'Tabella completa dei parametri: prompt, aspect_ratio, num_inference_steps, output_format e seed — uno schema rigoroso rifiuta i campi sconosciuti.'
• 'Note per la produzione: callback.url rispetto al polling, l'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 ottenere il risultato.
• num_inference_steps accetta solo valori da 4 a 8 (interi); questo modello non ha i campi size o n.
• Ripetere la richiesta con lo stesso header Idempotency-Key restituisce lo stesso taskId — è sicuro riutilizzarlo 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-9b meta_description: Chiama flux-2-klein-9b/text-to-image con curl e Python; crea task, esegui il polling delle immagini e gestisci callback, idempotenza ed errori in produzione. keywords:
• api text-to-image flux-2-klein-9b
• esempio api flux-2-klein-9b
• api generazione immagini hiapi
• flux klein 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-9b/text-to-image tramite l'API hiapi

Cosa costruirai

Uno script che invia un prompt a flux-2-klein-9b/text-to-image, attende il completamento della generazione dell'immagine e la scarica — oltre ai dettagli di produzione necessari prima di eseguirlo in modo non presidiato (callback, idempotenza, strutture degli errori).

Prerequisiti: ottieni una chiave API dalla console hiapi. Ogni richiesta riportata di seguito si autentica con Authorization: Bearer sk-<your-api-key>.

Esempio minimo funzionante

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

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

Risultato restituito:

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

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

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.png", "expireAt": 1785941465}
    ]
  },
  "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 e archiviati tu stesso, invece di collegarti direttamente ad esso.

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-9b/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.png", "wb").write(image_bytes)

Parametri importanti

flux-2-klein-9b/text-to-image ha uno schema di input rigoroso — l'invio di campi che non riconosce (size, n, negative_prompt o qualsiasi altro campo accettato da altri modelli di immagini hiapi) viene rifiutato direttamente, quindi non copiare i parametri tra modelli senza prima consultare la pagina del modello.

Campo	Obbligatorio	Descrizione
prompt	Sì	Stringa che descrive l'immagine.
aspect_ratio	No	Uno tra 1:1, 4:3, 3:4, 16:9, 9:16. Se omesso, il valore predefinito è 4:3.
num_inference_steps	No	Intero, 4–8. Il valore predefinito è 4; valori più alti scambiano velocità per un po' più di dettaglio.
output_format	No	Uno tra jpeg, png, webp. Il valore predefinito è png.
seed	No	Intero. Riutilizzare il seed rende riproducibili i risultati di più chiamate.

Per il riferimento completo dei parametri consulta la pagina del modello; per i prezzi attuali a consumo per immagine consulta la pagina dei prezzi — controlla lì invece di codificare i numeri, perché le tariffe basate sull'utilizzo cambiano.

Note per la produzione

Usa i callback invece del polling. Per qualsiasi scenario oltre a uno script rapido, salta il ciclo di polling e aggiungi callback.url (più "when": "final") nel corpo della richiesta di creazione del task — hiapi invierà i risultati via POST al tuo endpoint al termine del task, con una struttura del payload identica a quella restituita da GET /v1/tasks/{taskId}. Per dettagli sui campi dei callback e sulla verifica della firma, consulta Creazione di un task.

{
  "model": "flux-2-klein-9b/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 sulla chiamata POST /v1/tasks (massimo 255 byte). Ripetere la stessa richiesta con la stessa chiave sullo stesso account non crea un secondo task — ricevi il taskId originale. È proprio questo che rende sicuro ritentare una richiesta scaduta dalla tua parte senza doppio addebito.

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

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

Esegui il branching 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 — ambiti delle chiavi API e formato degli header
• flux-2-klein-9b/image-to-image — stessa famiglia, modifica un'immagine di input invece di generare da zero
• flux-2-klein-4b/text-to-image — modello più piccolo e veloce della stessa famiglia klein

Domande frequenti

flux-2-klein-9b/text-to-image supporta image-to-image? Non direttamente — è un modello separato, flux-2-klein-9b/image-to-image, con il proprio schema di input.

Qual è la differenza tra flux-2-klein-9b e flux-2-klein-4b? Entrambi sono endpoint text-to-image della stessa famiglia FLUX.2 [klein]; 9b è il più grande dei due, pensato per un maggiore realismo, resa del testo e dettaglio. Prima di passare all'altro, consulta la pagina del modello 4b per i suoi prezzi e parametri attuali.

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

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

Perché ricevo un errore 401 permission_denied? La tua chiave è mancante, non valida o non ha accesso a questo modello. Verifica di inviare Authorization: Bearer sk-... con la chiave dalla console, non un segnaposto.

Serve gestire un proprio server per usare questa API? Solo se hai bisogno dei callback. Il polling di GET /v1/tasks/{taskId} da uno script, un cron job o una funzione serverless va benissimo per volumi ridotti; quando la generazione cresce, passa a callback.url.