Zum Hauptinhalt springen

Ü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.
model
string
erforderlich
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.
prompt
string
erforderlich
Textbeschreibung des gewünschten Bildes.
image_url
string
Ö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.
image_urls
string[]
Ö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.
reference_image_urls
string[]
Zusätzliche modellspezifische Referenzbild-URLs für Anbieter, die primäre Eingabebilder von Referenzen unterscheiden.
image
file
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.
n
integer
Standard:"1"
Anzahl der zu generierenden Bilder (1-10, modellabhängig).
size
string
Standard:"1024x1024"
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.
aspect_ratio
string
Modellabhängiger Seitenverhältnis-Selektor.Häufige Werte für Google-Bildfamilien sind 1:1, 16:9, 9:16, 3:2 und 2:3.
resolution
string
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.
quality
string
Standard:"standard"
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.
response_format
string
Standard:"url"
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.
async
boolean
Standard:"false"
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.
style
string
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.
user
string
Eine eindeutige Kennung für den Endbenutzer.

Antwort

Inline-Antwort

created
integer
Unix-Zeitstempel der Erstellung.
data
array
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.
created
integer
Unix-Zeitstempel der Erstellung.
task_id
string
Eindeutige Aufgaben-ID zum Abfragen.
status
string
Anfänglicher Status: pending.
poll_url
string
Relative URL zum Abfragen der Ergebnisse, zum Beispiel /v1/tasks/{id}.
data
array
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.
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
  }'
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)
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
$ch = curl_init('https://api.tokenlab.sh/v1/images/generations');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => 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:
{
  "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:
{
  "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:
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"
{
  "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..."
    }
  ]
}
{
  "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.
ModellTypMerkmale
gpt-image-2Inline oder task-basiertGPT-Image-Modell mit Token-Preis und flexiblen Größen
flux-proOft task-basiertFotorealistisch, hohe Qualität
qwen-image-plusOft task-basiertStarke Textdarstellung und Prompt-Befolgung
nano-banana-proOft task-basiertReferenzbild-Workflows und Ausgabe mit hoher Auflösung
grok-imagine-imageOft task-basiertxAI-Bildgenerierung mit Seitenverhältnis- und Auflösungsauswahl
ideogram-v3Oft task-basiertStarke 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:
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}")