Come si usa l'API Krea 3? La tua prima immagine in 5 minuti

TL;DR

• Krea 3 (krea-3/text-to-image) è un modello text-to-image: da una descrizione genera foto realistiche, illustrazioni e concept art; prima di generare comprende ed espande il prompt, e i due varianti berry (qualità prioritaria, predefinito) / jam (velocità prioritaria) si cambiano allo stesso prezzo. Apri la pagina del modello e provalo subito; i nuovi utenti ricevono 200 crediti alla registrazione.
• Il prezzo è per immagine: Krea 3 $0.036; nella stessa famiglia c'è anche il più economico Krea 2 Medium Turbo (krea-2-medium-turbo) a $0.0215 (tabella completa dei prezzi nella pagina prezzi).
• Le chiamate passano per l'endpoint HiAPI /v1/tasks: invii il task e ottieni un taskId, poi interroghi il risultato e, in caso di successo, scarichi l'immagine da output[0].url.

Cosa sa fare

• Anche un solo prompt produce un'immagine completa: prima di generare il modello ragiona ed espande il prompt; anche scrivendo solo a lighthouse aggiunge ora, luce e composizione; se scrivi in modo specifico segue la tua descrizione.
• Due varianti berry / jam con un solo ID: si cambiano con variant, parametri e prezzo identici; con lo stesso seed le due varianti hanno composizione e tonalità diverse, quindi puoi eseguirle entrambe e scegliere tra due proposte.
• 6 preset di dimensione fino a 1K: quadrato, verticale e orizzontale per un totale di 6 (da 1024×1024 a 1024×576), output PNG o JPEG.
• Anche poster con testo nel titolo: metti il testo tra virgolette, i titoli brevi di solito sono accurati.

Questa qui sotto è un risultato reale di berry:

Studio product photograph of a frosted glass perfume bottle with a brushed brass cap standing on a block of travertine, hard afternoon sunlight casting a long palm-leaf shadow across a warm beige wall, crisp reflections, high-end editorial look

(In italiano: fotografia di prodotto in studio: flacone di profumo in vetro smerigliato con tappo in ottone spazzolato, appoggiato su un blocco di travertino, la luce dura del pomeriggio proietta la lunga ombra di una foglia di palma su una parete beige caldo, riflessi nitidi, look editoriale di alta gamma. Dimensione predefinita square_hd.)

krea-3/text-to-image, berry, square_hd, 1024×1024, $0.036.

Genera con questo prompt →

Come scegliere tra i due modelli

	krea-3/text-to-image (Krea 3)	krea-2-medium-turbo (Krea 2 Medium Turbo)
Per immagine	$0.036	$0.0215
Dimensioni	6 preset (max 1024×1024), personalizzate non supportate	aspect_ratio 8 proporzioni, incluse 2.35:1 cinematografico
Parametri caratteristici	variant (berry/jam), reasoning_level (espansione con ragionamento), negative_prompt (solo berry)	creativity 4 livelli (raw/low/medium/high)
Gestione del prompt	Ragionamento ed espansione prima di generare; anche frasi brevi producono un'immagine completa	Genera direttamente dal testo originale: più dettagli scrivi, più dettagli ottieni
Adatto a	Generazione finale, esplorazione rapida con prompt brevi, poster con testo	Generazione in batch, composizioni larghe, produzione quotidiana attenta al budget

I due modelli si possono usare in sequenza: Krea 2 per la bozza e la direzione, Krea 3 per il risultato finale; una bozza più un finale $0.0575. Per scegliere i prompt in base allo scenario vedi la raccolta di prompt.

Due percorsi per iniziare

Browser in 3 passi: apri la pagina del modello → incolla il prompt, scegli la dimensione → clicca genera, $0.036 per immagine.

API in 3 passi: POST /v1/tasks per inviare → ottieni il taskId → GET /v1/tasks/<taskId> finché lo stato è success, poi scarica.

curl: la prima immagine

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "krea-3/text-to-image",
  "input": {
    "prompt": "Studio product photograph of a frosted glass perfume bottle with a brushed brass cap standing on a block of travertine, hard afternoon sunlight casting a long palm-leaf shadow across a warm beige wall, crisp reflections, high-end editorial look",
    "image_size": "square_hd",
    "variant": "berry",
    "reasoning_level": "medium"
  }
}'

Per passare a Krea 2 Medium Turbo cambia solo model e i campi di input:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "krea-2-medium-turbo",
  "input": {
    "prompt": "Futuristic city skyline at dusk, neon reflections on wet streets, cinematic widescreen",
    "aspect_ratio": "2.35:1",
    "creativity": "low"
  }
}'

Il taskId nella risposta è la chiave per interrogare lo stato.

