Zum Hauptinhalt springen
Verwandle einen Text-Prompt mit POST /images/generations in Bilder und komponiere optional die trainierten style-, object-, person- und setting-Modelle deiner Organisation samt einer color palette. Übergib engine, um das Text-to-Image-Modell zu wählen; lass es weg, um die Standard-Engine nano_banana_pro zu nutzen. GET /images/models listet die Engines, die du nutzen kannst, mit ihren Limits und Credits.

​
Engines

Jede Engine akzeptiert num_outputs von 1 bis 4; die Standardwerte sind aspect_ratio 1:1 und resolution 1K. Ein Seitenverhältnis oder eine Auflösung, die die Engine nicht unterstützt, liefert 422, bevor Credits berechnet werden — die Anfrage wird nie umgeformt.
  • Trainierte Modelle und Paletten. style_id, object_ids, person_ids, setting_ids und color_palette_id funktionieren mit nano_banana_pro, nano_banana_2_1 und nano_banana_2. Mit nano_banana, imagen_4, seedream_4 oder flux_1_pro liefern sie 422 (mit param = dem Feld) — sie werden nie verworfen, und die Engine wird nie gewechselt.
  • Andere Endpoints. Diese Liste gilt für POST /images/generations (und das MCP-Tool generate_image). Magic Edit und img2img akzeptieren eigene engine-Werte: Beide akzeptieren nano_banana_pro, nano_banana_2 und nano_banana_2_1, und Magic Edit akzeptiert zusätzlich gemini und kontext.
  • Organisationen, die auf trainierte Modelle beschränkt sind. Manche Organisationen generieren nur mit ihren trainierten Modellen. Für sie liefert GET /images/models eine leere data-Liste mit unavailable_reason: "organization_restricted", jede engine liefert 422, und eine Anfrage muss engine weglassen und mindestens ein trainiertes Modell (style_id, object_ids, person_ids, setting_ids) oder eine color_palette_id übergeben.

​
Asynchrones Muster

Die Generierung ist asynchron. POST /images/generations gibt sofort 202 Accepted mit einer Job-id, einem status und einem estimated_credits-Wert zurück. Frage GET /images/generations/{id} ab, bis status gleich completed ist (oder failed/cancelled), und lies dann die erzeugten Bilder — jedes enthält eine presigned URL, 24 Stunden gültig. Ein Job, dessen outputs alle an der Compliance-Pipeline gescheitert sind, endet failed mit error delivery_blocked_compliance: <codes> (siehe Compliance-Sperren). Übergib eine webhook_url, um statt abzufragen benachrichtigt zu werden (siehe Webhooks).

​
Credits

Jedes Ergebnis (output) kostet 5 Credits bei 1K und skaliert mit der Auflösung (1K ×1, 2K ×2, 4K ×4), multipliziert mit num_outputs — gleich auf jeder Engine. Die Kosten ziehen aus dem Pool deiner Organisation; ein aufgebrauchter Pool liefert 402. Siehe Preise.

Quickstart

Ein vollständiger Zero-to-Image-Walkthrough mit curl, Python und TypeScript.