Inpainting und Outpainting mit der GPT Image 2 Bildbearbeitungs-API meistern
Zielmodelle:
gpt-image-2,gpt-image-2-official
Inferenz-Endpunkt:https://api.toapis.com/v1/images/generations
Verwandt: GPT Image 2 API-Leitfaden · 4K-Workflows zu Seitenverhältnissen · Globaler Mirror und Proxy · Offizielle Inpainting-Referenz
1. TL;DR und Leistungsüberblick
- Aufgabe: Eine Region eines bestehenden Bildes ersetzen (Inpainting) oder die Leinwand auf ein neues Seitenverhältnis erweitern (Outpainting), ohne eine zweite, undokumentierte API zu erfinden.
- Vertrag: Verwenden Sie Modell-IDs, die im Katalog existieren. Exaktes
gpt-image-2nimmtprompt,sizeals Verhältnis,resolutionals1k/2k/4kund optionalreference_images. Maskenbasiertes Inpainting ist beigpt-image-2-officialmitimage_urlsplusmask_urldokumentiert. - Nicht der aktuelle Vertrag: Eine Modell-ID namens
gpt-image-2-edit, ein synchroner Multipart-POST /v1/images/editsodersize: "1024x1024". Diese Formen stammen aus älteren Entwürfen und sollten nicht in neue Clients kopiert werden. - I/O: Laden Sie Quellbilder und Masken mit
POST /v1/uploads/imageshoch und übergeben Sie dann die zurückgegebene öffentliche URL. Base64 wird inreference_images,image_urlsundmask_urlnicht akzeptiert. - Asynchrones Protokoll: Der Submit-Aufruf gibt eine Task-
idzurück. Fragen SieGET /v1/images/generations/{id}ab, bis der Statuscompletedoderfailedlautet. Ein Client-Timeout ist kein Beweis dafür, dass die Aufgabe fehlgeschlagen ist.
2. Die Stärke programmatischer Bildbearbeitung
Ein Standbild aus einem Text-Prompt zu erzeugen ist nur der erste Schritt. Produktionskataloge, Anzeigen und Designsysteme brauchen häufiger eine gezielte Überarbeitung: ein Produkt austauschen, einen Hintergrund bereinigen oder ein quadratisches Packshot zu einem breiten Hero strecken — bei gleichbleibender Beleuchtung und Motividentität.
Die aktuelle GPT Image 2-Familie bei ToAPIs deckt diese Aufgaben auf einem Pfad ab, POST /v1/images/generations, mit zwei unterschiedlichen Modell-IDs:
| Aufgabe | Modell-ID | Wie Sie auf die Quelle zeigen | Maske? |
|---|---|---|---|
| Promptgeführte Bearbeitung oder Stilübertragung | gpt-image-2 | reference_images (URL-Liste, maximal 14) | Bei dieser ID nicht dokumentiert |
| Pixelgenaues Inpainting | gpt-image-2-official | image_urls (URL-Liste, maximal 16) | mask_url erforderlich, zusammen mit dem ersten Bild |
| Leinwand-Erweiterung (Outpainting) | Beide IDs | Original als Referenz übergeben und size auf das Zielverhältnis ändern | Kein dediziertes Outpaint-Flag |
image_urls ist bei exaktem gpt-image-2 ein rückwärtskompatibler Alias von reference_images und wird vom Gateway normalisiert. Beispiele des offiziellen Kanals in der API-Referenz verwenden image_urls zusammen mit mask_url. Verwenden Sie die Feldnamen aus der Referenz für die ID, die Sie tatsächlich aufrufen.
Eine brauchbare Inpainting-Maske ist ein PNG mit Alpha-Kanal. Ihre Pixelmaße müssen mit dem ersten Referenzbild übereinstimmen. Transparente Pixel (alpha = 0) sind die Regenerierungszone; undurchsichtige Pixel sollten erhalten bleiben. Bauen Sie die Maske in Ihrer Pipeline (zum Beispiel mit Pillow), laden Sie sie hoch und senden Sie nur die URL.
Outpainting ist ein Workflow, kein eigener Endpunkt. Wenn Sie ein 1:1-Packshot haben und ein 16:9-Banner brauchen, behalten Sie das Original als Referenz, setzen Sie size auf 16:9, wählen Sie eine explizite resolution-Stufe und weisen Sie das Modell an, das Motiv zu halten und die Szene zu erweitern. Eine praktische Variante: das Original auf eine größere transparente Leinwand komponieren, diese Leinwand hochladen und als Referenz verwenden — weiterhin auf /v1/images/generations, weiterhin ohne outpaint: true-Flag.

