GPT Image 2.5 API mit Python: ein funktionierendes Beispiel

Um die GPT Image 2.5 API aufzurufen, sendest du einen POST an https://api.seedrouter.ai/v1/images/generations mit einer Modell-ID wie gpt-image-2.5-flare und einem Prompt, behältst die id der Aufgabe aus der Antwort und fragst GET /v1/tasks/{id} ab, bis der Status completed ist. Die fertige Aufgabe enthält URLs zu deinen Bildern. Derselbe Endpunkt übernimmt Text-zu-Bild, Bearbeitungen mit Referenzen und Bearbeitungen mit Maske.

Diese Anleitung ist ein vollständiger, lauffähiger Weg in Python, mit dem Gegenstück in JavaScript, gefolgt von den häufigsten Fehlern und was jeder davon bedeutet.

Was brauchst du vor der ersten Anfrage?

Zwei Dinge: einen API-Key und eine Modell-ID.

Erstelle einen Key unter API-Keys und bewahre ihn in einer Umgebungsvariable auf deinem Server auf, niemals in Browser-Code:

export SEEDROUTER_API_KEY="your-key"

Wähle dann eine der vier Modell-IDs von GPT Image 2.5. Kopiere sie exakt; eine nackte ID gpt-image-2.5 gibt es nicht.

Wenn du unsicher bist, mit welchem Modell du anfangen sollst, nimm Flare; Flare vs Sunburst erklärt, wann sich Sunburst lohnt.

Wie erzeugst du ein Bild mit Python?

Das Absenden kehrt sofort zurück. Die Antwort ist ein Verweis auf eine Aufgabe, nicht das Bild.

import os
import requests

response = requests.post(
    "https://api.seedrouter.ai/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
    json={
        "model": "gpt-image-2.5-flare",
        "prompt": "An amber glass bottle on a cream background, studio lighting",
        "size": "1024x1024",
        "quality": "low",
    },
    timeout=60,
)
response.raise_for_status()
task_id = response.json()["id"]

Speichere task_id, bevor du irgendetwas anderes tust. Sie ist dein einziger Zugriff auf die Arbeit, für die du gerade bezahlt hast, und damit machst du weiter, falls dein Prozess neu startet, während das Bild rendert.

Wie bekommst du das Bild zurück?

Frag die Aufgabe alle paar Sekunden ab, bis sie fertig ist. Diese Schleife wartet bis zu zehn Minuten; wird diese Frist erreicht, endet deine Schleife, nicht die Aufgabe.

import time

print(f"Task ID: {task_id}")
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    result = requests.get(
        f"https://api.seedrouter.ai/v1/tasks/{task_id}",
        headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
        timeout=30,
    )
    result.raise_for_status()
    task = result.json()
    if task["status"] == "completed":
        for image in task["output"]["data"]:
            print(image["url"])
        break
    if task["status"] == "failed":
        raise RuntimeError(task["error"]["message"])
    time.sleep(3)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

Lade die URLs, die du behalten willst, herunter und speichere sie selbst. Ergebnis-URLs dienen der Übergabe, nicht der langfristigen Speicherung.

Wie sieht derselbe Aufruf in JavaScript aus?

Die Anfrage ist identisch; nur der HTTP-Client ändert sich. Führe sie auf deinem Server aus, damit der Key nie einen Browser erreicht.

const response = await fetch('https://api.seedrouter.ai/v1/images/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SEEDROUTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-image-2.5-flare',
    prompt: 'An amber glass bottle on a cream background, studio lighting',
    size: '1024x1024',
    quality: 'low',
  }),
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const { id: taskId } = await response.json();

Frag GET https://api.seedrouter.ai/v1/tasks/${taskId} mit demselben Header ab, genau wie in der Python-Schleife.

Wie bearbeitest du ein vorhandenes Bild?

Füge derselben Anfrage Referenzbilder hinzu. Es gibt keinen separaten Bearbeitungs-Endpunkt und kein Modus-Feld: Wer images sendet, macht daraus eine Bearbeitung, und eine zusätzliche mask begrenzt die Änderung auf einen Bereich.

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "Make the bottle blue. Preserve the composition and lighting.",
  "images": [{"image_url": "https://example.com/reference.png"}],
  "mask": {"image_url": "https://example.com/mask.png"}
}

Eingaben müssen öffentliche HTTPS-URLs sein. Du kannst bis zu 16 Referenzbilder als PNG, JPEG oder WebP senden, jeweils unter 50 MB. Die Maske ist ein PNG unter 4 MB, genauso groß wie das erste Referenzbild, und ihr transparenter Bereich markiert, was geändert werden soll. Base64-Strings, data:-URLs und Datei-Uploads werden abgelehnt; lade Dateien also zuerst in deinen eigenen Speicher hoch und sende die URLs.

Warum meldet die API, dass das Modell nicht verfügbar ist?

Fehlercode 20002 mit HTTP 400 („The requested model is not available.“) bedeutet, dass der Wert von model keine ID ist, die die API bedient. Die übliche Ursache ist ein knapper Fehlgriff: gpt-image-2.5 ohne Variante, gpt-image-2-5-flare mit Bindestrich statt Punkt oder ein Tippfehler in sunburst. Kopiere eine ID aus der Tabelle oben.

Parameterfehler werden gemeldet, bevor das Modell geprüft wird. Enthält eine Anfrage zusätzlich ein ungültiges Feld, bekommst du 20001 mit einer Meldung, die das Feld nennt, zum Beispiel quality. Behebe das zuerst; der Modellfehler erscheint beim nächsten Versuch, falls die ID dann immer noch falsch ist.

Eine Aufgabe kann auch fehlschlagen, nachdem sie angenommen wurde. Diese Abfrage liefert trotzdem HTTP 200, mit status: "failed" und einem error-Objekt wie Code 60001 (Inhaltsrichtlinie) oder 60002 (Generierung fehlgeschlagen). Fehlgeschlagene Aufgaben werden nicht berechnet. Der Fehlerkatalog listet jeden Code, einschließlich Guthaben- und Rate-Limit-Fehlern, mit dem jeweils nächsten Schritt.

Häufige Fragen

Gibt es einen offiziellen Python-SDK-Aufruf, der das Bild direkt zurückgibt?

Nicht bei dieser API. Die Auslieferung ist asynchron: Du sendest immer ab, behältst die Aufgaben-ID und fragst ab. stream und partial_images werden nicht unterstützt.

Kann ich mehrere Bilder auf einmal anfordern?

Ja. Setze n auf einen Wert von 1 bis 10. Die fertige Aufgabe listet eine URL pro geliefertem Bild, und berechnet werden die gelieferten Bilder.

Wie bekomme ich ein transparentes PNG?

Setze background auf transparent und output_format auf png. JPEG hat keinen Alphakanal, deshalb wird diese Kombination abgelehnt, bevor sie läuft.

Bau die Integration um die Aufgaben-ID herum

Speichere die Aufgaben-ID in dem Moment, in dem du sie erhältst, frag mit einer Frist ab und behandle ein Timeout beim Abfragen als „läuft noch“, nicht als „fehlgeschlagen“. Alles Weitere, einschließlich jedes Felds und jedes Limits, steht in der API-Referenz zu GPT Image 2.5, und ohne Code kannst du eine Anfrage im Playground ausprobieren.