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

Imagen 4 Ultra è la versione del series Google Imagen 4 con il più alto livello di dettaglio. Su hiapi, come tutti gli altri modelli di immagini, esegue il text-to-image tramite la stessa API unificata a task asincroni. Questa guida fornisce una richiesta realmente funzionante: una chiamata curl reale, un ciclo di polling in Python, i parametri che il server accetta effettivamente e i casi di errore verificati con richieste reali. Tutto quanto segue è stato eseguito e verificato sull'endpoint di produzione prima della pubblicazione; il taskId di esempio e gli URL di output provengono da quella esecuzione.

Cosa costruirai

Una singola chiamata trasforma un prompt testuale in un'immagine finita: invia il task a POST /v1/tasks, esegui il polling fino al completamento, quindi leggi l'URL dell'immagine da output[0].url. Ti serve una chiave API hiapi: ottienila dalla tua dashboard ed esportala:

export HIAPI_API_KEY="your-hiapi-key"

Esempio minimo funzionante (curl)

Il modello accetta prompt e l'opzionale aspect_ratio. Crea il task:

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0-ultra",
    "input": {
      "prompt": "Macro product photo of a matte ceramic coffee mug on a pale oak table, soft window light from the left, shallow depth of field, a few coffee beans in the foreground, no text, no logos",
      "aspect_ratio": "4:3"
    }
  }'

La chiamata di creazione restituisce immediatamente un id del task: la generazione prosegue in background:

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

Esegui il polling del task usando l'id restituito:

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01M5CVC8R62M0Z7CCM8WB38B61" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Quando status è success, l'immagine si trova in output[0].url:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5CVC8R62M0Z7CCM8WB38B61",
    "model": "imagen-4.0-ultra",
    "status": "success",
    "storage": "temp",
    "created": 1792506471,
    "completed": 1792506479,
    "output": [
      {
        "artifactId": "279760",
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M5CVC8R62M0Z7CCM8WB38B61-0.webp",
        "expireAt": 1793111279
      }
    ]
  },
  "message": "success"
}

Quella esecuzione si è completata in circa 8 secondi e ha restituito un WebP (non PNG/JPEG). L'URL si trova su storage temporaneo ("storage": "temp"), con expireAt impostato a 7 giorni dopo: scaricalo tempestivamente, non usare hotlink.

Produzione: Python con ciclo di polling

La risposta di creazione non contiene l'immagine, solo taskId. Un'integrazione reale invia il task e poi esegue il polling (oppure usa una callback). Questo script completa l'intero round-trip e scarica subito il risultato, perché l'URL è temporaneo:

import os, time, requests

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

def generate(prompt, aspect_ratio="1:1", negative_prompt=None, seed=None):
    body = {"model": "imagen-4.0-ultra", "input": {"prompt": prompt, "aspect_ratio": aspect_ratio}}
    if negative_prompt:
        body["input"]["negative_prompt"] = negative_prompt
    if seed is not None:
        body["input"]["seed"] = str(seed)  # seed is a STRING, not a number

    r = requests.post(API, headers=HEADERS, json=body, timeout=60)
    r.raise_for_status()
    created = r.json()
    if created.get("code") != 200:
        raise RuntimeError(f"create rejected: {created}")
    task_id = created["data"]["taskId"]

    # Poll. Statuses other than success/fail (e.g. queued, running, archiving) mean "keep waiting".
    for _ in range(60):
        time.sleep(3)
        try:
            d = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except requests.RequestException:
            continue  # tolerate a transient read; re-poll the same id
        status = d.get("status")
        if status == "success":
            return d["output"][0]["url"]
        if status in ("fail", "failed", "error"):
            raise RuntimeError(f"task failed: {d}")
    raise TimeoutError(f"task {task_id} did not finish in time")

url = generate(
    "A high-detail aerial landscape of terraced rice fields at golden hour, long shadows",
    aspect_ratio="16:9",
)
img = requests.get(url, timeout=60).content
open("out.webp", "wb").write(img)
print(f"saved {len(img)} bytes from {url}")

Note importanti per la produzione:

• Polling vs callback. Quanto sopra mostra il polling. Per evitare il polling, puoi allegare un oggetto callback di primo livello ({"url": "...", "when": "final"}): hiapi invierà una richiesta POST al tuo endpoint quando il task raggiunge lo stato finale. Il contratto della callback è descritto nella documentazione dell'API asincrona unificata.
• Riesegui il polling dell'id salvato, non ricreare. La lettura di un task è idempotente; se la connessione cade, riprova GET /v1/tasks/<id>, non eseguire mai di nuovo POST (verrebbe addebitata un'altra immagine).
• Scarica appena il task ha successo. output[0].url è temporaneo (in questa esecuzione il TTL è di 7 giorni). Scarica i byte e caricali sul tuo storage.

