Tutorial
So rufen Sie gpt-image-2.6-flare/image-to-image über die HiAPI API auf: curl und Python
Referenzbild-Upload, synchrone und asynchrone Anfragen sowie das Debuggen eines funktionierenden Aufrufs
Auf dieser Seite
Was dieser Endpunkt leistet und wann Sie image-to-image verwenden sollten
Text-zu-Bild-Modelle sind gut darin, Szenen von Grund auf neu zu erschaffen, aber viele Produktionsaufgaben beginnen mit einem bereits vorhandenen Bild. gpt-image-2.6-flare/image-to-image ist genau der Endpunkt, den HiAPI für solche Aufgaben bereitstellt: Sie senden ein Referenzbild und einen Prompt, und das Modell liefert ein transformiertes Bild zurück, das Ihren Anweisungen folgt und gleichzeitig fest am Referenzbild verankert bleibt.
Typische Anwendungsfälle sind:
- Stiltransfer und Neuzeichnen – verwandeln Sie Produktbilder in stilisierte Illustrationen oder zeichnen Sie Fotos in einer anderen visuellen Sprache neu.
- Bearbeitung und Retusche – passen Sie Beleuchtung, Hintergrund oder Komposition vorhandener Assets an, ohne neu zu fotografieren.
- Variantengenerierung – erzeugen Sie mehrere visuelle Varianten eines Basisdesigns für A/B-Tests oder kreative Erkundung.
- Asset-Anpassung – passen Sie die Größe eines Referenzbilds an verschiedene Kanäle an oder komponieren Sie es neu, während das Kernmotiv erhalten bleibt.
Wenn Ihre Aufgabe lautet „Beschreibe etwas und erhalte ein Bild“, ist Text-zu-Bild die einfachere Wahl. Verwenden Sie image-to-image erst dann, wenn die Ausgabe erkennbar von einem bestimmten Eingabebild abstammen muss – dieses Referenzbild ist der eigentliche Sinn des Aufrufs. Im Rest dieses Artikels bauen wir eine echte Anfrage von Ende zu Ende auf: zuerst mit curl, um zu beweisen, dass sie funktioniert, dann in Python, damit Sie sie in Ihren Dienst integrieren können.
Voraussetzungen und Anfragestruktur
Bevor Sie diesen Endpunkt aufrufen, stellen Sie sicher, dass die folgenden Voraussetzungen erfüllt sind:
- Ein HiAPI-Konto und ein API-Schlüssel. Der Schlüssel wird als Bearer-Token im Header
Authorizationgesendet. Committen Sie ihn nicht in ein Quellcode-Repository, sondern laden Sie ihn aus einer Umgebungsvariable (z. B.HIAPI_API_KEY). - Die Modell-ID. Verwenden Sie exakt
gpt-image-2.6-flare/image-to-image– Modell-IDs sind groß-/kleinschreibungssensitiv, und der Schrägstrich ist Teil des Bezeichners. - Der Endpunktpfad. Die Bildgenerierung befindet sich unter der Bildgenerierungs-Route auf dem HiAPI-API-Host. Suchen Sie die aktuelle Basis-URL und den Pfad auf der Modellseite, statt einen Host fest zu kodieren, den Sie in einem alten Code-Snippet gesehen haben.
- Eine Referenzbilddatei in einem gängigen Format (PNG oder JPEG sind sichere Standardwerte). Halten Sie die Dateigröße im vernünftigen Rahmen; zu große Dateien verlangsamen den Upload und können Anfragelimits auslösen.
Eine Anfrage an gpt-image-2.6-flare/image-to-image besteht aus drei wesentlichen Teilen:
- Modellselektor – teilt HiAPI mit, an welches Modell die Anfrage geroutet werden soll.
- Prompt – die Textanweisung, die die gewünschte Transformation beschreibt. Sie ist nicht optional; der Prompt ist der eigentliche Lenker der Bearbeitung.
- Referenzbild – das Eingabebild, auf dessen Grundlage das Modell arbeiten soll. Wie Sie es übergeben, hängt von der Anfrageart ab (siehe nächster Abschnitt).
Darüber hinaus sollten Sie nur Parameter übergeben, die für dieses Modell auf seiner HiAPI-Modellseite dokumentiert sind. Wenn Sie sich dabei ertappen, ein Feld zu erfinden, weil der Name „richtig aussieht“, halten Sie inne und lesen Sie die Dokumentation – unbekannte Parameter sind eine häufige Ursache für verwirrende 4xx-Fehler.
Wie Sie das Referenzbild übergeben
Konzeptionell ist das Referenzbild einfach ein weiteres Eingabefeld im Request-Body – aber seine Größe macht es besonders. Es gibt zwei praktikable Wege, die Bytes an die API zu übergeben, und diese Wahl wirkt sich weit stärker auf Ihren Client-Code aus als auf die API selbst.
Variante A: Inline im Request-Body
Kleine Bilder können direkt in die JSON-Nutzlast eingebettet werden, üblicherweise als base64-kodierter String. Sie lesen die Datei, kodieren sie und legen den String in das image-Feld der Anfrage. So ist alles in einer Anfrage, was sich für Thumbnails, Icons und Test-Fixtures gut eignet.
Der Preis: base64 bläht die Nutzlast um etwa ein Drittel auf, JSON-Encoder können mit sehr langen Strings nicht umgehen, und das Debuggen mehrerer Megabyte großer Request-Bodys in Logs ist mühsam. Inline dient der Bequemlichkeit, nicht großen Assets.
Variante B: Erst hochladen, dann per URL referenzieren
Für alles außer sehr kleinen Bildern laden Sie die Datei zuerst in einen von Ihnen kontrollierten Speicher hoch und übergeben dann ihre URL als Referenz. Ihr Request-Body bleibt klein, Wiederholungen sind günstig, und dasselbe Bild kann in mehreren Aufrufen wiederverwendet werden, ohne es jedes Mal neu hochzuladen.
Bei der Arbeit mit URLs sind einige Punkte zu beachten:
- Die URL muss für die API öffentlich zugänglich sein – nicht hinter einer Authentifizierung, nicht localhost und kein abgelaufener signierter Link, der mitten in der Anfrage ungültig wird.
- Verwenden Sie einen vom Modell akzeptierten Inhaltstyp; wenn die URL HTML statt eines Bildes zurückgibt, schlägt die Validierung fehl.
- Bevorzugen Sie stabile Dateinamen, damit Sie Logs zwischen Ihrem Speicher und den HiAPI-Anfragen korrelieren können.
Unabhängig von der gewählten Variante werden Referenzbild und Prompt in derselben Anfrage übergeben. Die API erfordert keinen separaten „erst hochladen, dann generieren“-Handshake – der Modellaufruf ist eine einzige logische Operation.
Synchrone und asynchrone Aufrufe
Die Bildgenerierung dauert Zeit, weshalb viele Bild-APIs neben einem synchronen Weg auch einen asynchronen Job-Modus anbieten. Auch hier gilt derselbe Kompromiss.
Synchron
Sie senden die Anfrage und halten die Verbindung offen, bis das Bild zurückkommt. Ihr Code ist eine gerade Linie: Anfrage bauen, POST, Antwort lesen, fertig.
Verwenden Sie synchrone Aufrufe, wenn:
- Sie prototypisieren oder debuggen und das vollständige Ergebnis in einem Schritt sehen möchten.
- die Anfrage in einer Umgebung läuft, in der Blockieren für eine Weile akzeptabel ist (CLI-Tools, Hintergrund-Worker).
- Sie einen möglichst einfachen Client ohne Polling-Logik möchten.
Der Nachteil: Lange Generierungen bedeuten lange offene Verbindungen, und jeder Proxy oder Load Balancer zwischen Ihnen und der API kann eigene Timeouts erzwingen.
Asynchron
Sie übermitteln die Anfrage als Job, erhalten sofort eine Job-ID und pollen dann (oder empfangen einen Callback), bis der Job abgeschlossen ist. Ihr Client benötigt einen kleinen Zustandsautomaten: einreichen, warten, Ergebnis abrufen, Fehler behandeln.
Verwenden Sie asynchrone Aufrufe, wenn:
- Sie nutzernahen Traffic bedienen und es sich nicht leisten können, Anfrage-Threads zu blockieren.
- Sie viele Bilder im Batch generieren und die Arbeit parallel verteilen und Ergebnisse sammeln möchten.
- Ihre Infrastruktur kurze Request-Timeouts hat, die Sie nicht kontrollieren.
So wählen Sie: Wenn jemand in einer Web-Anfrage auf das Ergebnis wartet, verwenden Sie asynchron. Wenn ein Skript oder Worker offline wartet, ist synchron einfacher und völlig in Ordnung. Überkonstruieren Sie nicht: erst synchron, und wechseln Sie zu asynchron, wenn echte Timeouts oder Nebenläufigkeitsgrenzen Sie dazu zwingen.
Der Rest dieses Artikels verwendet den synchronen Weg, weil er jeden Schritt sichtbar macht, aber der Request-Body, den Sie bauen, ist in beiden Modi identisch – nur die umgebende Infrastruktur unterscheidet sich.
Eine funktionierende curl-Anfrage
Bauen wir den Aufruf aus dem Terminal auf. Setzen Sie zuerst Ihren Schlüssel:
export HIAPI_API_KEY="your-api-key-here"
Schritt 1: Referenzbild vorbereiten
Beginnen Sie mit einem kleinen Bild, das Sie sicher kennen, damit ein Fehlschlag keine Mehrdeutigkeit lässt:
ls -lh reference.png
file reference.png
file sollte PNG image data oder JPEG image data melden. Wenn etwas anderes gemeldet wird, korrigieren Sie das zuerst, bevor Sie fortfahren.
Schritt 2: Anfrage senden
Die Anfrage ist ein POST an den Bildgenerierungs-Endpunkt, dessen JSON-Body das Modell, Ihren Prompt und das Referenzbild enthält. Je nach gewählter Upload-Variante ist das image-Feld entweder eine URL oder ein base64-String.
curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6-flare/image-to-image",
"prompt": "Recreate this scene as a flat vector illustration with a muted palette",
"image": "https://your-storage.example.com/reference.png"
}'
Zu diesen Parametern:
-sSblendet den Fortschrittsbalken aus, zeigt aber weiterhin Fehler – gut für Skripte.Authorization: Bearer $HIAPI_API_KEYsorgt dafür, dass der Schlüssel nicht im Befehl selbst auftaucht.$HIAPI_BASE_URLwird von der Modellseite übernommen; raten Sie den Host nicht.- Das Feld
imagenutzt hier die URL-Variante; für Inline-Bilder ersetzen Sie es durch einen base64-String.
Schritt 3: Antwort lesen
Fügen Sie -i hinzu, um die Antwort-Header einzuschließen, und -w '\nHTTP %{http_code}\n', um den Statuscode auszugeben. Ein erfolgreicher Aufruf liefert das Bild (bzw. einen Link zum Bild, je nach Antwortformat) sowie Metadaten. Bei einem Fehler erhalten Sie einen 4xx- oder 5xx-Statuscode und einen JSON-Fehlerbody – lesen Sie das Feld message, bevor Sie irgendetwas anderes ändern.
Schritt 4: Ausgabe in eine Datei umleiten
Für eine saubere Datei leiten Sie stdout in eine Datei um und prüfen sie erneut mit file. Wenn die Antwort JSON mit einer URL ist, extrahieren Sie diese URL und laden Sie sie mit einem zweiten curl herunter. Bevor Sie das in irgendeine Automatisierung einbinden, verifizieren Sie stets, dass die heruntergeladenen Bytes tatsächlich ein Bild sind.
Dieselbe Anfrage in Python
Die curl-Basis lässt sich direkt nach Python übersetzen. Dieses Beispiel verwendet nur die Standardbibliothek plus requests:
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
payload = {
"model": "gpt-image-2.6-flare/image-to-image",
"prompt": "Recreate this scene as a flat vector illustration with a muted palette",
"image": "https://your-storage.example.com/reference.png",
}
response = requests.post(
f"{BASE_URL}/images/generations",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)
Antwort verarbeiten
Das Antwortformat variiert – es kann das Bild direkt enthalten oder eine URL. Schreiben Sie eine kleine Hilfsfunktion, die beide Fälle vereinheitlicht, damit der nachgelagerte Code nicht wissen muss, welcher Fall vorliegt:
def extract_image(data):
if "url" in data:
return requests.get(data["url"], timeout=60).content
if "image" in data:
import base64
return base64.b64decode(data["image"])
raise ValueError(f"Unexpected response shape: {list(data)}")
Fehler behandeln
Lassen Sie raise_for_status() nicht Ihren einzigen Fehlerpfad sein. Umschließen Sie den Aufruf und geben Sie die Fehlermeldung der API aus:
try:
response = requests.post(url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
image_bytes = extract_image(response.json())
except requests.HTTPError as e:
print("HTTP", e.response.status_code, e.response.text)
raise
except requests.Timeout:
print("Request timed out; consider the async job route instead")
raise
Asynchrone Variante
Für den asynchronen Weg übermitteln Sie den Job mit derselben Nutzlast, lesen die Job-ID aus der Antwort und pollen dann den Job-Status-Endpunkt mit kurzen Pausen zwischen den Versuchen. Setzen Sie eine Obergrenze für die Polling-Versuche und behandeln Sie das Aufbrauchen des Budgets als Fehler – pollen Sie niemals unbegrenzt in einem Request-Handler.
Häufige Fehler beheben
Die meisten Fehlschläge fallen in wenige Kategorien. Gehen Sie diese Checkliste der Reihe nach durch; jeder Schritt isoliert eine Variable.
Authentifizierungsfehler (401 / 403)
- Ist
HIAPI_API_KEYtatsächlich in der Shell oder im Prozess gesetzt?echo $HIAPI_API_KEYsollte ihn ausgeben. - Lautet der Header exakt
Authorization: Bearer <key>– großes A, großes B, ein Leerzeichen? - Wurde der Schlüssel widerrufen oder rotiert? Generieren Sie ihn neu und versuchen Sie es mit einer minimalen Anfrage erneut.
Ungültige Referenzbild-Nutzlast
Dies ist der häufigste Fehlschlag, und meist liegt es nicht am Modell:
- URL nicht erreichbar: Öffnen Sie die Bild-URL in einem Browser in einem anderen Netzwerk. Wenn sie 404 liefert oder auf eine Anmeldeseite weiterleitet, kann die API sie ebenfalls nicht erreichen.
- Falscher Inhaltstyp: URLs, die HTML oder JSON zurückgeben, werden abgelehnt. Prüfen Sie mit
curl -I <url>, dass die AntwortContent-Type: image/...ist. - Datei beschädigt oder unlesbar: Führen Sie lokal
file reference.pngaus. Stellen Sie sicher, dass der base64-String dekodiert exakt dieselben Bytes wie die Originaldatei ergibt. - Datei zu groß: Prüfen Sie die auf der Modellseite dokumentierten Größengrenzen; verkleinern Sie das Bild vor einem erneuten Versuch.
Fehlerhafte Parameterformate
- Modell-ID falsch geschrieben:
gpt-image-2.6-flare/image-to-imagemuss exakt übereinstimmen, einschließlich des Schrägstrichs. - Prompt fehlt: Die Textanweisung ist erforderlich und darf nicht weggelassen werden.
- Überflüssige Felder: Entfernen Sie jeden Parameter, den Sie in der Dokumentation nicht finden. Unbekannte Schlüssel lösen häufig 4xx aus.
- JSON-Syntax: Validieren Sie Ihren Request-Body vor dem Senden mit
jq . <<< "$BODY".
Timeouts
Wenn die Anfrage abbricht, bevor das Bild zurückkommt, wurde die Verbindung zu lange offen gehalten. Kürzen Sie den Prompt, verkleinern Sie das Referenzbild, erhöhen Sie das Client-Timeout; wenn das Problem weiterhin besteht, wechseln Sie zum asynchronen Job-Modus – lange Generierungen sind genau der Anwendungsfall für Asynchronie.
Debugging-Strategie
Ändern Sie pro Versuch nur eine Variable. Beginnen Sie mit einem sehr kleinen, sicher bekannten Referenzbild und einem Prompt, um zu beweisen, dass die Pipeline funktioniert, und führen Sie dann schrittweise echte Eingaben ein. Protokollieren Sie bei jedem Fehlschlag den vollständigen Antwortbody; das Feld message weist oft direkt auf den fehlerhaften Teil der Anfrage hin.
In Ihre Pipeline integrieren
Sobald die Basis funktioniert, machen einige Gewohnheiten gpt-image-2.6-flare/image-to-image in der Produktion zuverlässig.
Eingaben vor dem Aufruf validieren. Prüfen Sie, ob das Referenzbild ein unterstütztes Format hat und innerhalb der Größengrenzen liegt, und wenn es eine URL ist, ob sie erreichbar ist. Weisen Sie schlechte Eingaben an Ihrer eigenen Grenze zurück, statt für einen fehlgeschlagenen Roundtrip zu bezahlen.
Ausgaben nach dem Aufruf validieren. Stellen Sie sicher, dass die Antwort echte Bildbytes enthält (prüfen Sie die Magic Bytes) und keine untergeschobene HTML-Fehlerseite. Eine günstige Header-Prüfung erspart nachgelagert viel verwirrendes Debugging.
Mit Backoff wiederholen, aber nur bei den richtigen Fehlern. Transiente 5xx-Fehler und Netzwerk-Timeouts verdienen Wiederholungen mit exponentiellem Backoff plus Jitter; 4xx-Fehler durch schlechte Parameter schlagen jedes Mal exakt gleich fehl, also korrigieren Sie die Anfrage statt sie zu wiederholen.
Für nutzernahe Arbeit asynchron bevorzugen. Wenn jemand auf einer Seite wartet, übermitteln Sie einen Job und pollen Sie vom Client aus – halten Sie keine Web-Anfrage für eine lange Generierung offen.
Modell-IDs in der Konfiguration ablegen. Modell-IDs ändern sich mit der Zeit. Lesen Sie sie aus einer einzigen Konfigurationsstelle, damit ein Modellwechsel eine Zeile ändert statt eine globale Suche-und-Ersetzen-Aktion erfordert.
Mit anderen HiAPI-Modellen kombinieren. Dieser Endpunkt passt natürlich zu Text-zu-Bild und bildet hybride Pipelines (erst ein Basisbild generieren, dann bearbeiten); falls Ihre Pipeline es braucht, auch zu Upscaling- oder Hintergrundentfernungs-Schritten. Da alles über dieselbe HiAPI-Schnittstelle und dieselbe Authentifizierung läuft, ist ein zusätzlicher Schritt nur ein weiterer Aufruf mit demselben Schlüssel.
Beginnen Sie mit der curl-Basis, portieren Sie nach Python und wechseln Sie zu asynchron, wenn der Traffic es erfordert. Die Modellseite bietet die aktuellen Anfrageparameter und Limits – schauen Sie dort nach, bevor Sie einen Feldnamen oder eine Größenobergrenze annehmen.
Ähnliche Artikel
Alle Artikel ansehen →-
Tutorial
gpt-6.2-sol Praxisleitfaden: 5 hochwertige Einsatzszenarien für Textmodelle im Geschäftsalltag
-
Tutorial
gpt-6.2-astra Praxisleitfaden: Integration und Umsetzung von 5 hochwertigen Text-Szenarien
Eine Entwickler-Checkliste von der Szenarioauswahl bis zur technischen Umsetzung
-
Tutorial
Tripo H3.1 Anwendungsszenarien in der Praxis: 5 wertvolle Einsatzmöglichkeiten und Umsetzungshinweise
Von Text-zu-3D bis Multi-View-Rekonstruktion: den richtigen Modus und die richtigen Parameter je nach Geschäftsszenario wählen