Wie verwendet man die Imagen 4 API? In 5 Minuten das erste Bild generieren

TL;DR

• Imagen 4（imagen-4.0）ist ein Text-zu-Bild-Modell, ein Bild kostet $0.06: einen Prompt schreiben, Bildformat wählen und das Bild wird generiert – geeignet für Porträtfotografie, Naturnahaufnahmen und Produktstillleben. Auf der Modellseite kann man es online ausprobieren, neue Nutzer erhalten bei der Registrierung 200 Credits.
• Zur selben Serie gehören zwei weitere Stufen: imagen-4.0-fast kostet $0.03 pro Bild für umfangreiche Entwürfe, imagen-4.0-ultra kostet $0.09 pro Bild für finale Details.
• Der Aufruf erfolgt über die HiAPI-/v1/tasks-Schnittstelle: Aufgabe einreichen und taskId erhalten, dann das Ergebnis abfragen und nach Erfolg das Bild von output[0].url herunterladen.

Was es kann

• Direkt aus Text Bilder erzeugen: Es werden keine Referenzbilder akzeptiert, das Bild wird vollständig durch den Prompt beschrieben, aspect_ratio ist Pflichtfeld (sechs Optionen: 1:1, 16:9, 9:16, 3:4, 4:3, auto).
• Drei Ausrichtungen in einer Serie: Fast für Entwürfe, Standard für die tägliche Produktion, Ultra für mehr Detail – die drei Modell-IDs werden im selben Projekt phasenweise eingesetzt.
• Immer genau 1 Bild pro Aufruf: Es gibt keine Parameter für Anzahl, Pixelgröße oder Ausgabeformat, bei erneutem Lauf ändert sich seed.

Hier ein echtes Ergebnis der Standard-Stufe:

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

（Auf Deutsch: Sonnendurchflutetes skandinavisches Wohnzimmer, Leinensofa, Eichenregale und eine Monstera; redaktionelle Innenraumfotografie. Bildformat 16:9.）

imagen-4.0，16:9，1280×720，$0.06。

Mit diesem Prompt generieren →

Wie man die drei Modelle wählt

	imagen-4.0-fast	imagen-4.0（Standard）	imagen-4.0-ultra
Pro Bild	$0.03	$0.06	$0.09
Ausrichtung	Viele Entwürfe, Richtung auswählen	Tägliche Produktion	Finale Details, Materialien und Textlayout
$10 ergibt etwa	333 Bilder	166 Bilder	111 Bilder
Geeignet für	Themenmeetings, Skizzenrunden	Reguläre Bildablieferung	Finalisierung, detailkritische Motive

Budget-Referenz: Nur Standard-Stufe, 1.000 Bilder pro Monat kosten etwa $60.00; je mehr Entwürfe auf Fast verlagert werden, desto niedriger die Rechnung, die Finalisierung bleibt bei Ultra.

Die drei Modelle werden gleich aufgerufen, nur das model-Feld wird geändert; die Parameterstruktur ist identisch, nur der Typ von seed unterscheidet sich (siehe Parametertabelle). Fast und Ultra haben jeweils ein englisches Integrations-Tutorial: Imagen 4 Fast API guide、Imagen 4 Ultra API guide. Zur Auswahl von Prompts nach Szenario siehe Prompt-Sammlung; die vollständige Preistabelle und das Monatsbudget der drei Stufen finden sich auf der Preisseite, der Vergleich mit zwei identischen Prompt-Gruppen von Nano Banana 2.1 auf der Vergleichsseite.

Zwei Einstiegswege

Browser in 3 Schritten: Modellseite öffnen → Prompt einfügen, Bildformat wählen → Generieren klicken, Standard-Stufe $0.06 pro Bild. Beim ersten Mal empfiehlt es sich, zunächst im Browser ein Bild zu generieren, den Bildstil zu bestätigen und dann mit dem Code zu beginnen.

API in 3 Schritten: POST /v1/tasks einreichen → taskId erhalten → mit GET /v1/tasks/<taskId> abfragen, nach success herunterladen.

curl: Das erste Bild

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

Zum Wechseln der Stufe nur model ändern: imagen-4.0-fast oder imagen-4.0-ultra. Die taskId in der Antwort dient als Abfragebeleg.

