Come si usa l'API Recraft V4.1? Genera immagini con la palette colori in 5 minuti

TL;DR

• La serie Recraft V4.1 è una coppia di modelli text-to-image con parametri identici: recraft-v4.1/text-to-image produce il risultato finale più dettagliato ($0.05/immagine), recraft-v4.1-flash/text-to-image serve per le bozze rapide ($0.01/immagine, prezzi completi nella pagina prezzi), l'unica differenza è il campo model. Apri la pagina del modello per provarlo, i nuovi utenti ricevono 200 crediti alla registrazione.
• La caratteristica è la palette brand: passando un set di RGB in colors, l'immagine tende a mantenersi su questi colori (non disponibile nel Playground, solo via API).
• La chiamata passa dall'interfaccia HiAPI /v1/tasks: invii il task e ottieni taskId, poi interroghi il risultato e, in caso di successo, scarichi da output[0].url.

Cosa può fare

• Fotografia, illustrazione, poster: immagini prodotto realistiche, illustrazioni vettoriali flat, poster con titolo, tutto con una sola descrizione.
• Colori controllabili: colors specifica la palette, background_color il colore di sfondo, per restare fedeli al VI quando si creano materiali brand.
• 6 preset di dimensione: square_hd (predefinito), square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9, nessuna larghezza/altezza personalizzata.
• Bozze con Flash + versione finale con V4.1: stessi parametri, cambia solo model, 10 bozze più 1 versione finale a $0.15.

Qui sotto un risultato reale di V4.1:

Minimalist brand poster for a specialty coffee brand, huge bold headline "NORTH BEAN" in clean sans-serif, warm terracotta and cream palette, single coffee bean illustration, generous negative space, Swiss grid layout

(In italiano: poster minimalista per un brand di caffè specialty, enorme titolo in grassetto sans-serif "NORTH BEAN", palette terracotta caldo e crema, illustrazione di un singolo chicco di caffè, ampio spazio negativo, layout a griglia svizzera. Dimensione scelta: portrait_4_3.)

recraft-v4.1/text-to-image, portrait_4_3, immagine di esempio di questo articolo 896×1216, $0.05.

Genera con questo prompt →

Come scegliere tra i due modelli

	recraft-v4.1-flash/text-to-image	recraft-v4.1/text-to-image
Per immagine	$0.01	$0.05
Posizionamento	Bozze rapide, scelta della direzione	Versione finale più dettagliata
Parametri	Identici (prompt / image_size / colors / background_color)	Come a sinistra
Adatto a	Esplorazione in batch, immagini per social, round di bozze	Versioni da consegnare, materiali brand

I due modelli condividono la stessa pipeline: Flash produce 10 direzioni a $0.10, quella scelta si rilancia cambiando model come versione finale V4.1 a $0.05, il tutto a $0.15. Viceversa, se servono solo bozze, tutto con Flash: 1.000 immagini costano solo $10.00. 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, una V4.1 costa $0.05. (colors e background_color richiedono l'API.) La prima volta conviene provare una generazione nel browser per verificare che lo stile sia quello atteso prima di scrivere codice.

API in 3 passi: POST /v1/tasks per inviare → ottieni taskId → GET /v1/tasks/<taskId> finché non vedi success, poi scarichi.

curl: la prima immagine (con palette brand)

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": "recraft-v4.1-flash/text-to-image",
  "input": {
    "prompt": "Flat vector illustration of a cozy reading nook with an armchair, a tall plant and a round window showing a city skyline at dusk, clean geometric shapes, gentle grain",
    "image_size": "landscape_4_3",
    "colors": [
      {"r": 28, "g": 61, "b": 90},
      {"r": 240, "g": 128, "b": 60},
      {"r": 245, "g": 222, "b": 179}
    ],
    "background_color": {"r": 250, "g": 246, "b": 238}
  }
}'

