API imagen-4.0-fast: una richiesta text-to-image funzionante

Imagen 4 Fast è la variante rapida della serie Google Imagen 4 e su hiapi esegue la generazione text-to-image tramite la stessa API a task asincrona unificata di tutti gli altri modelli di immagini. Questa guida ti offre una richiesta realmente funzionante: una vera chiamata curl, un ciclo di polling in Python, lo schema di input chiuso preciso e i casi di errore verificati su esecuzioni in produzione. Tutto quanto segue è stato eseguito sull'endpoint di produzione prima della pubblicazione; il taskId e gli URL di output negli esempi provengono da quella esecuzione.

Cosa realizzerai

Una singola chiamata che trasforma un prompt testuale in un'immagine completa: invii il task a POST /v1/tasks, esegui il polling fino al completamento, quindi leggi l'URL dell'immagine. Ti serve una chiave API hiapi (creane una nella console e mantieni un po' di credito pay-as-you-go sull'account — vedi prezzi). Nessun SDK necessario; ogni esempio qui è puro HTTP.

Richiesta minima funzionante (curl)

Crea il task. L'id del modello è imagen-4.0-fast e su questa variante aspect_ratio è obbligatorio (maggiori dettagli sotto):

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0-fast",
    "input": {
      "prompt": "Colorful isometric city block with tiny cars and trees; playful 3D illustration",
      "aspect_ratio": "16:9"
    }
  }'

La chiamata di creazione restituisce solo un handle del task — non l'immagine:

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

Polling del risultato (Python)

Una volta ottenuto il taskId, esegui il polling su GET /v1/tasks/<id> finché lo stato non raggiunge uno stato terminale. Questo è il ciclo che ho effettivamente eseguito:

import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

# 1. create the task
created = requests.post(API, headers=HEADERS, json={
    "model": "imagen-4.0-fast",
    "input": {
        "prompt": "Colorful isometric city block with tiny cars and trees; playful 3D illustration",
        "aspect_ratio": "16:9",
    },
}).json()
task_id = created["data"]["taskId"]

# 2. poll until the task reaches a terminal state
while True:
    data = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
    status = data["status"]
    if status == "success":
        print(data["output"][0]["url"])   # the finished image
        break
    if status == "fail":
        raise RuntimeError(data)
    time.sleep(3)

Nella mia esecuzione, lo stato è passato da handling → archiving → success in circa 12 secondi, con la seguente risposta finale:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5D4ZD2X353AHHW3SW8X8N0A",
    "model": "imagen-4.0-fast",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M5D4ZD2X353AHHW3SW8X8N0A-0.webp",
        "expireAt": 1793121346
      }
    ]
  },
  "message": "success"
}

Un task restituisce un'immagine WebP. Lo stato archiving è normale — vi rimane brevemente, poi passa a success.

Schema di input (ciò che il server accetta realmente)

L'oggetto input è uno schema chiuso. Accetta solo i seguenti campi:

Campo	Tipo	Obbligatorio	Descrizione
prompt	string	Sì	Non vuoto; una stringa vuota restituisce minLength: got 0, want 1.
aspect_ratio	enum	Sì	Uno tra 1:1, 16:9, 9:16, 3:4, 4:3, auto. Nessun valore predefinito.
seed	integer	No	Per esecuzioni riproducibili. Deve essere un numero JSON, non una stringa.
negative_prompt	string	No	Descrive ciò che si desidera evitare nell'immagine.

Il modello non ha campi resolution o size — le dimensioni di output seguono aspect_ratio. Qualsiasi campo al di fuori di questa tabella viene rifiutato.

Casi di errore verificati (le insidie)

Questi non sono supposizioni — ognuno è una risposta 400 reale catturata sull'endpoint di produzione.

1. aspect_ratio mancante. È la trappola numero uno quando si copia uno snippet dalla variante base Imagen 4 o Ultra, dove aspect_ratio è predefinito a 1:1. Su Fast non esiste un valore predefinito:

