So verwenden Sie gpt-image-2.5-sunburst/image-to-image über die HiAPI API: curl und Python

Die Image-to-Image-Fähigkeiten dieses Endpunkts

Der Endpunkt gpt-image-2.5-sunburst/image-to-image folgt einer einfachen Konvention: Sie senden ein Referenzbild sowie eine Bearbeitungsanweisung in natürlicher Sprache, und das Modell gibt ein neues Bild zurück, auf das die Anweisung angewendet wurde und das gleichzeitig am Referenzbild verankert bleibt. Anders als bei Text-to-Image – wo alles von Grund auf aus Ihrem Prompt entsteht – dient bei Image-to-Image das Referenzbild als visueller Kontext: Komposition, Motiv, Stil und Farbhinweise werden übernommen, sofern Ihre Anweisung nicht ausdrücklich deren Änderung verlangt.

Dadurch ist dies die richtige Wahl für Szenarien, in denen Sie bereits Ausgangsmaterial besitzen und eine kontrollierte Transformation wünschen, etwa die Umstilisierung von Produktfotos, die Änderung von Licht oder Hintergrund, die Anpassung des Erscheinungsbilds eines Motivs oder die Erzeugung von Varianten eines bestehenden Konzepts. Wenn Sie kein Ausgangsmaterial haben und maximale kreative Freiheit wünschen, wählen Sie Text-to-Image; wenn die Treue zu einem vorhandenen Bild wichtiger ist als Neuheit, wählen Sie Image-to-Image.

Das wichtigste mentale Modell für Entwickler: Das Referenzbild ist eine Eingabebeschränkung, die Bearbeitungsanweisung ist das Delta. Eine gute Anweisung beschreibt, was sich ändern soll, nicht alles, was vorhanden sein soll. „Ersetze den Hintergrund durch einen sauberen Studio-Verlauf und behalte das Motiv und seinen Schatten bei“ funktioniert besser als eine vollständige Szenenbeschreibung, weil das Referenzbild die Szene bereits liefert. Denken Sie daran, während Sie die folgende Beschreibung der Request-Struktur lesen – der Request-Body ist klein, aber die Qualität der Anweisung bestimmt die Qualität der Ausgabe.

Vorbereitung und Request-Struktur

Vor dem ersten Aufruf sollten Sie drei Dinge bereithalten:

• API-Schlüssel, ausgestellt durch Ihr HiAPI-Konto. Bewahren Sie ihn in einer Umgebungsvariable auf, nicht im Quellcode.
• Basis-URL, also die Base-URL der HiAPI API; siehe Ihr Dashboard oder die API-Referenzdokumentation.
• Endpunktpfad: gpt-image-2.5-sunburst/image-to-image.

Jede Anfrage ist ein POST-Request, der einen JSON-Body und den Header Authorization trägt. Konzeptuell besteht der Request-Body aus drei logischen Teilen:

1. Modellauswahl – der Modellbezeichner dieses Endpunkts, damit das Gateway den Aufruf korrekt weiterleitet.
2. Eingabe – das Referenzbild (gehostete URL oder Base64-Datenstring) sowie der Text der Bearbeitungsanweisung.
3. Ausgabesteuerung – alle optionalen Parameter, die in der Endpunktdokumentation aufgeführt sind, etwa Größe oder Anzahl. Verwenden Sie nur Parameter, die in der offiziellen Referenzdokumentation vorkommen; raten Sie keine Namen.

Ein Hinweis zur Disziplin: Da dies ein gehosteter Endpunkt ist, definiert die aktuelle API-Referenzdokumentation, welche Felder tatsächlich akzeptiert werden – leiten Sie dies nicht aus anderen Bild-APIs ab. Senden Sie im Zweifel zuerst einen minimalen gültigen Request-Body (model, image, prompt), vergewissern Sie sich, dass eine 200-Antwort zurückkommt, und fügen Sie optionale Felder dann einzeln hinzu. So lässt sich jeder Fehler einer einzelnen Änderung zuordnen, statt einem auf einmal zusammengebauten Request-Body.

