GPT Image 2.5 API: Bilder mit Python generieren und bearbeiten

Sie senden ein POST an https://api.omniakey.com/v1/media/tasks, setzen model auf gpt-image-2.5-flare, fragen die zurückgegebene Task-ID ab und laden assets[0].url herunter, sobald der Status succeeded lautet. Am 29. Oktober 2026 haben wir in 1K, 2K und 1536x1024 generiert und ein Café-Foto bearbeitet, dann jede Datei geöffnet und die echte Pixelgröße ausgelesen: 1024×1024, 2048×2048, 1536×1024 und 1024×682. Die 1K-Generierung dauerte 29.5 s, die 2K-Generierung 45.2 s.

Welche Modell-ID von 2.5 Sie nehmen

Nehmen Sie gpt-image-2.5-flare. Das ist die ID, die wir in jedem Lauf unten aufgerufen haben. Die Modellseite GPT-Image 2.5 Flare (geprüft am 29. Oktober 2026) nennt OpenAI als Anbieter, führt Text zu Bild und Bildbearbeitung auf und trägt den Hinweis „Guide updated 2026-10-27“. Dieselbe Seite nennt eine zweite 2.5-ID, gpt-image-2.5-sunburst.

Flare übernimmt beide Aufgaben. Generieren schickt einen Prompt, Bearbeiten schickt einen Prompt plus ein Quellbild. Die Qualität kennt low, medium und high, und dieselbe Seite schreibt, dass die Stufe den Preis nicht verändert. Jeder Lauf hier nutzte medium. Sunburst, die Stufen low und high, 4K und 3840x2160, Masken und mehrere Referenzbilder haben wir nicht getestet, planen Sie also mit Flare in medium und einem Quellbild, bis Sie den Rest selbst prüfen.

Der Request-Code

Das folgende Skript ist genau das, was wir ausgeführt haben: zwei Hilfsfunktionen, dann ein Generierungsaufruf und ein Bearbeitungsaufruf. Es nutzt nur die Python-Standardbibliothek, liest den Schlüssel aus OMNIAKEY_API_KEY und schreibt jede PNG-Datei in den Ordner, aus dem Sie es starten.

import base64
import json
import os
import time
import urllib.request
import uuid

API = "https://api.omniakey.com/v1/media/tasks"
KEY = os.environ["OMNIAKEY_API_KEY"]
MODEL = "gpt-image-2.5-flare"

def request(method, url, body=None, extra_headers=None):
    headers = {"Authorization": f"Bearer {KEY}", "User-Agent": "omniakey-example/1"}
    data = None
    if body is not None:
        headers["Content-Type"] = "application/json"
        data = json.dumps(body).encode()
    headers.update(extra_headers or {})
    req = urllib.request.Request(url, data=data, headers=headers, method=method)
    with urllib.request.urlopen(req, timeout=120) as resp:
        return json.load(resp)

def run_task(body, out_path):
    task = request("POST", API, body, {"Idempotency-Key": str(uuid.uuid4())})["id"]
    for _ in range(150):
        time.sleep(4)
        state = request("GET", f"{API}/{task}")
        if state["status"] not in ("queued", "processing"):
            break
    if state["status"] != "succeeded":
        raise RuntimeError(state.get("error") or state["status"])
    asset_url = state["assets"][0]["url"]  # signierter Link: etwa eine Stunde gültig, also sofort herunterladen
    req = urllib.request.Request(asset_url, headers={"User-Agent": "omniakey-example/1"})
    with urllib.request.urlopen(req, timeout=120) as resp, open(out_path, "wb") as f:
        f.write(resp.read())
    return task

def generate_image(prompt, out_path, size="1K", quality="medium"):
    body = {
        "model": MODEL,
        "type": "image",
        "operation": "generate",
        "input": {"prompt": prompt},
        "parameters": {"size": size, "quality": quality},
    }
    return run_task(body, out_path)

def edit_image(source_path, prompt, out_path, size="1K", quality="medium"):
    with open(source_path, "rb") as f:
        image = base64.b64encode(f.read()).decode()
    body = {
        "model": MODEL,
        "type": "image",
        "operation": "edit",
        "input": {"prompt": prompt, "image": {"data": image, "mime_type": "image/jpeg"}},
        "parameters": {"size": size, "quality": quality},
    }
    return run_task(body, out_path)