{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: aspect_ratio: missing required field \"aspect_ratio\"; prompt: minLength: got 0, want 1" }

2. seed inviato come stringa. Passalo come numero:

{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: seed: got string, want integer" }

3. Campo sconosciuto (qui resolution) — lo schema chiuso rifiuta qualsiasi contenuto in eccesso:

{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'resolution' not allowed" }

Nota la forma: un errore di validazione è un HTTP 400, con error_code: "INVALID_REQUEST", senza taskId, e message aggrega ogni errore di campo in un'unica stringa separata da ; — quindi leggi tutto il contenuto, non solo la prima frase.

Fast rispetto alle altre varianti della serie Imagen 4

hiapi ospita tre varianti di Imagen 4 sulla stessa identica API a task; cambia solo l'id model, quindi il corpo della richiesta sopra funziona per tutte le varianti:

• imagen-4.0-fast — la variante rapida (pagina del modello), nonché l'opzione più economica della serie. Adatta all'iterazione dei prompt, all'esplorazione di concetti e all'esplorazione in batch di direzioni, ovvero generare molte candidati e conservarne pochi.
• imagen-4.0 — la variante standard Imagen 4.
• imagen-4.0-ultra — la variante con il massimo dettaglio, per risultati di qualità da consegna.

Un flusso di lavoro pratico: prototipa su Fast, poi sostituisci la stringa model con imagen-4.0-ultra per il rendering finale, senza modificare altro codice. Confronta i prezzi attuali per immagine sulla pagina dei prezzi.

Considerazioni per la produzione

• Polling vs. webhook. Il ciclo sopra è un polling. In produzione, l'API a task di hiapi supporta anche i webhook: aggiungi un oggetto callback di primo livello (allo stesso livello di model/input) contenente url e when: "final", e hiapi invierà via POST i dettagli del task quando raggiunge lo stato terminale. Prima di affidarti a questa funzionalità, leggi la documentazione dell'API asincrona per le convenzioni di consegna e retry.
• Non reinviare in caso di rete instabile. Ogni creazione di task restituisce un nuovo taskId — non c'è deduplicazione dei prompt. Se una richiesta di polling fallisce temporaneamente, riesegui il polling sul taskId che hai già salvato; esegui un nuovo POST solo se non hai mai ricevuto il taskId.
• Gli URL di output scadono. output[].url risiede su temp.hiapi.ai e il suo expireAt è di circa 7 giorni (l'esempio sopra scade il 2026-10-28). Scarica subito i byte nel tuo storage; non usare hotlink.

Contenuti correlati

• Pagina del modello Imagen 4 Fast
• Imagen 4 Ultra — variante con il massimo dettaglio, stessa struttura di richiesta
• Imagen 4 (base)
• Documentazione dell'API a task asincrona unificata
• Prezzi

Domande frequenti

Imagen 4 Fast richiede un endpoint o un SDK diverso? No. È semplicemente POST /v1/tasks con "model": "imagen-4.0-fast" — lo stesso endpoint utilizzato da tutti i modelli di immagini e video di hiapi. Cambia variante modificando l'id del modello.

Perché la mia richiesta restituisce 400 con «missing required field aspect_ratio»? Fast non ha un rapporto d'aspetto predefinito (a differenza della variante base e Ultra). Invia sempre aspect_ratio da enum 1:1 | 16:9 | 9:16 | 3:4 | 4:3 | auto.

Posso impostare la risoluzione o le dimensioni dell'immagine? No — il modello non ha campi resolution o size; le dimensioni di output seguono aspect_ratio. Inviare resolution restituisce additional properties 'resolution' not allowed.

seed è una stringa o un numero? Un numero. "seed": 7 funziona; "seed": "7" restituisce seed: got string, want integer.

Quanto dura l'URL di output? Circa 7 giorni (expireAt). Scarica e archivia immediatamente.