Questo esempio usa i parametri reali del caso Flash: palette a tre colori blu scuro, arancione e grano, con sfondo bianco sporco. Per la versione finale sostituisci model con recraft-v4.1/text-to-image, il resto resta invariato.

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": "recraft-v4.1/text-to-image",
    "input": {
        "prompt": "Minimalist brand poster for a specialty coffee brand, huge bold headline \"NORTH BEAN\" in clean sans-serif, warm terracotta and cream palette, single coffee bean illustration, generous negative space, Swiss grid layout",
        "image_size": "portrait_4_3",
    },
}

resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

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"]   # indirizzo temporaneo, scarica e salva al più presto
    img = requests.get(image_url, timeout=60)
    with open("output_image", "wb") as f:
        f.write(img.content)
    print("saved")

Tabella parametri (identica per i due modelli)

Campo	Obbligatorio	Valori	Descrizione
prompt	Sì	1–10000 caratteri	Descrizione dell'immagine
image_size	No	square_hd (predefinito) / square / portrait_4_3 / portrait_16_9 / landscape_4_3 / landscape_16_9	6 preset, nessuna larghezza/altezza personalizzata
colors	No	Array di oggetti RGB, canali 0–255	Guida forte della palette: l'immagine tende a mantenersi su questi colori; non disponibile nel Playground
background_color	No	Singolo oggetto RGB	Colore di sfondo; non disponibile nel Playground

Ogni oggetto RGB richiede tutte e tre le chiavi r/g/b, ciascuna 0–255, e non ammette chiavi aggiuntive. La presenza di campi non previsti dalla tabella nel body della richiesta restituisce direttamente 400.

Errori che incontrerai (testo originale dell'API)

Cosa hai fatto	Risposta
Hai omesso prompt	400 invalid input: prompt: missing required field "prompt"
Hai passato un oggetto larghezza/altezza a image_size	400 invalid input: image_size: got object, want string
Un canale di colors è 256	400 invalid input: colors.0.r: maximum: got 256, want 255
A colors manca la chiave b	400 invalid input: colors.0.b: missing required field "b"
Hai passato colors come stringa	400 invalid input: colors: got string, want array
L'oggetto RGB ha una chiave in più	400 invalid input: colors.0: additional properties 'a' not allowed
Saldo insufficiente	402 insufficient account balance; top up and retry
Un reinvio con lo stesso Idempotency-Key restituisce 409 o 422, riprova con una nuova key.

Da sapere prima di andare in produzione

• Callback: passa "callback": {"url": "https://..."} al livello superiore del body, per essere notificato automaticamente allo stato terminale.
• Salva subito: output[0].url è un indirizzo temporaneo, scaricalo appena lo ricevi nel tuo storage, non usarlo come link permanente.
• La palette è una guida, non un vincolo: se nel prompt scrivi colori in conflitto con colors, il risultato può mescolare i due; se vuoi colori strettamente aderenti, non scrivere altri colori nel prompt.
• Da Flash a V4.1 cambia solo model: gli altri parametri restano invariati, l'idea di composizione si riutilizza direttamente.

Domande frequenti

I parametri dei due modelli sono uguali?

Identici. Cambia solo il campo model, zero modifiche al codice.

Dove si imposta il parametro colors?

Solo via API. Il Playground non mette a disposizione i parametri colors e background_color.

colors garantisce che si usino solo i colori specificati?

No. È una guida forte, l'immagine tende a mantenersi su quella palette, ma non è un vincolo rigido.

Quante immagini per volta?

1 per volta. Per averne di più, invia più task o mettili in coda.

Quante immagini con $10?

Flash costa $0.01 per immagine, con $10 ne ottieni 1.000. I fallimenti non vengono addebitati.

Prossimo passo: prendi il prompt NORTH BEAN e genera un'immagine dalla pagina del modello, e quando ti servono i colori brand aggiungi colors alla richiesta API; per i template per scenario vedi la raccolta di prompt.