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

Imagen 4 Ultra ist die Version mit der höchsten Detailstufe in der Google Imagen 4-Serie. Auf hiapi wird es wie alle anderen Bildmodelle über dieselbe einheitliche asynchrone Task-API für Text-zu-Bild ausgeführt. Dieser Leitfaden zeigt eine wirklich lauffähige Anfrage – einen echten curl-Aufruf, eine Python-Polling-Schleife, die Parameter, die der Server tatsächlich akzeptiert, und Fehlerfälle, die durch echte Anfragen verifiziert wurden. Alles im Folgenden wurde vor der Veröffentlichung auf dem Produktionsendpunkt ausgeführt und verifiziert; die Beispiel-taskId und Ausgabe-URLs stammen aus diesem Lauf.

Was du baust

Ein einzelner Aufruf verwandelt einen Text-Prompt in ein fertiges Bild: Sende die Aufgabe per POST /v1/tasks, polle bis zum Abschluss und lies dann die Bild-URL aus output[0].url. Du benötigst einen hiapi API-Key – hole ihn aus deinem Dashboard und exportiere ihn:

export HIAPI_API_KEY="your-hiapi-key"

Minimales lauffähiges Beispiel (curl)

Das Modell akzeptiert prompt und optional aspect_ratio. Aufgabe erstellen:

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": "Makro-Produktfoto einer matten Keramik-Kaffeetasse auf einem hellen Eichentisch, weiches Fensterlicht von links, geringe Schärfentiefe, ein paar Kaffeebohnen im Vordergrund, kein Text, keine Logos",
      "aspect_ratio": "4:3"
    }
  }'

Der Erstellungsaufruf gibt sofort eine Aufgaben-ID zurück – die Generierung läuft im Hintergrund weiter:

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

Polle die Aufgabe mit der zurückgegebenen ID:

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

Wenn status success ist, befindet sich das Bild unter 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"
}

Dieser Lauf war in etwa 8 Sekunden abgeschlossen und lieferte ein WebP (nicht PNG/JPEG). Die URL liegt im temporären Speicher ("storage": "temp"), expireAt ist auf 7 Tage in der Zukunft gesetzt – lade die Datei rechtzeitig herunter und verlinke sie nicht per Hotlink.

Produktion: Python mit Polling-Schleife

Die Erstellungsantwort enthält kein Bild – nur taskId. Eine echte Integration reicht zuerst ein und pollt dann (oder verwendet einen Callback). Dieses Skript führt den vollständigen Roundtrip aus und lädt das Ergebnis sofort herunter, da die URL temporär ist:

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

Wichtige Hinweise für die Produktion:

• Polling vs. Callback. Oben wird Polling gezeigt. Um Polling zu vermeiden, kannst du ein Objekt callback auf oberster Ebene anhängen ({"url": "...", "when": "final"}); hiapi sendet dir dann eine POST-Anfrage, sobald die Aufgabe einen Endzustand erreicht. Den Callback-Vertrag findest du in der Dokumentation zur einheitlichen asynchronen API.
• Eine gespeicherte ID erneut pollen, nicht neu erstellen. Das Lesen einer Aufgabe ist idempotent; bei Verbindungsabbrüchen sollte GET /v1/tasks/<id> wiederholt werden, niemals ein erneutes POST (das würde ein weiteres Bild in Rechnung stellen).
• Bei Erfolg sofort herunterladen. output[0].url ist temporär (in diesem Lauf beträgt die TTL 7 Tage). Lade die Bytes herunter und übertrage sie in deinen eigenen Speicher.

Parameter, die dieses Modell tatsächlich akzeptiert

imagen-4.0-ultra unterstützt nur Text-zu-Bild – Referenzbilder werden nicht unterstützt (auf der Modellseite bestätigt; in diesem Lauf wurde nur Text-zu-Bild getestet). Das Eingabe-Schema ist geschlossen: Unbekannte Felder werden abgelehnt, sodass keine zusätzlichen Parameter untergeschoben werden können.