Parametri effettivamente accettati da questo modello

imagen-4.0-ultra supporta solo text-to-image: non supporta immagini di riferimento (confermato nella pagina del modello; in questa esecuzione è stato testato solo il text-to-image). Lo schema di input è chiuso: i campi sconosciuti vengono rifiutati, quindi non è possibile introdurre parametri aggiuntivi di nascosto.

Campo	Tipo	Obbligatorio	Descrizione
prompt	string	Sì	Da 1 a 5.000 caratteri. Una stringa vuota fallisce (minLength: got 0, want 1).
aspect_ratio	enum	No	Uno tra 1:1, 16:9, 9:16, 3:4, 4:3, auto. Il valore predefinito è 1:1.
negative_prompt	string	No	Massimo 5.000 caratteri; descrive ciò che deve essere escluso.
seed	string	No	Massimo 500 caratteri. È una stringa: passare un numero viene rifiutato.

Una richiesta genera esattamente una immagine.

Casi di errore verificati

Questi sono stati prodotti sull'endpoint reale, quindi la tua gestione degli errori può basarsi su di essi. Le richieste rifiutate restituiscono HTTP 400, con una envelope piatta e senza taskId:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: aspect_ratio: value must be one of '1:1', '16:9', '9:16', '3:4', '4:3', 'auto'"}

Alcuni comportamenti da tenere presenti nel codice:

• Il validatore segnala tutti gli errori dei campi in una sola volta, concatenandoli con ; . Se passi un numero a seed e un aspect_ratio non valido, otterrai entrambi in un unico messaggio: invalid input: seed: got number, want string; aspect_ratio: value must be one of .... Non dare per scontato che ogni risposta contenga un solo errore.
• I campi sconosciuti fanno fallire l'intera richiesta, con l'errore <root>: additional properties '<name>' not allowed. Lo schema è chiuso.
• Un prompt vuoto fallisce con l'errore prompt: minLength: got 0, want 1.
• Una create riuscita restituisce code: 200 con data.taskId; un rifiuto restituisce data: null. Ramifica su questo prima di tentare di leggere l'id del task.

Quale tier di Imagen 4 conviene chiamare?

imagen-4.0-ultra è il livello più alto dei tre; scegli in base al task, non per abitudine (aspect ratio, negative prompt e seed non influiscono su quanto paghi: vedi prezzi):

• Imagen 4 Fast — il più economico, adatto a scansioni di bozze e a esplorare direzioni in batch.
• Imagen 4 — il livello intermedio quotidiano, adatto a immagini di prodotto, lifestyle e contenuti.
• Imagen 4 Ultra (questo modello) — il più costoso dei tre, posizionato per il dettaglio di livello finale: texture macro, rendering dei materiali e tipografia, per scenari in cui l'immagine finale deve reggere un esame ravvicinato. Scegli Ultra quando l'output è direttamente consegnabile; per le iterazioni usa Fast o il livello base.

Link correlati

• Pagina del modello Imagen 4 Ultra — schema in tempo reale, esempi e prezzi.
• Documentazione dell'API asincrona unificata — creazione/elenco/lettura dei task e contratto della callback.
• Guida rapida — completa l'autenticazione ed esegui il tuo primo task in pochi minuti.
• Prezzi — costo per immagine di ciascun livello di Imagen 4.

Domande frequenti

Quante immagini restituisce una richiesta? Una. Nell'esecuzione verificata, l'array output conteneva un solo elemento.

Qual è il formato dell'output? WebP. Il file restituito è un .webp su temp.hiapi.ai.

Per quanto tempo è valido l'URL di output? Circa 7 giorni: expireAt è impostato a 7 giorni dopo il completamento. Trattalo come una risorsa temporanea e scaricalo subito.

Posso inviare immagini di riferimento? No. imagen-4.0-ultra supporta solo text-to-image; la pagina del modello indica le immagini di riferimento come non supportate.

Perché la mia richiesta restituisce l'errore "additional properties not allowed"? Lo schema di input è chiuso. Invia solo prompt, aspect_ratio, negative_prompt e seed; qualsiasi altra chiave fa fallire l'intera richiesta.

Il negative prompt, il seed o l'aspect ratio modificano il prezzo? No. La fatturazione è per immagine; questi parametri non influiscono sul costo.