> ## Documentation Index > Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt > Use this file to discover all available pages before exploring further. # Bild erstellen > Erstellt ein Bild anhand eines Prompts ## Übersicht Für Coding-Agenten zuerst die aktuelle empfohlene Bild-Shortlist mit `GET /v1/models?recommended_for=image` ermitteln und dann das ausgewählte `model` explizit an diesen Endpunkt senden. `gpt-image-2` ist ein GPT-Image-Modell mit tokenbasierter Abrechnung. TokenLab rechnet nach der offiziellen OpenAI-Usage-Aufschlüsselung für Texteingabe, Bildeingabe, gemeldete Cache-Eingabe und Bildausgabe-Token ab; es wird nicht als Festpreis-pro-Bild-Modell behandelt. Für die Bilderzeugung mit `gpt-image-2` unterstützt der öffentliche Vertrag `prompt`, `n`, `size`, `quality`, `response_format`, `async`, `background`, `output_format`, `output_compression` oder `compression`, `moderation` und `user`. Wenn `size` oder `quality` fehlt, verwendet TokenLab `auto`; eigene `size`-Werte müssen dem unten beschriebenen flexiblen `WIDTHxHEIGHT`-Vertrag entsprechen. `input_fidelity` gehört nicht zum aktuellen öffentlichen TokenLab-Vertrag für `gpt-image-2`; lassen Sie es weg, sonst gibt die Anfrage `400 unsupported_parameter` zurück. ### Hinweise zum Modellverhalten Google-Gemini-Bildfamilien verwenden keinen gemeinsamen Auswahlvertrag: * `gemini-3.1-flash-image`, `gemini-3-pro-image` und `nano-banana-pro` unterstützen `aspect_ratio` sowie `resolution` (`1k`, `2k`, `4k`) für ihre öffentlichen Text-zu-Bild- und Image-Edit/Image-to-Image-Operationen. * `nano-banana-2` unterstützt im aktuellen TokenLab-Vertrag `aspect_ratio` sowie `resolution` (`1k`, `2k`, `4k`) nur für Text-zu-Bild-Generierung. * `gemini-2.5-flash-image`, `nano-banana` und `nano-banana-edit` unterstützen `aspect_ratio`, bieten aber keine öffentliche Auswahl von `resolution`. * Verwenden Sie für Nano-Banana-Referenzbild-Anfragen `nano-banana-edit` oder `nano-banana-pro` auf diesem Endpunkt (`/v1/images/generations`) mit `operation: "image-to-image"` und `image_urls`. Senden Sie Nano-Banana-Referenzbild-Anfragen nicht an `/v1/images/edits`. * Bei Nano-Banana-Image-to-Image-Anfragen darf `nano-banana-pro` `resolution` (`1k`, `2k`, `4k`) enthalten; `nano-banana-edit` muss es weglassen. `nano-banana` und `nano-banana-2` sind im aktuellen Modelldetails Text-zu-Bild-Modelle. * Referenzbilder können an diesem Endpunkt als JSON `image_url` / `image_urls` oder als multipart-`image`-Datei übergeben werden. `/v1/images/generations` akzeptiert weder `images[]` noch `file_id`; `/v1/files`-Referenzen gelten nur für `/v1/images/edits`-Modelle, die `images[].file_id` ausdrücklich dokumentieren. Bei Google-Bildfamilien bevorzugen Sie `aspect_ratio` und senden Sie `resolution` nur, wenn das Modell es ausdrücklich unterstützt. xAI-Grok-Imagine-Bildmodelle (`grok-imagine-image`, `grok-imagine-image-quality` und das legacy `grok-imagine-image-pro`) unterstützen `aspect_ratio` sowie `resolution` (`1k`, `2k`). `grok-imagine-image-pro` bleibt als Kompatibilitäts-ID für `grok-imagine-image-quality` erhalten. ## Anfragekörper **Timeout für synchrone Anfragen:** Einige Bildanfragen geben das endgültige Bild inline zurück und warten dafür, bis die Generierung abgeschlossen ist. Hochauflösende oder hochwertige Anfragen können fast eine Minute oder länger dauern; setzen Sie das Timeout Ihres HTTP-Clients daher auf mindestens `120s`. Wenn die Create-Antwort `status: "pending"`, `task_id` oder `poll_url` enthält, folgen Sie stattdessen der zurückgegebenen `poll_url`. Zu verwendendes Modell (z. B. `gpt-image-2`, `flux-pro`, `qwen-image-plus` oder `nano-banana-pro`). Die aktuelle Empfehlungsliste erhalten Sie mit `GET /v1/models?recommended_for=image`. Textbeschreibung des gewünschten Bildes. Öffentliche HTTPS-Referenzbild-URL für Image-to-Image-Generierung. Setzen Sie bei Nano-Banana-Referenzbild-Anfragen `operation` auf `image-to-image`; `nano-banana-pro` darf `resolution` enthalten, während `nano-banana-edit` es weglassen sollte. Öffentliche HTTPS-Referenzbild-URLs. Verwenden Sie dieses Feld für ein oder mehrere Referenzbilder in JSON-Anfragen. `file_id` und `images[]` werden an diesem Endpunkt nicht unterstützt. Zusätzliche modellspezifische Referenzbild-URLs für Anbieter, die primäre Eingabebilder von Referenzen unterscheiden. Multipart-Referenzbilddatei für Image-to-Image-Generierung. Verwenden Sie dies, wenn das Quellbild privat ist oder Header-Authentifizierung benötigt. Dies ist keine /v1/files-`file_id`; dieser Endpunkt akzeptiert keine `file_id`. Anzahl der zu generierenden Bilder (1-10, modellabhängig). Bildgröße. Verwenden Sie dieses Feld für OpenAI-ähnliche Bildfamilien und andere Modelle, die exakte Pixelgrößen akzeptieren. Für `gpt-image-2` akzeptiert `size` `auto` oder `WIDTHxHEIGHT`. Benutzerdefinierte Abmessungen müssen auf beiden Seiten Vielfache von 16 sein, die längste Kante darf höchstens `3840px` betragen, das Verhältnis lange/kurze Kante höchstens `3:1`, und die Gesamtpixelzahl muss zwischen `655,360` und `8,294,400` liegen. `aspect_ratio` und `resolution` gehören derzeit nicht zum öffentlichen TokenLab-Vertrag für `gpt-image-2`. Für Google-Gemini-Bildfamilien wird `size` als Kompatibilitätsalias behandelt und auf den öffentlichen `aspect_ratio`-Vertrag des Modells sowie, falls unterstützt, auf `resolution` abgebildet. Für diese Modelle sollten Sie vorzugsweise `aspect_ratio` direkt senden. Modellabhängiger Seitenverhältnis-Selektor. Häufige Werte für Google-Bildfamilien sind `1:1`, `16:9`, `9:16`, `3:2` und `2:3`. Modellabhängiger Auflösungs-Selektor. Unterstützt auf `gemini-3.1-flash-image` und `gemini-3-pro-image` für Text-zu-Bild und Image-Edit, auf `nano-banana-pro` für Text-zu-Bild und Image-to-Image sowie auf `nano-banana-2` nur für Text-zu-Bild. Typische Werte sind `1k`, `2k` und `4k`. Senden Sie diesen Parameter nicht an reine Aspect-Ratio-Gemini-Bildfamilien, außer das Modell dokumentiert ihn ausdrücklich. Für xAI-Grok-Imagine-Bildmodelle verwenden Sie `1k` oder `2k`. Bildqualität. GPT-Image-Modelle wie `gpt-image-2` verwenden `auto`, `low`, `medium` oder `high`. Andere Bildfamilien können anbieterspezifische Werte verwenden; prüfen Sie die Metadaten des ausgewählten Modells, bevor Sie Nicht-Standardwerte senden. Antwortformat: `url` oder `b64_json`. Standard ist `url`. Bei Azure Official- oder Azure-kompatiblen `gpt-image-2`-Anfragen erhält TokenLab Bilddaten als `b64_json`. Bei `url`-Anfragen lädt TokenLab jedes Bild in das CDN hoch und gibt `data[].url` zurück. Wenn der CDN-Speicher nicht verfügbar ist oder der Upload fehlschlägt, schlägt die Anfrage fehl, statt in eine Base64-Antwort umgewandelt zu werden. Bei `b64_json` wird das rohe Base64 zurückgegeben. Auf `true` setzen, um mit `gpt-image-2` oder offiziellen FLUX/BFL-Bildmodellen zuerst eine Aufgabe zu erstellen. Abgeschlossene Async-Bildaufgaben liefern unabhängig vom angeforderten `response_format` URLs; verwenden Sie synchrone Anfragen, wenn Sie `b64_json` benötigen. Optionaler Stil-Selektor. Senden Sie ihn nur, wenn das ausgewählte Modell ihn ausdrücklich dokumentiert; lassen Sie ihn für `gpt-image-2` weg, sofern die Modellmetadaten nichts anderes sagen. Eine eindeutige Kennung für den Endbenutzer. ## Antwort ### Inline-Antwort Unix-Zeitstempel der Erstellung. Array der generierten Bilder. Jedes Objekt enthält: * `url` (string): URL des generierten Bildes * `b64_json` (string): Base64-kodiertes Bild (falls angefordert) * `revised_prompt` (string): Optionale vom Anbieter zurückgegebene Prompt-Überarbeitung, wenn das Upstream-Modell sie meldet ### Antwort für asynchrone Aufgaben Setzen Sie `async: true` mit `gpt-image-2` oder offiziellen FLUX/BFL-Bildmodellen, um eine Aufgabe zu erstellen, statt im Create-Request auf das endgültige Bild zu warten. Die Antwort enthält `status: "pending"`, `task_id` und `poll_url`. Fragen Sie `/v1/tasks/{task_id}` ab, bis die Aufgabe `completed` oder `failed` erreicht. Asynchrone Bildaufgaben liefern nur die endgültigen Bild-URLs. Wenn Sie rohe `b64_json`-Bilddaten benötigen, verwenden Sie eine synchrone Anfrage. Beim Erstellen der Aufgabe kann der geschätzte Betrag reserviert werden. Abgeschlossene Aufgaben werden nach tatsächlicher Nutzung abgerechnet; fehlgeschlagene oder abgelaufene Aufgaben werden freigegeben oder erstattet. Unix-Zeitstempel der Erstellung. Eindeutige Aufgaben-ID zum Abfragen. Anfänglicher Status: `pending`. Relative URL zum Abfragen der Ergebnisse, zum Beispiel `/v1/tasks/{id}`. Leer, solange die Aufgabe aussteht. Abgeschlossene Bildaufgaben geben generierte Bild-URLs in `data[].url` zurück. Wenn du `status: "pending"` erhältst, verwende `poll_url` oder `GET /v1/tasks/{task_id}`, um das Ergebnis abzurufen. ```bash cURL theme={null} curl -X POST "https://api.tokenlab.sh/v1/images/generations" \ -H "Authorization: Bearer sk-your-api-key" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-3-pro-image", "prompt": "A cinematic portrait of a white cat sitting on a rainy windowsill", "aspect_ratio": "16:9", "resolution": "2k", "n": 1 }' ``` ```python Python theme={null} from openai import OpenAI client = OpenAI( api_key="sk-your-api-key", base_url="https://api.tokenlab.sh/v1" ) response = client.images.generate( model="gemini-3-pro-image", prompt="A cinematic portrait of a white cat sitting on a rainy windowsill", aspect_ratio="16:9", resolution="2k", n=1 ) print(response.data[0].url) ``` ```javascript JavaScript theme={null} import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'sk-your-api-key', baseURL: 'https://api.tokenlab.sh/v1' }); const response = await client.images.generate({ model: 'gemini-3-pro-image', prompt: 'A cinematic portrait of a white cat sitting on a rainy windowsill', aspect_ratio: '16:9', resolution: '2k', n: 1 }); console.log(response.data[0].url); ``` ```php PHP theme={null} true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => [ 'Content-Type: application/json', 'Authorization: Bearer sk-your-api-key' ], CURLOPT_POSTFIELDS => json_encode([ 'model' => 'gemini-3-pro-image', 'prompt' => 'A cinematic portrait of a white cat sitting on a rainy windowsill', 'aspect_ratio' => '16:9', 'resolution' => '2k', 'n' => 1 ]) ]); $response = curl_exec($ch); curl_close($ch); $data = json_decode($response, true); echo $data['data'][0]['url']; ``` Beispiel für eine reine Aspect-Ratio-Bildfamilie: Für `gemini-2.5-flash-image`, `nano-banana` oder `nano-banana-edit` senden Sie `aspect_ratio`, aber lassen `resolution` weg: ```json theme={null} { "model": "gemini-2.5-flash-image", "prompt": "A clean editorial product shot of a citrus soda can", "aspect_ratio": "16:9" } ``` Nano-Banana-Pro-Referenzbild-Beispiel: Senden Sie die Anfrage an `/v1/images/generations`, nicht an `/v1/images/edits`. `resolution` ist optional und kann auf `1k`, `2k` oder `4k` gesetzt werden: ```json theme={null} { "model": "nano-banana-pro", "prompt": "Create a clean cinematic character image based on the reference images", "operation": "image-to-image", "image_urls": ["https://example.com/reference-1.png"], "aspect_ratio": "1:1", "resolution": "2k" } ``` Private oder lokale Quellbilder können direkt per multipart hochgeladen werden. Senden Sie keine `file_id` an `/v1/images/generations`: ```bash theme={null} curl -X POST "https://api.tokenlab.sh/v1/images/generations" \ -H "Authorization: Bearer sk-your-api-key" \ -F "model=nano-banana-pro" \ -F "prompt=Create a clean cinematic character image based on this reference" \ -F "operation=image-to-image" \ -F "image=@reference.png" \ -F "aspect_ratio=1:1" \ -F "resolution=2k" ``` ```json Inline Response theme={null} { "created": 1706000000, "data": [ { "url": "https://...", "revised_prompt": "A fluffy white cat with bright eyes sitting peacefully on a wooden windowsill, watching raindrops stream down the glass window..." } ] } ``` ```json Async Task Response theme={null} { "created": 1706000000, "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "status": "pending", "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "data": [] } ``` ## Verfügbare Modelle Dies sind aktuelle Beispielmodelle, kein fester Katalog. Nutzen Sie `GET /v1/models?recommended_for=image` oder die Models-Seite für aktuelle Verfügbarkeit und Preise. | Modell | Typ | Merkmale | | -------------------- | ------------------------ | --------------------------------------------------------------- | | `gpt-image-2` | Inline oder task-basiert | GPT-Image-Modell mit Token-Preis und flexiblen Größen | | `flux-pro` | Oft task-basiert | Fotorealistisch, hohe Qualität | | `qwen-image-plus` | Oft task-basiert | Starke Textdarstellung und Prompt-Befolgung | | `nano-banana-pro` | Oft task-basiert | Referenzbild-Workflows und Ausgabe mit hoher Auflösung | | `grok-imagine-image` | Oft task-basiert | xAI-Bildgenerierung mit Seitenverhältnis- und Auflösungsauswahl | | `ideogram-v3` | Oft task-basiert | Starke Textdarstellung | Behandeln Sie ein Modell nicht statisch als immer synchron oder immer asynchron. Wenn die Create-Antwort `status: "pending"` zurückgibt, folgen Sie `poll_url` und pollen Sie bis zum Abschluss. ## Task-basierte Antworten behandeln Prüfen Sie bei Bildmodellen immer, ob die Antwort `status: "pending"` enthält: ```python theme={null} import requests import time def generate_image(prompt, model="flux-pro"): response = requests.post( "https://api.tokenlab.sh/v1/images/generations", headers={"Authorization": "Bearer sk-your-api-key"}, json={"model": model, "prompt": prompt} ) data = response.json() if data.get("status") == "pending": task_id = data["task_id"] poll_url = data.get("poll_url") print(f"Image task started: {task_id}") while True: status_resp = requests.get( f"https://api.tokenlab.sh{poll_url}" if poll_url else f"https://api.tokenlab.sh/v1/tasks/{task_id}", headers={"Authorization": "Bearer sk-your-api-key"} ) status_data = status_resp.json() if status_data["status"] == "completed": return status_data["data"][0]["url"] if status_data["status"] == "failed": raise Exception(status_data.get("error", "Generation failed")) time.sleep(3) return data["data"][0]["url"] url = generate_image("a beautiful sunset over mountains", model="flux-pro") print(f"Generated image: {url}") ```