Referenzbild und Bearbeitungsanweisung senden

Für das Referenzbild gibt es zwei unterstützte Bereitstellungswege; die Abwägung hängt vor allem davon ab, wo die Bildbytes liegen.

Gehostete URL

Wenn das Bild bereits öffentlich erreichbar ist, übergeben Sie direkt seine URL. Damit bleibt der Request-Body klein, die Serialisierung schnell, und es ist die einfachste Wahl während der Entwicklung. Die URL muss direkt vom Dienst abrufbar sein – nicht hinter einer Authentifizierung, keine Redirect-Kette und keine HTML-Seite, die zufällig ein Bild enthält.

Base64-Daten

Wenn das Bild lokal liegt oder eine private Ressource ist, kodieren Sie es und senden Sie es inline. Base64 bläht den Request-Body um etwa ein Drittel auf, daher kann bei großen Quellbildern die Größenbeschränkung nahe kommen. Falls Sie sich dem Limit nähern, verkleinern Sie das Bild vor dem Kodieren.

Format- und Größenfallen

• Bleiben Sie bei gängigen Formaten (PNG, JPEG, WebP) und stellen Sie sicher, dass die Dateiendung zu den tatsächlichen Bytes passt.
• Übergroße Bilder sind die häufigste Ursache für abgelehnte Anfragen. Wählen Sie möglichst Quellbilder in vernünftiger Größe; für eine Bearbeitung ist in der Regel kein Material in voller Auflösung nötig.
• Wenn Sie den Base64-String selbst zusammenbauen, fügen Sie das Data-URI-Präfix nur dann hinzu, wenn es in den Beispielen der API-Referenzdokumentation enthalten ist; andernfalls lassen Sie es weg. Das Vermischen dieser beiden Konventionen ist eine häufige Quelle für „invalid image“-Fehler.

Bearbeitungsanweisungen formulieren

Die Qualität der Ausgabe steht und fällt mit der Anweisung. Seien Sie konkret darin, was geändert werden soll, und benennen Sie ausdrücklich, was erhalten bleiben soll. Nennen Sie das Ziel („die Jacke“), die Transformation („neu einfärben in Dunkelmarineblau“) und die Einschränkung („Pose des Models und vorhandene Schatten beibehalten“). Vermeiden Sie es, mehrere unzusammenhängende Bearbeitungen in einer Anweisung zu stapeln – wenn Sie voneinander unabhängige Änderungen benötigen, teilen Sie sie in mehrere Aufrufe auf, dann lässt sich jedes Ergebnis auch leichter bewerten.

Ein ausführbarer curl-Request

Im Folgenden ein vollständig im Terminal ausführbarer Request. Ersetzen Sie Schlüssel und Bildplatzhalter durch Ihre eigenen Werte.

curl -X POST "$HIAPI_BASE_URL/gpt-image-2.5-sunburst/image-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/image-to-image",
    "image": "https://your-cdn.example.com/reference.png",
    "prompt": "Ersetze den Hintergrund durch einen weichen, neutralen Studio-Verlauf; behalte das Motiv, seine Pose und die vorhandenen Schatten unverändert bei."
  }'

Punkt für Punkt erklärt:

• -X POST – dieser Vorgang erzeugt ein neues Bild, daher POST.
• Die URL setzt sich aus Basis-URL und Endpunktpfad zusammen; die Basis-URL in einer Umgebungsvariable zu halten erleichtert den Wechsel zwischen Umgebungen.
• Authorization: Bearer ... – Ihr API-Schlüssel. Exportieren Sie ihn als HIAPI_API_KEY, damit er nicht in der Shell-Historie oder in Logs auftaucht.
• Content-Type: application/json – der Body ist JSON; das Weglassen dieses Headers ist eine häufige Ursache für verwirrende 4xx-Antworten.
• model – der Bezeichner des Endpunkts. Er muss exakt mit der Dokumentation übereinstimmen.
• image – das Referenzbild, hier eine gehostete URL. Für Base64 ersetzen Sie es durch den Datenstring oder eine lokal kodierte Variable.
• prompt – die Bearbeitungsanweisung. Beschreiben Sie nur die Änderung und das, was erhalten bleiben soll.

