Come si usa l'API di Imagen 4? La tua prima immagine in 5 minuti

TL;DR

• Imagen 4 (imagen-4.0) è un modello text-to-image, $0.06 per immagine: scrivi un prompt, scegli il formato e ottieni l'immagine. Ideale per ritratti fotografici, primi piani naturali e nature morte di prodotto. Apri la pagina del modello per provarlo online; i nuovi utenti ricevono 200 crediti alla registrazione.
• Della stessa famiglia fanno parte altre due versioni: imagen-4.0-fast a $0.03 per immagine per molti bozzetti, imagen-4.0-ultra a $0.09 per immagine per i dettagli del prodotto finale.
• Le chiamate passano dall'interfaccia HiAPI /v1/tasks: invia il task e ottieni il taskId, poi interroga il risultato e, in caso di successo, scarica l'immagine da output[0].url.

Cosa sa fare

• Immagine direttamente dal testo: non accetta immagini di riferimento, l'immagine è interamente descritta dal prompt; aspect_ratio è obbligatorio (1:1, 16:9, 9:16, 3:4, 4:3, auto: sei opzioni).
• Tre posizionamenti in un'unica famiglia: Fast per i bozzetti, la versione standard per la produzione quotidiana, Ultra per i dettagli; i tre ID modello si usano in fasi diverse nello stesso progetto.
• Sempre 1 immagine per volta: non esistono parametri per numero di immagini, dimensioni in pixel o formato di output; per rigenerare basta cambiare il seed.

Ecco un risultato reale della versione standard:

Sunlit Scandinavian living room with linen sofa; oak shelves and a monstera plant; editorial interior photography

(In italiano: soggiorno scandinavo luminoso, divano in lino, mensole in rovere e una pianta di monstera; fotografia d'interni in stile editoriale. Formato scelto: 16:9.)

imagen-4.0, 16:9, 1280×720, $0.06.

Genera con questo prompt →

Come scegliere tra i tre modelli

	imagen-4.0-fast	imagen-4.0 (standard)	imagen-4.0-ultra
Per immagine	$0.03	$0.06	$0.09
Posizionamento	Molti bozzetti, scelta della direzione	Produzione quotidiana	Dettagli del prodotto finale, materiali e impaginazione del testo
Con $10 circa	333 immagini	166 immagini	111 immagini
Adatto a	Riunioni di selezione, giri di bozze	Consegna di immagini ordinarie	Versione definitiva, immagini sensibili ai dettagli

Riferimento di budget: usando sempre la versione standard, 1.000 immagini al mese costano circa $60,00; più bozzetti sposti su Fast, più il conto scende, lasciando a Ultra il volume della versione definitiva.

I tre modelli si chiamano allo stesso modo, cambiando solo il campo model; la struttura dei parametri è identica, cambia solo il tipo di seed (vedi la tabella dei parametri). Fast e Ultra hanno ciascuno una guida di integrazione in inglese: Imagen 4 Fast API guide, Imagen 4 Ultra API guide. Per scegliere i prompt in base allo scenario consulta la raccolta di prompt; la tabella completa dei prezzi delle tre versioni e il budget mensile sono nella pagina dei prezzi, mentre il confronto con Nano Banana 2.1 sugli stessi due gruppi di prompt è nella pagina di confronto.

Due percorsi per iniziare

Browser in 3 passi: apri la pagina del modello → incolla il prompt, scegli il formato → clicca su genera; la versione standard costa $0.06 per immagine. Al primo tentativo conviene generare un'immagine nel browser per verificare che lo stile corrisponda alle aspettative, poi passare al codice.

API in 3 passi: invia con POST /v1/tasks → ottieni il taskId → interroga con GET /v1/tasks/<taskId> e, quando lo stato è success, 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": "imagen-4.0",
  "input": {
    "prompt": "Sunlit Scandinavian living room with linen sofa; oak shelves and a monstera plant; editorial interior photography",
    "aspect_ratio": "16:9"
  }
}'

