imagen-4.0-fast API: Eine funktionierende Text-zu-Bild-Anfrage

Imagen 4 Fast ist die Geschwindigkeitsstufe der Google Imagen 4-Serie, und auf hiapi erzeugt sie Text-zu-Bild über dieselbe einheitliche asynchrone Task-API wie alle anderen Bildmodelle. Dieser Leitfaden liefert dir eine wirklich lauffähige Anfrage – einen echten curl-Aufruf, eine Python-Polling-Schleife, das exakte geschlossene Eingabe-Schema und Fehlerfälle, die im Live-Betrieb verifiziert wurden. Alles im Folgenden wurde vor der Veröffentlichung gegen den Produktions-Endpoint ausgeführt; die taskId und die Ausgabe-URL in den Beispielen stammen aus diesem Lauf.

Was du erreichen wirst

Ein einziger Aufruf verwandelt einen Text-Prompt in ein fertiges Bild: Task an POST /v1/tasks übermitteln, bis zur Fertigstellung pollen, dann die Bild-URL abrufen. Du brauchst einen hiapi API-Key (erstellen im Console und etwas Guthaben für nutzungsbasierte Abrechnung im Konto halten – siehe Preise). Kein SDK nötig; jedes Beispiel hier ist reines HTTP.

Minimale funktionierende Anfrage (curl)

Task erstellen. Die Modell-ID ist imagen-4.0-fast, und in dieser Stufe ist aspect_ratio erforderlich (Details unten):

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"
    }
  }'

Der Erstellungsaufruf gibt nur ein Task-Handle zurück – kein Bild:

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

Ergebnis pollen (Python)

Sobald du die taskId hast, polle GET /v1/tasks/<id>, bis der Status einen Endzustand erreicht. Dies ist die Schleife, die ich tatsächlich ausgeführt habe:

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)

In meinem Lauf durchlief der Status innerhalb von etwa 12 Sekunden handling → archiving → success, und die Endzustands-Antwort sah so aus:

{
  "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"
}

Ein Task liefert ein WebP-Bild. Der Status archiving ist normal – er hält kurz an und springt dann auf success.

Eingabe-Schema (was der Server tatsächlich akzeptiert)

Das input-Objekt ist ein geschlossenes Schema. Es akzeptiert nur die folgenden Felder:

Feld	Typ	Erforderlich	Beschreibung
prompt	string	Ja	Nicht leer; ein leerer String liefert minLength: got 0, want 1.
aspect_ratio	enum	Ja	Einer von 1:1, 16:9, 9:16, 3:4, 4:3, auto. Kein Standardwert.
seed	integer	Nein	Für reproduzierbare Läufe. Muss eine JSON-Zahl sein, kein String.
negative_prompt	string	Nein	Beschreibt, was im Bild vermieden werden soll.

Das Modell hat kein resolution- oder size-Feld – die Ausgabegröße folgt aspect_ratio. Jedes Feld außerhalb dieser Tabelle wird abgelehnt.

Verifizierte Fehlerfälle (die Stolperfallen)

Diese sind keine Vermutungen – jeder einzelne ist eine echte 400-Antwort, die gegen den Live-Endpoint erfasst wurde.

1. Fehlendes aspect_ratio. Dies ist die größte Falle, wenn du Code-Snippets von der Basis-Imagen 4- oder Ultra-Stufe kopierst, denn dort ist aspect_ratio standardmäßig 1:1. Bei Fast gibt es keinen Standardwert:

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

2. seed als String gesendet. Übergib ihn als Zahl:

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

3. Unbekanntes Feld (hier resolution) – das geschlossene Schema lehnt jeden Überschuss ab:

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

Achte auf die Form: Validierungsfehler sind HTTP 400 mit error_code: "INVALID_REQUEST", ohne taskId, und die message fasst alle Feldfehler zu einem durch ; getrennten String zusammen – lies also den gesamten Text, nicht nur den ersten Satz.

Fast im Vergleich zu den anderen Stufen der Imagen 4-Serie

hiapi hostet drei Imagen 4-Stufen auf exakt derselben Task-API; nur die model-ID unterscheidet sich, daher funktioniert der obige Request-Body über alle Stufen hinweg:

• imagen-4.0-fast – die Geschwindigkeitsstufe (Modellseite) und die kostengünstigste Option der Serie. Geeignet für Prompt-Iteration, Konzepterkundung und breite Richtungssuche, also viele Kandidaten generieren und einige wenige behalten.
• imagen-4.0 – die Standardstufe Imagen 4.
• imagen-4.0-ultra – die Stufe mit höchstem Detailgrad für lieferfähige Endergebnisse.

Ein praktischer Workflow: Prototypisiere auf Fast und tausche dann den model-String gegen imagen-4.0-ultra für das finale Rendering, ohne weiteren Code zu ändern. Vergleiche die aktuellen Preise pro Bild auf der Preisseite.

Hinweise für die Produktion

• Polling vs. Webhook. Die obige Schleife ist Polling. In der Produktion unterstützt die Task-API von hiapi auch Webhooks: Füge ein Top-Level-callback-Objekt hinzu (auf derselben Ebene wie model/input) mit url und when: "final", und hiapi sendet die Task-Details per POST, sobald der Task einen Endzustand erreicht. Lies vor der Nutzung die Dokumentation zur asynchronen API zu Zustellungs- und Wiederholungsregeln.
• Bei Netzwerkproblemen nicht neu übermitteln. Jede Task-Erstellung liefert eine neue taskId – es gibt keine Deduplizierung von Prompts. Wenn eine Polling-Anfrage kurzzeitig fehlschlägt, polle die bereits gespeicherte taskId erneut; ein erneutes POST ist nur nötig, wenn du nie eine taskId erhalten hast.
• Ausgabe-URLs laufen ab. output[].url liegt auf temp.hiapi.ai, und das expireAt liegt etwa 7 Tage in der Zukunft (das obige Beispiel läuft am 2026-10-28 ab). Lade die Bytes sofort in deinen eigenen Speicher herunter; kein Hotlinking.

Verwandte Inhalte

• Imagen 4 Fast Modellseite
• Imagen 4 Ultra – Stufe mit höchstem Detailgrad, gleiche Request-Struktur
• Imagen 4 (Basisversion)
• Dokumentation zur einheitlichen asynchronen Task-API
• Preise

Häufige Fragen

Braucht Imagen 4 Fast einen anderen Endpoint oder ein SDK? Nein. Es ist einfach POST /v1/tasks mit "model": "imagen-4.0-fast" – derselbe Endpoint, den alle Bild- und Videomodelle von hiapi verwenden. Wechsle die Stufe, indem du die Modell-ID änderst.

Warum gibt meine Anfrage 400 zurück mit „missing required field aspect_ratio“? Fast hat kein Standard-Seitenverhältnis (anders als die Basis- und Ultra-Stufe). Sende immer aspect_ratio aus dem Enum 1:1 | 16:9 | 9:16 | 3:4 | 4:3 | auto.

Kann ich Auflösung oder Bildgröße festlegen? Nein – das Modell hat kein resolution- oder size-Feld; die Ausgabegröße folgt aspect_ratio. Wenn du resolution sendest, wird additional properties 'resolution' not allowed zurückgegeben.

Ist seed ein String oder eine Zahl? Eine Zahl. "seed": 7 funktioniert; "seed": "7" liefert seed: got string, want integer.

Wie lange ist die Ausgabe-URL gültig? Etwa 7 Tage (expireAt). Lade sie sofort herunter und speichere sie.