Wenn Sie mit einer lokalen Datei testen möchten, ohne manuell zu kodieren, lässt sich JSON in den meisten Shells mit einem kleinen Skript oder jq erzeugen; entscheidend ist, dass der endgültige Request-Body gültiges JSON mit diesen Feldern ist.

Derselbe Request in Python

Die Python-Version behält den Request-Body exakt bei, damit sich die Antworten direkt vergleichen lassen. Verwenden Sie requests:

import os
import requests

base_url = os.environ["HIAPI_BASE_URL"]
api_key = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "gpt-image-2.5-sunburst/image-to-image",
    "image": "https://your-cdn.example.com/reference.png",
    "prompt": (
        "Ersetze den Hintergrund durch einen weichen, neutralen Studio-Verlauf; "
        "behalte das Motiv, seine Pose und die vorhandenen Schatten unverändert bei."
    ),
}

response = requests.post(
    f"{base_url}/gpt-image-2.5-sunburst/image-to-image",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)

response.raise_for_status()
print(response.json())

Zwei Dinge sind erwähnenswert. Erstens setzt json=payload den Content-Type und serialisiert den Body für Sie, wodurch eine ganze Klasse von Fehlern beim manuellen Zusammenbauen von JSON entfällt. Zweitens ist timeout=120 bewusst gewählt: Bildgenerierung ist nicht sofort fertig, und ein Client, der ewig wartet, ist schlechter als einer, der sauber fehlschlägt. Passen Sie das Timeout an Ihre Workload an, aber setzen Sie unbedingt eines.

Um eine lokale Datei zu verwenden, lesen Sie deren Bytes, kodieren Sie sie mit Base64 und weisen Sie das Ergebnis image zu. Bei einer gehosteten URL lassen Sie den String unverändert. Sobald curl- und Python-Aufruf dieselbe Struktur zurückgeben, haben Sie bestätigt, dass beide sich gleich verhalten, und können auf jeder der beiden Varianten weiter aufbauen.

Häufige fehlgeschlagene Anfragen beheben

Die meisten Fehler lassen sich in vier Kategorien einordnen. Gehen Sie sie in der folgenden Reihenfolge durch, denn jede kann sich als die nächste tarnen.

Authentifizierungsfehler

401 oder 403 bedeutet fast immer, dass der Schlüssel fehlt, falsch formatiert oder abgelaufen ist. Prüfen Sie, ob der Header exakt Authorization: Bearer <key> lautet, ob keine überflüssigen Anführungszeichen oder Zeilenumbrüche durch Copy-Paste hineingeraten sind, und ob die Umgebungsvariable tatsächlich in der Shell oder im Prozess gesetzt ist, der den Request ausführt. Ein Schlüssel, der in curl funktioniert, in Python aber nicht, deutet meist auf eine nicht gesetzte Variable hin, nicht auf einen kaputten Schlüssel.

Fehlerhaft formatierter Request-Body

Ein 400 mit Validierungsinformationen bedeutet in der Regel, dass das JSON ungültig ist oder Pflichtfelder fehlen. Geben Sie den Request-Body vor dem Senden formatiert aus, prüfen Sie, ob model mit dem Endpunktbezeichner übereinstimmt, und ob der Feldname der Bearbeitungsanweisung mit der Dokumentation übereinstimmt. Beim manuellen Schreiben von JSON in curl sind nachgestellte Kommas und einfache Anführungszeichen die klassischen Übeltäter; Pythons json= vermeidet diese Probleme.

Ungültige oder zu große Bild-Eingabe

