Blog

Tutorial

So nutzen Sie gpt-image-2.6-sunburst/image-to-image über die HiAPI API: Praxis mit curl und Python

Referenzbild übermitteln, asynchrone Aufgaben abfragen und Anfragen end-to-end debuggen

Nov 10, 2026
Cover-Artwork für ein HiAPI-Tutorial: dünne Papierschichten, die in geringer Tiefe zurückweichen, in Creme, Graphit und einem Blatt aus Terrakotta.
Auf dieser Seite

Wann gpt-image-2.6-sunburst/image-to-image passt

Text-zu-Bild liefert Ihnen das Ergebnis, das das Modell frei aus einem Prompt entwickelt. Bild-zu-Bild geht von Material aus, das Sie bereits haben: Sie übergeben dem Endpoint ein Referenzbild und eine Anweisung, und das Modell erzeugt daraus ein neues Bild, das von dieser Referenz abgeleitet ist. Auf HiAPI ist gpt-image-2.6-sunburst/image-to-image der Endpoint, der speziell für diesen zweiten Modus gedacht ist.

Wählen Sie ihn, wenn das Quellbild selbst Teil der Anforderung ist – etwa um vorhandenes Material stilistisch neu zu gestalten, Licht oder Bildkomposition anzupassen, eine bestimmte visuelle Behandlung auf ein Produktfoto anzuwenden oder kontrollierte Varianten eines Designs zu erzeugen. Das Referenzbild ist der Anker: Es trägt Motiv, Farbpalette und Layout, und Ihr Prompt beschreibt die Transformation, nicht die Szene von Grund auf. Wenn Sie kein Quellmaterial haben und nur anhand einer Beschreibung ein Bild erhalten möchten, ist der Text-zu-Bild-Endpoint einfacher und lässt dem Modell mehr Freiheit.

Zwei praktische Konsequenzen bestimmen alles Weitere. Erstens enthält die Anfrage quasi-binären Input (einen Bildverweis), was beeinflusst, wie Sie den Request-Body aufbauen. Zweitens ist die Bildgenerierung nicht sofort abgeschlossen, weshalb dieser Endpoint als asynchrone Aufgabe läuft und das Bild nicht inline zurückgibt. Planen Sie für zwei Schritte – „einreichen“ und „abholen“ – statt für einen einzigen blockierenden Aufruf.

Voraussetzungen und Einrichtung der Authentifizierung

Bevor Sie die erste Anfrage senden, brauchen Sie drei Dinge: ein HiAPI-Konto, einen API-Schlüssel und eine Möglichkeit, das Referenzbild so zu referenzieren, wie es der Endpoint akzeptiert. Erstellen Sie den Schlüssel in der HiAPI-Konsole und behandeln Sie ihn wie ein Passwort – er autorisiert jeden Aufruf, der Ihrem Konto in Rechnung gestellt wird.

Übergeben Sie den Schlüssel als Bearer-Token im Authorization-Header. Hardcodieren Sie ihn niemals in Quelldateien, Notebooks oder in die Versionsgeschichte. Exportieren Sie ihn zum Testen in der Shell als Umgebungsvariable und lesen Sie ihn im Anwendungscode aus der Umgebung (oder einem Secret-Manager):

export HIAPI_API_KEY="your_api_key_here"

Entscheiden Sie vorab, wie Sie das Referenzbild bereitstellen. In der Regel können Sie das Material an einen temporären Ort hochladen und eine URL übergeben oder das Bild als base64-kodierte Daten im Request-Body senden. Eine URL hält die Anfrage kleiner und leichter protokollierbar; base64 erspart zusätzliches Hosting, bläht aber den Request-Body auf. Behalten Sie in beiden Fällen ein vom Endpoint unterstütztes Dateiformat bei und prüfen Sie die Größenbeschränkungen, bevor Sie senden. Notieren Sie außerdem die Basis-URL der HiAPI API für Ihr Konto – jeder Pfad weiter unten erhält sie als Präfix.

Referenzbild mit curl übermitteln

Beginnen Sie in der Shell, damit Sie genau sehen, was tatsächlich gesendet wird. Die Form des Aufrufs ist ein POST an den Bild-zu-Bild-Endpoint mit einem JSON-Body, der Referenzbild und Anweisung enthält.

curl -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-sunburst/image-to-image",
    "image": "https://your-bucket.example.com/reference.png",
    "prompt": "Repaint this scene in warm sunset tones, keep the composition and objects unchanged",
    "n": 1
  }'

