Come usare l'API di text-to-image krea-2-medium-turbo (curl + Python)

krea-2-medium-turbo è il livello veloce ed economico di text-to-image offerto da Krea su hiapi. Basta inviare un prompt, scegliere un aspect ratio e ottenere un'immagine renderizzata tramite l'API di task asincrona. Questa guida fornisce esempi di richiesta curl e Python pronti da copiare e incollare, destinati a /v1/tasks, con lo schema di input esatto, oltre ai tempi di esecuzione e ai comportamenti in caso di errore che ho misurato dal vivo il 2026-10-21 — inclusi un risultato in contrasto con quanto descritto nella documentazione.

Prerequisiti

Una chiave API hiapi (sk-...). Creala nella console API Keys. Ogni richiesta si autentica tramite Authorization: Bearer sk-<your-key>. Questo è l'unico prerequisito — il modello viene eseguito lato server, quindi non serve installare nulla oltre a un client HTTP.

Schema di input

krea-2-medium-turbo accetta cinque campi. Solo prompt e model sono obbligatori:

Campo	Obbligatorio	Tipo	Predefinito	Descrizione
model	Sì	string	—	Deve essere esattamente krea-2-medium-turbo.
prompt	Sì	string	—	Da 1 a 5000 caratteri.
aspect_ratio	No	enum	1:1	Uno tra 1:1, 4:3, 3:2, 16:9, 2.35:1, 4:5, 2:3, 9:16.
creativity	No	enum	low	raw (il più letterale) → low → medium → high (il più creativo).
seed	No	integer	—	Opzionale. Prima di farci affidamento, leggi l'avvertenza sul seed qui sotto.

L'oggetto input è rigoroso (additionalProperties: false): qualsiasi campo non presente in questa tabella viene rifiutato prima che la generazione inizi. Non ci sono n / num_images, né resolution o size, né campi per il negative prompt. Una richiesta restituisce esattamente un'immagine, e le dimensioni dell'output dipendono interamente da aspect_ratio. Se hai usato altre API di immagini su hiapi che accettano resolution (Seedream, Qwen-Image) o size, ricorda che qui quei campi vanno rimossi — restituiscono un 400.

Richiesta minima funzionante (curl)

La creazione del task restituisce immediatamente un taskId; l'immagine viene renderizzata in background.

curl -s -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "krea-2-medium-turbo",
    "input": {
      "prompt": "A lighthouse on a rocky coast at golden hour, cinematic wide shot",
      "aspect_ratio": "2.35:1",
      "creativity": "medium",
      "seed": 42
    }
  }'

Risposta:

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

Poi esegui il polling del task per id finché non raggiunge lo stato finale:

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

Un task completato si presenta così (campi ridotti per chiarezza):

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5E4J4FQVJNSDKQ29BRSMD0A",
    "model": "krea-2-medium-turbo",
    "status": "success",
    "storage": "temp",
    "created": 1792549655,
    "completed": 1792549681,
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/xxxxxxxx/01M5E4J4FQVJNSDKQ29BRSMD0A-0.png",
        "artifactId": "280334",
        "expireAt": 1793154481
      }
    ]
  },
  "message": "success"
}

L'immagine si trova in data.output[0].url.

Lo stesso flusso in Python

import time
import requests

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

def generate(prompt, aspect_ratio="1:1", creativity="low", seed=None):
    body = {
        "model": "krea-2-medium-turbo",
        "input": {"prompt": prompt, "aspect_ratio": aspect_ratio, "creativity": creativity},
    }
    if seed is not None:
        body["input"]["seed"] = seed

    created = requests.post(API, headers=HEADERS, json=body, timeout=30)
    created.raise_for_status()
    task_id = created.json()["data"]["taskId"]

    # Esegui il polling finché il task non raggiunge lo stato finale.
    while True:
        data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        status = data["status"]
        if status == "success":
            return data["output"][0]["url"]
        if status == "fail":                 # Nota: restituisce comunque HTTP 200, vedi sotto
            raise RuntimeError(f"generation failed: {data}")
        time.sleep(3)

url = generate(
    "A lighthouse on a rocky coast at golden hour, cinematic wide shot",
    aspect_ratio="2.35:1",
    creativity="medium",
)
print(url)

Considerazioni per la produzione