Wenn der Dienst das Bild ablehnt, prüfen Sie drei Dinge: Die URL ist öffentlich abrufbar und liefert tatsächlich ein Bild (keine Weiterleitung und keine Fehlerseite), das Format wird unterstützt, und der Request-Body überschreitet die in der Dokumentation angegebene Größenbeschränkung nicht. Bei Base64-Eingaben stellen Sie sicher, dass die Kodierung sauber ist und die Data-URI-Präfix-Konvention mit dem Referenzbeispiel übereinstimmt. Im Zweifel verkleinern Sie das Bild und versuchen es erneut – ein kleineres Quellbild behebt einen erheblichen Teil dieser Fehler.

Timeouts und vorübergehende Störungen

Lang laufende Generierungen können das Client-Timeout überschreiten, und 429- oder 5xx-Antworten zeigen an, dass ein Rate-Limit ausgelöst wurde oder ein vorübergehendes Serverproblem vorliegt. Unterscheiden Sie diese von Client-Fehlern: Ein 400 sollte nicht unverändert wiederholt werden, aber 429 oder 503 eignen sich für einen Retry mit Backoff. Protokollieren Sie für jeden Fehlschlag Statuscode und Response-Body – aussagekräftige Fehlerlogs machen aus Rätselraten eine Punkt-für-Punkt-Prüfung.

Vom Skript zum wiederverwendbaren Client

Ein einmaliges Skript beweist, dass der Endpunkt funktioniert; ein kleiner Wrapper lässt ihn stabil in einer Pipeline laufen. Kapseln Sie den Aufruf in eine Funktion, die drei Dinge übernimmt: die Anfrage, das Timeout und eine begrenzte Retry-Strategie.

import os
import time
import requests

class ImageEditClient:
    def __init__(self, base_url: str, api_key: str, timeout: int = 120):
        self.base_url = base_url.rstrip("/")
        self.api_key = api_key
        self.timeout = timeout

    def edit(self, image: str, prompt: str, retries: int = 3):
        url = f"{self.base_url}/gpt-image-2.5-sunburst/image-to-image"
        headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json",
        }
        payload = {
            "model": "gpt-image-2.5-sunburst/image-to-image",
            "image": image,
            "prompt": prompt,
        }
        last_error = None
        for attempt in range(retries):
            try:
                resp = requests.post(
                    url, headers=headers, json=payload, timeout=self.timeout
                )
            except requests.Timeout as err:
                last_error = err
                time.sleep(2 ** attempt)
                continue
            if resp.status_code in (429, 500, 502, 503, 504):
                last_error = RuntimeError(f"transient {resp.status_code}: {resp.text}")
                time.sleep(2 ** attempt)
                continue
            if resp.status_code >= 400:
                raise RuntimeError(f"request failed {resp.status_code}: {resp.text}")
            return resp.json()
        raise RuntimeError(f"exhausted retries: {last_error}")

Die Designentscheidungen sind wichtiger als der Code selbst. Retries gelten nur für Timeouts und vorübergehende Statuscodes, niemals für 4xx-Client-Fehler, denn das Wiederholen eines fehlerhaft formatierten Request-Bodys verschwendet nur Quota. Exponentielles Backoff verhindert, dass eine gedrosselte Pipeline den Endpunkt wiederholt unter Druck setzt. Client-Fehler werden sofort mit dem Response-Body geworfen, sodass der Aufrufer genau sieht, was der Dienst beanstandet. Und die Modellbezeichner an einer Stelle zu zentralisieren bedeutet, dass ein künftiger Wechsel zu einem anderen Bild-Endpunkt nur eine Zeile ändert, statt den ganzen Codebestand zu durchsuchen.

Fügen Sie darauf aufbauend strukturiertes Logging für jeden Versuch hinzu und prüfen Sie Größe/Form der Antwort, bevor nachgelagerte Konsumenten sie verwenden. Wenn Sie bereit sind, andere Bildmodelle auf demselben Gateway zu erkunden, ist der HiAPI-Modellkatalog der richtige Ort, um Endpunkte zu vergleichen, ohne den Client neu schreiben zu müssen.