Feld	Typ	Erforderlich	Beschreibung
prompt	string	Ja	1–5.000 Zeichen. Ein leerer String schlägt fehl (minLength: got 0, want 1).
aspect_ratio	enum	Nein	Einer von 1:1, 16:9, 9:16, 3:4, 4:3, auto. Standard ist 1:1.
negative_prompt	string	Nein	Maximal 5.000 Zeichen; beschreibt, was ausgeschlossen werden soll.
seed	string	Nein	Maximal 500 Zeichen. Es ist ein String – eine Zahl wird abgelehnt.

Eine Anfrage erzeugt genau ein Bild.

Verifizierte Fehlerfälle

Diese sind auf dem echten Endpunkt entstanden, sodass sich deine Fehlerbehandlung darauf verlassen kann. Abgelehnte Anfragen geben HTTP 400 mit einem flachen Envelope und ohne taskId zurück:

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

Einige Verhaltensweisen, die du im Code berücksichtigen solltest:

• Der Validator meldet alle Feldfehler auf einmal, verbunden mit ; . Wenn du seed eine Zahl gibst und aspect_ratio ungültig ist, erhältst du beides in einer Meldung: invalid input: seed: got number, want string; aspect_ratio: value must be one of .... Gehe nicht davon aus, dass jede Antwort nur einen Fehler enthält.
• Unbekannte Felder lassen die gesamte Anfrage fehlschlagen mit dem Fehler <root>: additional properties '<name>' not allowed. Das Schema ist geschlossen.
• Ein leerer Prompt schlägt fehl mit prompt: minLength: got 0, want 1.
• Ein erfolgreiches create hat code: 200 und enthält data.taskId; bei Ablehnung ist data: null. Verzweige entsprechend, bevor du versuchst, die Aufgaben-ID zu lesen.

Welche Imagen 4-Stufe sollte man aufrufen?

imagen-4.0-ultra ist die höchste der drei Stufen; wähle nach Aufgabe, nicht nach Gewohnheit (Seitenverhältnis, Negativ-Prompt und Seed beeinflussen nicht, was du bezahlst – siehe Preise):

• Imagen 4 Fast – am günstigsten, geeignet für Entwurfsserien und schnelles Ausloten von Richtungen im Batch.
• Imagen 4 – die mittlere Stufe für den Alltag, geeignet für Produkt-, Lifestyle- und Content-Bilder.
• Imagen 4 Ultra (dieses Modell) – die teuerste der drei, positioniert für Detailtreue auf Endproduktniveau: Makro-Texturen, Material-Rendering und Typografie, für Szenarien, in denen das finale Bild einer genauen Prüfung standhalten muss. Wähle Ultra, wenn die Ausgabe direkt ausgeliefert werden soll; für Iterationen nutze Fast oder die Basisstufe.

Relevante Links

• Imagen 4 Ultra Modellseite – Live-Schema, Beispiele und Preise.
• Dokumentation zur einheitlichen asynchronen API – Aufgaben erstellen/auflisten/abrufen sowie der Callback-Vertrag.
• Schnellstart – Authentifizierung und erster Task in wenigen Minuten.
• Preise – Kosten pro Bild für die einzelnen Imagen 4-Stufen.

Häufig gestellte Fragen

Wie viele Bilder liefert eine Anfrage? Eines. Im verifizierten Lauf enthielt das output-Array nur einen Eintrag.

In welchem Format erfolgt die Ausgabe? WebP. Die zurückgegebene Datei ist eine .webp auf temp.hiapi.ai.

Wie lange ist die Ausgabe-URL gültig? Etwa 7 Tage – expireAt ist auf 7 Tage nach Abschluss gesetzt. Behandle sie als temporäre Ressource und lade sie sofort herunter.

Kann ich Referenzbilder senden? Nein. imagen-4.0-ultra unterstützt nur Text-zu-Bild; die Modellseite listet Referenzbilder als nicht unterstützt.

Warum meldet meine Anfrage "additional properties not allowed"? Das Eingabe-Schema ist geschlossen. Sende nur prompt, aspect_ratio, negative_prompt und seed; jeder andere Schlüssel lässt die gesamte Anfrage fehlschlagen.

Ändern Negativ-Prompt, Seed oder Seitenverhältnis den Preis? Nein. Die Abrechnung erfolgt pro Bild; diese Parameter beeinflussen die Kosten nicht.