if __name__ == "__main__":
    task = generate_image(
        "A small glass greenhouse on a hillside at sunrise, morning fog in the valley, "
        "soft watercolor style, a wooden bench outside the door, no people, no text.",
        "greenhouse.png",
    )
    print("generate task", task)
    task = edit_image(
        "cafe-base.jpg",
        "Change the red bicycle to matte black. Keep everything else exactly the same: "
        "the table, the cup, the window frame and the daylight. Photorealistic, no text, no logos.",
        "cafe-edited.png",
    )
    print("edit task", task)

Authorization: Bearer <key> gehört in jeden Aufruf, und der Aufruf zum Anlegen braucht zusätzlich einen Idempotency-Key, den das Skript mit einer frischen UUID füllt. Im Body steht type auf "image", operation auf "generate" oder "edit", der Text unter input.prompt und Größe und Qualität unter parameters. Die API akzeptiert auch n, gültig ist nur 1, deshalb lässt das Skript es weg. Ein Anlegen antwortet mit HTTP 202 und einer Task-ID, der Status beginnt bei queued, und die Schleife wartet 4 s zwischen den Abfragen, bis er die beiden Arbeitszustände verlässt.

Eine Bearbeitung legt das JPEG unter input.image als eingebettetes Base64-Objekt samt MIME-Typ ab. Request-Bodys sind einschließlich Base64 auf 1 MiB begrenzt, deshalb schickt das Skript ein 1024-Pixel-JPEG mit etwa 230 KB.

Die getesteten Größen und was zurückkam

Vier Läufe, alle mit Qualität medium, am 29. Oktober 2026. Drei kamen in der angefragten Größe zurück. Die 1K-Bearbeitung nicht, in einem ihrer zwei Läufe.

• 1K, generieren — Pixelgröße aus der Datei: 1024×1024; Datum: 29. Oktober 2026
• 2K, generieren — Pixelgröße aus der Datei: 2048×2048; Datum: 29. Oktober 2026
• 1536x1024, generieren — Pixelgröße aus der Datei: 1536×1024; Datum: 29. Oktober 2026
• 1K, bearbeiten — Pixelgröße aus der Datei: 1024×682; Datum: 29. Oktober 2026

Das Gewächshaus unten ist eine 1K-Generierung mit demselben Request-Body wie im Code oben.

Zwei Dinge sind aus der Liste mitzunehmen. Erstens: Lesen Sie die Größe aus der Datei, die Sie heruntergeladen haben. Die 1K-Bearbeitung fragte ein Quadrat an und kam mit 1024×682 zurück, der Form des gesendeten JPEG mit 1024×683, und ein weiterer Lauf derselben Bearbeitung in 1K kam mit 1024×1024 zurück. Zweitens: Die Größenliste in der Dokumentation der Bild-API (geprüft am 29. Oktober 2026) bietet für dieses Modell auto, 1K, 2K, 4K und 3840x2160 und schreibt, dass Größen außerhalb der Liste vor jeder Abrechnung abgelehnt werden; unser Aufruf mit 1536x1024 am 29. Oktober 2026 wurde nicht abgelehnt und lieferte 1536×1024. Prüfen Sie die echte Datei, bevor Sie ein Layout auf eine Größe bauen.

Eine Bearbeitung behält die Szene und ändert eine Sache

Eine Bearbeitung beantwortet zwei Fragen: Was ändert sich, und was bleibt. Wir haben eine Änderung verlangt und die Dinge benannt, die erhalten bleiben mussten.

Prompt: "Change the red bicycle to matte black. Keep everything else exactly the same: the table, the cup, the window frame and the daylight. Photorealistic, no text, no logos."

Das Fahrrad kam dunkel zurück, und Tisch, Tasse, Pflanze und Fensterrahmen waren weiter im Bild. Die Quelle war ein JPEG mit 1024×683, die Ausgabe maß 1024×682, und der Lauf dauerte 38.0 s. Schreiben Sie die Liste des Bleibenden jedes Mal mit. Zur Struktur von Prompts allgemein geht es im GPT Image 2 Prompt-Guide weiter.

Fehler und Grenzen