Feld für Feld: model wählt den Endpoint; image enthält das Referenzbild (hier eine URL, andernfalls ein base64-Datenstring, wenn Sie die Datei nicht hosten); prompt ist die Bearbeitungsanweisung, die die Änderung beschreiben sollte, statt das Motiv neu zu beschreiben; n ist die Anzahl der gewünschten Ausgaben. Halten Sie den prompt konkret und begrenzt – Anweisungen, die dem Referenzbild widersprechen, führen leicht zu unbrauchbaren Ergebnissen.

Senden Sie die Anfrage und prüfen Sie den Response-Body. Bei einem asynchronen Endpoint erhalten Sie kein fertiges Bild, sondern eine Aufgabenkennung oder ein Statusobjekt. Speichern Sie diese Antwort, bevor Sie fortfahren – sie ist das Handle für alles Weitere. Mit curl -i prüfen Sie zusätzlich schnell den HTTP-Statuscode – das ist der schnellste Weg, um Authentifizierungsprobleme (4xx beim Einreichen) von Inhaltsproblemen zu unterscheiden.

Denselben Aufruf in Python ausführen

Sobald der Aufruf in der Shell funktioniert, übertragen Sie ihn nach Python. Die Standardbibliothek reicht aus, aber requests macht die Beispiele lesbarer:

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

payload = {
    "model": "gpt-image-2.6-sunburst/image-to-image",
    "image": "https://your-bucket.example.com/reference.png",
    "prompt": "Repaint this scene in warm sunset tones, keep the composition and objects unchanged",
    "n": 1,
}

resp = requests.post(
    f"{BASE_URL}/v1/images/generations",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json=payload,
    timeout=60,
)
resp.raise_for_status()
job = resp.json()
print(job)

Die Unterschiede zu curl sind rein mechanisch: Der Schlüssel kommt aus os.environ, der Request-Body ist ein als JSON serialisiertes dict, und raise_for_status() macht aus einer fehlgeschlagenen Einreichung eine Exception statt eines stillen Fehlers. Die letzte Zeile ist wichtig – der größte Teil des Debugging-Leids entsteht daraus, eine 4xx-Antwort für einen Erfolg zu halten und dann eine Aufgaben-ID abzufragen, die nie existiert hat.

Für binären Input lesen Sie die Datei, kodieren sie als base64 und legen den String statt der URL in image ab. Der Rest des Request-Body bleibt unverändert, sodass Sie die Methode wechseln können, ohne die Anfragelogik anzupassen.

Den Lebenszyklus asynchroner Aufgaben handhaben

Die Bildgenerierung braucht Zeit, daher folgt der Endpoint dem Muster „erst einreichen, dann abfragen“. Verstehen Sie die drei Zustände, und der Rest ist Protokollierungsarbeit.

1. Einreichen und Aufgabe erfassen

Ihr POST gibt eine Aufgabenkennung zurück. Extrahieren Sie sie sofort und persistieren Sie sie irgendwo – eine Datenbankzeile, eine Queue-Nachricht, eine abfragbare Logzeile. Wenn Ihr Prozess zwischen Einreichen und Abfragen abstürzt, ist diese Kennung der einzige Weg, Ihre bereits bezahlte Arbeit wiederzufinden.

2. Abfragen, bis die Aufgabe abgeschlossen ist

Fragen Sie den Status-Endpoint mit der Aufgaben-ID in festem Intervall ab. Beginnen Sie konservativ – einige Sekunden zwischen den Prüfungen – und erhöhen Sie das Intervall bei längeren Aufgaben schrittweise, um die API nicht zu überlasten. Hören Sie in einem Endzustand auf: Erfolg, Fehler oder Ihr eigenes Timeout. Fragen Sie niemals in einer engen Schleife ab.

import time

def wait_for_job(job_id, base_url, api_key, timeout=300, interval=2):
    deadline = time.time() + timeout
    while time.time() < deadline:
        r = requests.get(
            f"{base_url}/v1/images/jobs/{job_id}",
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=30,
        )
        r.raise_for_status()
        data = r.json()
        if data["status"] in ("succeeded", "failed"):
            return data
        time.sleep(interval)
        interval = min(interval * 1.5, 15)
    raise TimeoutError(f"job {job_id} not finished in time")

3. Ergebnis abrufen und speichern

Bei Erfolg verweist die Antwort auf das erzeugte Bild. Falls die URL temporär ist, laden Sie sie zeitnah herunter und schreiben Sie sie unter einem von Ihnen kontrollierten Namen in Ihren eigenen Speicher, damit nachgelagerte Konsumenten nie von temporären Links abhängen. Protokollieren Sie die Aufgaben-ID zusammen mit dem gespeicherten Material – das ist Ihre billigste Debugging-Hilfe.

In der Produktion sollte die Abfrage von einem Hintergrund-Worker gesteuert werden, nicht vom Request-Handler. Eine Web-Anfrage, die die gesamte Bildgenerierungszeit blockiert, ist fragil und bindet Verbindungen unnötig.