• Polling o callback. Il ciclo sopra esegue il polling ogni 3 secondi, il che va bene con volumi bassi di concorrenza. In produzione, puoi allegare callback.url e impostare when: "final" al momento della richiesta di creazione, facendo sì che hiapi invii via POST il task completato a te invece di fare polling — le convenzioni delle callback sono nella documentazione dell'API dei task.
• Una generazione fallita restituisce comunque HTTP 200. Il codice di stato HTTP sull'endpoint di polling indica se la richiesta è andata a buon fine, non se l'immagine è stata generata. Un errore di rendering viene restituito con 200 e data.status: "fail". Ramifica su data.status, non sul codice di stato HTTP, altrimenti tratterai un fallimento come un successo.
• Gli URL di output sono temporanei. I risultati sono archiviati con "storage": "temp" su temp.hiapi.ai e hanno un timestamp expireAt che scade dopo circa sette giorni (604.800 secondi nella mia esecuzione). Scarica i byte e ri-ospitali (nel tuo bucket/CDN) non appena il task è completato — non usare link diretti agli URL di temp.hiapi.ai nelle pagine di produzione.
• Il prezzo è una tariffa fissa per immagine, indipendente dall'aspect ratio o dal livello di creatività — non ci sono livelli di risoluzione da considerare. Consulta le cifre aggiornate sulla pagina dei prezzi invece di hardcodificarle.

Cosa ho testato effettivamente (2026-10-21)

Tutto quanto segue deriva da chiamate live, non dalla documentazione:

• Tempi e risoluzione. Una richiesta 2.35:1 è stata completata in circa 26 secondi (differenza created → completed), restituendo un PNG da 1568 × 672 px — quindi 2.35:1 è davvero un ritaglio cinematografico widescreen, non quasi quadrato. Durante il rendering e lo spostamento del file nello storage temporaneo, il task attraversa gli stati intermedi handling → archiving → success.
• La validazione dell'enum è applicata lato server. Inviare "aspect_ratio": "21:9" (un valore plausibile ma non supportato) restituisce immediatamente 400: invalid input: aspect_ratio: value must be one of '1:1', '4:3', '3:2', '16:9', '2.35:1', '4:5', '2:3', '9:16'. Il messaggio di errore indica il campo ed elenca i valori validi, il che è comodo da gestire a livello di codice.
• I campi sconosciuti restituiscono 400, non vengono ignorati. "resolution": "2K" restituisce invalid input: <root>: additional properties 'resolution' not allowed; "n": 2 restituisce lo stesso errore per n. È la regola additionalProperties: false in azione — se copi il corpo di una richiesta da un altro modello, i campi in eccesso bloccano l'intera chiamata.
• Nei miei test, seed non ha riprodotto immagini identiche. Ho inviato due volte lo stesso prompt, con seed: 42, aspect_ratio: 2.35:1 e creativity: medium. Entrambe le volte è tornata un'immagine valida da 1568 × 672, ma le scene erano chiaramente diverse (una torre bianca, una torre a strisce bianche e rosse), le dimensioni dei file diverse (1,30 MB contro 1,51 MB) e gli hash diversi. Il campo è accettato e la documentazione lo descrive come riproducibile, ma considera la riproduzione esatta dei pixel come un obiettivo best-effort, non una garanzia — se ti serve una scena specifica, salva il risultato che ottieni, non ri-richiedere usando il seed.

Pagine correlate

• Pagina del modello krea-2-medium-turbo——playground online e riferimento completo dei parametri.
• Documentazione API di krea-2-medium-turbo——dettagli su endpoint e callback.
• Krea 3 text-to-image——il livello più recente di Krea orientato alla qualità (con modalità berry/jam); usalo quando vuoi più definizione, mentre krea-2-medium-turbo è per velocità e basso costo.
• API di generazione di immagini AI su hiapi——altri modelli text-to-image dietro la stessa interfaccia dei task.

FAQ

Quali aspect ratio posso richiedere? Otto: 1:1 (predefinito), 4:3, 3:2, 16:9, 2.35:1, 4:5, 2:3 e 9:16. Qualsiasi altro valore restituisce 400.

Posso generare più immagini con una sola chiamata? No. Non c'è un campo n e lo schema rifiuta le proprietà sconosciute, quindi ogni richiesta genera esattamente un'immagine. Per generare in batch, invia le richieste in un ciclo (eventualmente con seed diversi).

A cosa serve creativity? Controlla quanto letteralmente il modello segue il prompt: raw è il più fedele alla formulazione, high concede la massima libertà interpretativa, low (predefinito) e medium stanno nel mezzo.

krea-2-medium-turbo supporta image-to-image o l'editing? No — supporta solo text-to-image. Lo schema non ha campi image_urls / immagine di input. Se devi trasformare un'immagine esistente, usa un modello dedicato per editing/image-to-image su hiapi.

Quanto durano gli URL di output? Sono serviti da storage temporaneo e scadono (nel mio test dopo circa sette giorni). Scarica e ri-ospitala le immagini non appena il task è completato.