Per cambiare versione basta modificare model: imagen-4.0-fast o imagen-4.0-ultra. Il taskId restituito è la credenziale per la ricerca.

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": "imagen-4.0",
    "input": {
        "prompt": "Sunlit Scandinavian living room with linen sofa; oak shelves and a monstera plant; editorial interior photography",
        "aspect_ratio": "16:9",
    },
}

# Invio: con Idempotency-Key, i retry di rete non creano 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"]   # indirizzo 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

Campo	Obbligatorio	Valori	Descrizione
prompt	Sì	1–5000 caratteri	Descrizione del contenuto dell'immagine
aspect_ratio	Sì	1:1 / 16:9 / 9:16 / 3:4 / 4:3 / auto	Formato di output, obbligatorio
negative_prompt	No	≤5000 caratteri	Contenuti che non si desidera vedere
seed	No	Standard e Ultra: stringa (≤500 caratteri); Fast: intero	Con gli stessi parametri e lo stesso seed si riproduce l'immagine

I tre modelli condividono la stessa tabella dei parametri. Se nel corpo della richiesta compare un campo non previsto dalla tabella, si riceve direttamente un errore 400.

Gli errori che incontrerai

Codice di stato	Significato	Come gestirlo
400 INVALID_REQUEST	Corpo della richiesta non valido (prompt o aspect_ratio mancanti, valore enum errato, campo non previsto dalla tabella)	Correggi il corpo della richiesta confrontandolo con la tabella dei parametri
402 INSUFFICIENT_QUOTA	Credito insufficiente (nessun addebito)	Ricarica e riprova
429 RATE_LIMITED	Limite di frequenza attivato	Riduci la frequenza di invio
409 / 422 IDEMPOTENCY_KEY_*	Stessa chiave di idempotenza inviata più volte (in elaborazione / parametri non coerenti)	Usa un nuovo Idempotency-Key
415 UNSUPPORTED_MEDIA_TYPE	Formato della richiesta errato	Controlla Content-Type: application/json

Se il task termina in stato di errore, ci sono anche codici come CONTENT_POLICY_VIOLATION, TASK_FAILED, TASK_TIMEOUT e altri; in caso di errore non viene addebitato nulla e i crediti prenotati vengono restituiti per intero.

Da tenere presente prima della messa in produzione

• Callback: passa "callback": {"url": "https://..."} al livello superiore del corpo della richiesta; quando il task raggiunge lo stato finale il tuo servizio viene notificato, evitando il polling.
• Salva subito: output[0].url è un indirizzo temporaneo; appena lo ricevi, scarica e salva nel tuo storage.
• Specifica il formato in modo esplicito: aspect_ratio è obbligatorio, non affidarti ai valori predefiniti; per i contenuti social in verticale scegli 9:16.
• Tipo di seed per modello: Fast accetta un intero, la versione standard e Ultra una stringa.

Domande frequenti

I tre modelli si chiamano allo stesso modo?

Sì, cambia solo il campo model, il resto del codice non va modificato.

Si possono specificare dimensioni in pixel o formato di output?

No. Non ci sono parametri per dimensioni in pixel e formato; il formato di output è determinato da aspect_ratio e si ottiene 1 immagine per volta.

In caso di errore vengono addebitati costi?

No. I crediti prenotati vengono restituiti per intero dopo lo stato finale di errore.

Il testo nelle immagini è affidabile?

Va ingrandito e verificato. Nelle immagini di poster può capitare che manchi una lettera o un tratto; prima della pubblicazione ingrandisci e controlla la parte testuale.

Le immagini delle tre versioni possono convivere nello stesso progetto?

Sì. La logica di prompt e formato è comune.

Prossimo passo: copia il prompt del soggiorno qui sopra e prova a generare un'immagine nella pagina del modello, poi scegli i template nella raccolta di prompt in base allo scenario per generare in batch.