Zwei Header entscheiden, bevor ein einziges Pixel entsteht: das Bearer-Token und ein eindeutiger Idempotency-Key. Stimmen die beiden, lässt sich der Rest des Aufrufs einfach wiederholen.

Der Schlüssel darf bis zu 255 Zeichen lang sein, laut der am 29. Oktober 2026 geprüften Dokumentation. Eine Wiederverwendung mit demselben Body ist der sichere erneute Versuch: Sie bekommen den vorhandenen Task und es wird nichts Neues berechnet. Halten Sie den Body einschließlich Base64 unter 1 MiB, verkleinern oder komprimieren Sie die Quelle also vor dem Senden.

Wenn ein Task erfolgreich ist, ist assets[0].url ein signierter Link, der laut Dokumentation etwa eine Stunde gilt. Laden Sie also sofort herunter oder fragen Sie denselben Task erneut ab, um einen frischen Link zu bekommen. Task-Datensätze bleiben 24 Stunden erhalten.

Ein Header hat uns am 29. Oktober 2026 überrascht: Ein POST mit dem Standard-User-Agent von Pythons urllib kam als HTTP 403 mit dem Body "error code: 1010" von Cloudflare zurück. Derselbe POST mit unserem eigenen Header User-Agent: omniakey-example/1 erreichte die API, die auf den leeren Body mit 400 invalid_request antwortete, und es wurde nichts berechnet. Die Dokumentation nennt nur Authorization und Idempotency-Key, setzen Sie also einen User-Agent in Ihrem Client.

GPT Image 2.5 oder GPT Image 2 für die API-Arbeit?

Flare ist die 2.5-ID, die wir getestet haben. GPT Image 2 nutzt die ID gpt-image-2, wie auf seiner Modellseite GPT Image 2 steht. Wenn ein Skript mit dieser ID schon liefert, was Sie brauchen, gibt es keinen Grund zu wechseln.

Für ein Foto, das seine Szene behalten soll, während sich ein Objekt ändert, ist Flare in medium der Bereich, den unsere Läufe vom 29. Oktober 2026 abdecken: drei generierte Größen und die Bearbeitung mit 1024×682. Der Vergleich GPT Image 2.5 gegen GPT Image 2 enthält Größen und Ergebnisse mit demselben Prompt für beide Modelle, sodass Sie mit Zahlen vor sich entscheiden können. Die aktuellen Preise stehen auf der Preisseite.

Häufige Fragen

Welche Modell-ID soll ich nehmen, gpt-image-2.5-flare oder gpt-image-2.5-sunburst?

In jedem Lauf oben kam Flare zum Einsatz, und seine Bearbeitung behielt die Szene, die erhalten bleiben sollte. Die Modellseite führt Sunburst als zweite 2.5-ID: Starten Sie mit Flare und schicken Sie Sunburst erst durch Ihre schwierigste Bearbeitung, bevor Sie wechseln.

Kann ich eine Querformat-Größe wie 1536x1024 anfragen?

Am 29. Oktober 2026 kam eine Generierung mit 1536x1024 als 1536×1024 zurück. Die Größenliste in der Dokumentation der Bild-API enthält diesen Wert für dieses Modell nicht, lesen Sie also die Datei und prüfen Sie die Dokumentation, bevor Sie sich in der Produktion darauf verlassen.

Warum kommt meine Bearbeitung in einer anderen Größe zurück als angefragt?

Dieselbe 1K-Bearbeitung kam in einem Lauf als 1024×682 und in einem anderen als 1024×1024 zurück. Behandeln Sie die angefragte Größe als Wunsch, nicht als Zusage. Öffnen Sie die PNG-Datei und lesen Sie Breite und Höhe aus, bevor Sie sie einsetzen.

Brauche ich einen User-Agent-Header?

Am 29. Oktober 2026 bekam eine Anfrage mit dem Standard-User-Agent von Python HTTP 403 mit dem Cloudflare-Fehler 1010. Dieselbe Anfrage mit unserem eigenen User-Agent-Header erreichte die API, senden Sie also einen mit.

Wie lange gelten die Bild-Links?

Laut Dokumentation gilt der signierte Link etwa eine Stunde. Fragen Sie den Task erneut ab, um einen frischen Link zu bekommen, und laden Sie die Datei herunter, sobald der Task erfolgreich ist.