Python: invio, polling, download

import time, uuid, requests

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

payload = {
    "model": "krea-3/text-to-image",
    "input": {
        "prompt": "Studio product photograph of a frosted glass perfume bottle with a brushed brass cap standing on a block of travertine, hard afternoon sunlight casting a long palm-leaf shadow across a warm beige wall, crisp reflections, high-end editorial look",
        "image_size": "square_hd",
        "variant": "berry",
        "reasoning_level": "medium",
    },
}

# Invio: con Idempotency-Key, un retry di rete non crea task duplicati
resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

# Polling: queued -> handling -> archiving -> success / fail
while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(3)

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # URL temporaneo: scarica e salva al più presto
    img = requests.get(image_url, timeout=60)
    with open("output_image", "wb") as f:  # assegna l'estensione in base al formato effettivamente restituito
        f.write(img.content)
    print("saved")

Tabella dei parametri (krea-3/text-to-image)

Campo	Obbligatorio	Valori	Descrizione
prompt	Sì	1–5000 caratteri	Descrizione dell'immagine; più è specifica, più il risultato la segue
image_size	No	square_hd / square / portrait_4_3 / portrait_16_9 / landscape_4_3 / landscape_16_9, predefinito square_hd	Preset di dimensione, max 1024×1024; auto e dimensioni personalizzate non supportati
variant	No	berry / jam, predefinito berry	berry qualità prioritaria, jam velocità prioritaria; stesso prezzo
reasoning_level	No	low / medium, predefinito medium	Grado di espansione con ragionamento del prompt; usa medium per prompt brevi, low se scrivi in modo specifico
negative_prompt	No	≤1024 caratteri	Contenuti che non vuoi vedere; efficace solo con berry
output_format	No	png / jpeg, predefinito png	Formato di output
seed	No	intero 0–2147483647	Riproducibile all'interno della stessa variante; berry e jam non si riproducono a vicenda

Krea 2 Medium Turbo ha campi diversi: prompt (obbligatorio), aspect_ratio (8 valori, predefinito 1:1), creativity (raw/low/medium/high, predefinito low), seed. Se nel body della richiesta compare un campo non previsto dalla tabella, la risposta è direttamente 400.

Errori che incontrerai (messaggi originali dell'API)

Cosa hai fatto	Risposta
Hai passato auto in image_size	400 invalid input: image_size: value must be one of 'square_hd', 'square', 'portrait_4_3', 'portrait_16_9', 'landscape_4_3', 'landscape_16_9'
Hai passato un campo non previsto (es. num_images)	400 invalid input: <root>: additional properties 'num_images' not allowed
prompt vuoto	400 invalid input: prompt: minLength: got 0, want 1
variant scritto male	400 invalid input: variant: value must be one of 'berry', 'jam'
Saldo insufficiente	402 insufficient account balance; top up and retry

Le richieste che non superano la validazione dei parametri non vengono addebitate. Inviare di nuovo lo stesso Idempotency-Key restituisce 409 (in elaborazione) o 422 (parametri non coerenti): usa una nuova key e riprova.

Da sapere prima di andare in produzione

• Callback: passa "callback": {"url": "https://..."} al livello superiore del body; quando il task raggiunge lo stato finale il tuo servizio riceve una notifica, evitando il polling.
• Salva subito: output[0].url è un indirizzo temporaneo; appena lo ottieni scarica e salva nel tuo storage.
• Solo 6 dimensioni: per il 2.35:1 cinematografico o altre proporzioni usa aspect_ratio di Krea 2 Medium Turbo.
• Il seed si riproduce solo nella stessa variante: berry e jam con lo stesso seed danno immagini diverse; per una serie di immagini fissa variant + seed.

Domande frequenti

Funziona anche con prompt brevi?

Sì. Il modello ragiona ed espande, con a lighthouse si ottiene già un'immagine completa; se vuoi controllare i dettagli scrivi un prompt specifico.

berry e jam differiscono solo per la velocità?

Non solo per la velocità. Con lo stesso seed composizione e tonalità sono diverse e la qualità è paragonabile: trattale come due proposte, eseguile entrambe e poi scegli.

negative_prompt vale per entrambe le varianti?

È efficace solo con berry; se lo passi a jam non ha effetto.

Quante immagini per volta?

Una sola per volta. Per più immagini invia più task o cambia seed e riesegui.

Quante immagini con $10?

Krea 3 costa $0.036 a immagine, circa 277 immagini. I nuovi utenti ricevono 200 crediti alla registrazione (1 dollaro = 2.000 crediti).

Passo successivo: prendi il prompt del flacone di profumo e prova un'immagine nella pagina del modello, poi copia i template dalla raccolta di prompt in base allo scenario.