Python: Einreichen, Abfragen, Herunterladen

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

# Einreichen: mit Idempotency-Key, Netzwerk-Retry erstellt keine doppelten Aufgaben
resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

# Abfragen: 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"]   # Temporäre Adresse, sofort herunterladen und speichern
    img = requests.get(image_url, timeout=60)
    with open("output_image", "wb") as f:  # Dateiendung nach dem tatsächlich zurückgegebenen Format benennen
        f.write(img.content)
    print("saved")

Parametertabelle

Feld	Pflicht	Werte	Beschreibung
prompt	Ja	1–5000 Zeichen	Beschreibung des Bildinhalts
aspect_ratio	Ja	1:1 / 16:9 / 9:16 / 3:4 / 4:3 / auto	Ausgabebildformat, Pflichtfeld
negative_prompt	Nein	≤5000 Zeichen	Inhalte, die nicht erscheinen sollen
seed	Nein	Standard und Ultra: String（≤500 Zeichen）；Fast: Integer	Gleiche Parameter und gleicher Seed reproduzieren das Bild

Die drei Modelle nutzen dieselbe Parametertabelle. Felder außerhalb der Tabelle im Request-Body führen direkt zu 400.

Fehler, die dir begegnen werden

Statuscode	Bedeutung	Vorgehen
400 INVALID_REQUEST	Request-Body ungültig (fehlendes prompt oder aspect_ratio, falscher Enum-Wert, Feld außerhalb der Tabelle übergeben)	Request-Body gemäß Parametertabelle anpassen
402 INSUFFICIENT_QUOTA	Guthaben unzureichend (keine Abbuchung)	Nach Aufladen erneut versuchen
429 RATE_LIMITED	Rate-Limit ausgelöst	Einreichungsrate reduzieren
409 / 422 IDEMPOTENCY_KEY_*	Doppelte Einreichung mit demselben Idempotenzschlüssel (in Bearbeitung / Parameter inkonsistent)	Neuen Idempotency-Key verwenden
415 UNSUPPORTED_MEDIA_TYPE	Anfrageformat falsch	Content-Type: application/json prüfen

Wenn eine Aufgabe im Endzustand fehlschlägt, gibt es als Fehlercodes noch CONTENT_POLICY_VIOLATION, TASK_FAILED, TASK_TIMEOUT usw.; bei Fehlschlag wird nichts berechnet, vorab reservierte Credits werden vollständig erstattet.

Vor dem Livegang beachten

• Callback: Auf oberster Ebene des Request-Bodys "callback": {"url": "https://..."} übergeben, im Endzustand wird dein Dienst benachrichtigt, was das Polling erspart.
• Rechtzeitig sichern: output[0].url ist eine temporäre Adresse, sofort herunterladen und im eigenen Speicher ablegen.
• Bildformat explizit angeben: aspect_ratio ist ein Pflichtfeld, nicht auf Standardwerte verlassen; für vertikale Social-Media-Inhalte 9:16 wählen.
• seed-Typ je nach Modell: Fast erhält Integer, Standard und Ultra Strings.

Häufige Fragen

Sind die drei Modelle gleich aufzurufen?

Ja, nur das model-Feld ändern, anderer Code bleibt unverändert.

Kann man Pixelgröße oder Ausgabeformat angeben?

Nein. Es gibt keine Parameter für Pixelgröße und Format, das Ausgabebildformat wird durch aspect_ratio bestimmt, jeweils 1 Bild.

Wird bei Fehlschlag berechnet?

Nein. Vorab reservierte Credits werden nach dem Fehlschlag-Endzustand vollständig erstattet.

Ist Text im Bild zuverlässig?

Muss vergrößert geprüft werden. Bei Plakatmotiven fehlt gelegentlich ein Buchstabe oder ein Strich, vor der Veröffentlichung den Textbereich vergrößern und prüfen.

Können Bilder der drei Stufen in einem Projekt gemischt werden?

Ja. Prompt- und Bildformat-Logik ist universell.

Nächster Schritt: Den obigen Wohnzimmer-Prompt kopieren und auf der Modellseite ein Bild testen, dann nach Szenario Vorlagen aus der Prompt-Sammlung für die Batch-Generierung auswählen.