Häufige Fehler und wie man sie behebt

Wenn ein Aufruf fehlschlägt, arbeiten Sie diese Liste von oben nach unten ab; der erste Eintrag fängt die meisten Probleme ab.

401 / 403 beim Einreichen

Authentifizierungsproblem. Prüfen Sie, ob der Schlüssel im Authorization-Header vorhanden ist, ob das Bearer-Schema verwendet wird und ob beim Kopieren versehentliche Leerzeichen oder Zeilenumbrüche entstanden sind. Vergewissern Sie sich, dass die Umgebungsvariable in der Shell oder dem Prozess, der die Anfrage ausführt, tatsächlich gesetzt ist.

400 / 422 beim Request-Body

Der Request-Body ist fehlerhaft oder ein Feld ist falsch. Häufige Ursachen: JSON-Syntaxfehler durch manuell zusammengesetzte curl-Strings, ein image-Wert, der weder eine erreichbare URL noch gültiges base64 ist, ein fehlender prompt oder ein nicht unterstütztes Bildformat. Validieren Sie das JSON lokal und bestätigen Sie, dass das Referenzbild tatsächlich im Browser lädt.

404 bei Modell oder Pfad

Pfad oder Modellname sind falsch geschrieben. Die Modellkennung ist ein exakter String – gpt-image-2.6-sunburst/image-to-image unterscheidet sich von der Text-zu-Bild-Variante und ist groß-/kleinschreibungssensitiv.

Timeouts und hängende Abfragen

Unterscheiden Sie langsame von fehlerhaften Aufgaben. Setzen Sie für jeden HTTP-Aufruf ein timeout, definieren Sie Ihre eigene Gesamtfrist und protokollieren Sie beim Aufgeben den zuletzt beobachteten Aufgabenstatus. Wenn Aufgaben regelmäßig Ihre Frist überschreiten, erhöhen Sie sie, statt auf eine enge Retry-Schleife umzusteigen.

Leere oder unbrauchbare Ausgabe

Die Aufgabe war erfolgreich, aber das Bild entspricht nicht Ihren Vorstellungen. Das ist meist ein Prompt-Problem: Die Anweisung ist zu vage oder widerspricht dem Referenzbild. Präzisieren Sie in der Bearbeitungsanweisung, was sich ändern soll und was unverändert bleiben muss.

Produktionsempfehlungen für Bild-zu-Bild-Pipelines

Sobald der Prototyp läuft, geht es um Zuverlässigkeit und Vorhersagbarkeit.

  • Nur wiederholbare Fehler erneut versuchen. Verwenden Sie exponentielles Backoff für fehlgeschlagene Einreichungen durch 5xx- und Netzwerkfehler; wiederholen Sie 4xx nicht blind, denn das schlägt nur erneut fehl. Verfolgen Sie Idempotenz selbst, indem Sie die Aufgabe an Ihre eigene Request-ID binden, damit Wiederholungen keine doppelte Arbeit erzeugen.
  • Einreichen und Abfragen trennen. Legen Sie Einreichen und Abfragen in verschiedene Worker oder Phasen. Das entkoppelt Ihre API-Latenz von der Generierungszeit und lässt Sie die Abfrage unabhängig skalieren.
  • Eigenen Speicher kontrollieren. Laden Sie das Ergebnis sofort nach Abschluss der Aufgabe in Ihren eigenen Bucket herunter. Behandeln Sie die zurückgegebene URL als temporären Link.
  • Prompts versionieren. Prompts sind Produktionsassets. Speichern Sie Prompt, Referenzbild und Aufgaben-ID zusammen mit jeder Ausgabe, damit Sie Monate später ein Ergebnis reproduzieren oder erklären können.
  • Latenz und Kosten im Blick behalten. Bildaufgaben werden pro Ausgabe abgerechnet, also begrenzen Sie die Parallelität pro Nutzer und protokollieren Sie den Verbrauch pro Aufgabe. Überwachen Sie die p95-Latenz vom Einreichen bis zur Materialspeicherung – das ist die Zahl, die Nutzer tatsächlich spüren.

Sobald die Anfrageform und der Lebenszyklus feststehen, bleibt nur noch gewöhnliche Ingenieursarbeit. Details zum Modell finden Sie in der HiAPI-Dokumentation, und von dort binden Sie den Endpoint in Ihre Pipeline ein.

Ähnliche Artikel

Alle Artikel ansehen →

Starte mit persistenten KI-Artefakten

Hol dir deinen API-Key und rufe Bild-, Video- und Audiomodelle über eine einzige task-basierte API auf.

API-Dokumentation lesen