Abbildung 1: Eine Quellleinwand und eine innere Maskenregion passieren das ToAPIs-Gateway; der dokumentierte Pfad bleibt POST /v1/images/generations, mit mask_url ausschließlich für gpt-image-2-official.
size und resolution folgen demselben Vertrag wie bei Text zu Bild: size ist ein Verhältnis wie 1:1 oder 16:9, und resolution ist 1k, 2k oder 4k. Exaktes gpt-image-2 exponiert im aktuellen Playground-Vertrag kein quality-Feld; quality (low / medium / high) erscheint bei gpt-image-2-official. Die dokumentierte Pixeltabelle finden Sie im 4K-Workflow-Leitfaden.
3. Umsetzung in der Produktion: cURL und Python
Die internationalen Beispiele dieser Reihe verwenden https://api.toapis.com. Die offizielle Dokumentation empfiehlt Nutzern in Festlandchina https://toapis.cn. Behalten Sie einen Origin pro Umgebung bei. Pfade, Modell-IDs und der Bearer-Header bleiben gleich.
Schritt 1: Quellbild hochladen (und eine Maske, falls nötig)
curl -X POST "https://api.toapis.com/v1/uploads/images" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-F "file=@./product.png"
Die Antwort enthält data.url. Wiederholen Sie den Aufruf für eine PNG-Maske, wenn Sie gpt-image-2-official aufrufen. Betten Sie kein Base64 in die Generierungsanfrage ein.
Schritt 2: Promptgeführte Bearbeitung bei exaktem gpt-image-2
curl -X POST "https://api.toapis.com/v1/images/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "Keep the ceramic kettle and slate surface. Replace only the background with a calm marble countertop, matching the existing side light. No typography.",
"size": "1:1",
"resolution": "1k",
"n": 1,
"response_format": "url",
"reference_images": ["https://example.com/product.png"]
}'
Schritt 3: Maskiertes Inpainting bei gpt-image-2-official
curl -X POST "https://api.toapis.com/v1/images/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2-official",
"prompt": "Replace the masked region with a desert sunset, preserving the subject outline and lighting",
"size": "1:1",
"resolution": "1k",
"quality": "medium",
"image_urls": ["https://example.com/photo.png"],
"mask_url": "https://example.com/mask.png"
}'
Schritt 4: Python-Helfer zum Senden und Abfragen
Passen Sie die Feldnamen an die API-Referenz der Modell-ID an, die Sie aufrufen. Das Snippet nutzt den dokumentierten Bildstatus-Pfad und die Status completed / failed.
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def upload_image(path: str) -> str:
with open(path, "rb") as handle:
res = requests.post(
f"{BASE}/v1/uploads/images",
headers=HEADERS,
files={"file": handle},
timeout=60,
)
res.raise_for_status()
url = res.json().get("data", {}).get("url")
if not url:
raise RuntimeError(f"Unexpected upload envelope: {res.text}")
return url
def dispatch_edit(payload: dict) -> str:
res = requests.post(
f"{BASE}/v1/images/generations",
headers={**HEADERS, "Content-Type": "application/json"},
json=payload,
timeout=30,
)
res.raise_for_status()
data = res.json()
task_id = data.get("id") or data.get("task_id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_image_task(task_id: str, deadline_s: int = 180) -> str:
poll_url = f"{BASE}/v1/images/generations/{task_id}"
interval = 2.0
start = time.time()
while time.time() - start < deadline_s:
time.sleep(interval)
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
if poll.status_code == 429:
retry_after = poll.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else min(interval * 2, 20))
continue
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status == "completed":
return data["result"]["data"][0]["url"]
if status == "failed":
raise RuntimeError(f"Generation failed: {data.get('error')}")
interval = min(interval * 1.5, 8.0)
raise TimeoutError(
f"Task {task_id} exceeded {deadline_s}s; check status before retrying"
)
if __name__ == "__main__":
source = upload_image("product.png")
# Prompt-guided edit on exact gpt-image-2 (no mask field on this ID).
task_id = dispatch_edit(
{
"model": "gpt-image-2",
"prompt": "Keep the ceramic kettle; extend the scene into a wide 16:9 set with the same side light. No typography.",
"size": "16:9",
"resolution": "1k",
"n": 1,
"response_format": "url",
"reference_images": [source],
}
)
print("Task:", task_id)
print("Image:", poll_image_task(task_id))
Für maskiertes Inpainting laden Sie stattdessen eine passende RGBA-Maske hoch, wechseln model auf gpt-image-2-official und senden image_urls plus mask_url. Speichern Sie Modell-ID, size und resolution zusammen mit dem Task-Datensatz, damit ein späterer SKU-Wechsel eine explizite Entscheidung ist.
4. Fehlerbehandlung und Statusmatrix
Die folgenden Kategorien sind diagnostische Ausgangspunkte, keine Garantie für exakte ToAPIs-Fehlercodes. Ein erfolgreicher HTTP-Submit erfordert trotzdem, dass Sie den Task-status lesen.
| HTTP-Status | Häufige Kategorie | Empfohlene Maßnahme |
|---|---|---|
400 | Ungültiges Feld oder nicht unterstützte Kombination | Bestätigen Sie die Modell-ID, dass size ein dokumentiertes Verhältnis ist, dass resolution 1k / 2k / 4k ist, dass URLs öffentlich sind und dass eine Maske (falls verwendet) bei gpt-image-2-official ein gleich großes PNG mit Alpha-Kanal ist |
401 | Fehlender oder ungültiger API-Schlüssel | Rotieren Sie den Schlüssel im ToAPIs Dashboard und bestätigen Sie den Authorization-Header |
429 | Rate- oder Parallelitätslimit | Beachten Sie Retry-After, wenn vorhanden; verwenden Sie Backoff mit Jitter; wiederholen Sie nur, wenn es sicher ist |
5xx oder Netzwerk-Timeout | Vorübergehendes Gateway- oder Upstream-Problem | Prüfen Sie den Task-Status vor erneutem Senden; verwenden Sie eine begrenzte Retry-Policy |
5. Preise und FinOps-ROI
- Verwenden Sie keine Stückpreise aus Planungsentwürfen wie ein pauschales
$0.024/$0.048-Paar „Standard vs. HD". Diese Zahlen sind relativ zum aktuellen Katalog veraltet, der nach Modell-ID und — beim Standard-GPT-Image-2-Landing-Vergleich — nach Auflösungsstufe bepreist. - Der GPT Image 2 Modell-Leitfaden zeigt derzeit einen ToAPIs-Landing-Vergleich von
$0.015/$0.020/$0.025pro Bild bei1K/2K/4Kfür Standard-gpt-image-2. Behandeln Sie das als veröffentlichten Vergleich, nicht als vertragliche Rechnung. SKUs des offiziellen Kanals und Kontorabatte können abweichen; bestätigen Sie den Satz für die exakte ID, die Sie aufrufen. - Routing (
api.toapis.comversustoapis.cn) ist eine Basis-URL-Wahl, kein dokumentierter Rabatt. FinOps-Gewinne entstehen durch Entwürfe in1k, das Vermeiden doppelter Submits nach einem Client-Timeout und die Wahl der richtigen SKU (gpt-image-2versusgpt-image-2-official) statt der Annahme eines günstigeren „Edit"-Modells. - Als Hintergrund lesen Sie den GPT Image 2 Preisartikel und prüfen dann jede Zahl am Live-Katalog, bevor Sie sie in eine Prognose aufnehmen.
6. Häufig gestellte Fragen
Siehe den FAQ-Block im Frontmatter. Zusammenfassung: Exaktes gpt-image-2 dokumentiert weder mask_url noch /v1/images/edits; maskiertes Inpainting ist bei gpt-image-2-official dokumentiert; Masken müssen gleich große RGBA-PNGs sein, die als URL ausgeliefert werden; Outpainting ist eine Änderung von size plus ein Referenzbild; die Abrechnung muss für die exakte Modell-ID im Konto bestätigt werden.
7. Aktions-Checkliste
- Erstellen Sie einen Schlüssel im ToAPIs Developer Portal.
- Legen Sie eine Basis-URL pro Umgebung fest (
https://api.toapis.comoder, wo erforderlich,https://toapis.cn) und laden Sie ein Quellbild mitPOST /v1/uploads/imageshoch. - Testen Sie eine promptgeführte Bearbeitung auf
gpt-image-2mitreference_images,size: "1:1"undresolution: "1k". - Wenn Sie eine pixelgenaue Maske brauchen, wechseln Sie auf
gpt-image-2-official, laden Sie eine RGBA-Maske passend zum ersten Bild hoch und senden Sieimage_urlsplusmask_url. - Speichern Sie die Task-
id, fragen SieGET /v1/images/generations/{id}mit einer begrenzten Frist ab und beachten SieRetry-Afterbei429. - Als Nächstes: der 4K-Leitfaden zu Seitenverhältnissen, wenn Sie
resolutionerhöhen, und der API-Leitfaden für die umfassendere Parameterliste.







