So rufen Sie gpt-image-2/image-to-image auf HiAPI auf: curl, Python und eine funktionierende Anfrage

Was der image-to-image-Endpunkt erwartet

Das Modell gpt-image-2/image-to-image auf HiAPI ist ein asynchroner Bildgenerierungs-Endpunkt. Anders als synchrone Aufrufe, die blockierend auf das zurückgegebene Bild warten, nimmt dieser Endpunkt Ihre Anfrage entgegen, stellt sie in eine Warteschlange und gibt ein Task-Handle zurück. Anschließend müssen Sie diesen Task kontinuierlich verfolgen, bis er abgeschlossen ist.

Auf Anfrageebene müssen Sie drei Dinge bereitstellen:

• Modell-ID: gpt-image-2/image-to-image.
• Ein Referenzbild: das Quellbild, auf dessen Grundlage das Modell transformieren oder aufbauen soll. Dies ist die entscheidende Eingabe im Image-to-Image-Modus – ohne sie machen Sie Text-to-Image.
• Prompt und Optionen: eine Textanweisung, die die gewünschte Ausgabe beschreibt, sowie optionale Felder aus der Modelldokumentation (z. B. Größe oder Ausgabeformat). Senden Sie nur die in der Modelldokumentation aufgeführten Parameter.

Die Antwort ist nicht das Bild selbst, sondern ein Task-Objekt mit einer Kennung und einem Status. Betrachten Sie diesen Status als einzige Wahrheitsquelle: pending oder processing bedeutet weiter warten, succeeded bedeutet, das Ergebnis ist bereit, failed bedeutet, es ist ein Problem aufgetreten und das Polling sollte beendet werden.

Entwerfen Sie Ihren Client von Anfang an um diesen Lebenszyklus herum. Alles andere in diesem Tutorial – curl, Python, Polling, Download – baut auf der Tatsache auf, dass „Einreichen und Abschließen zwei getrennte Zeitpunkte sind“.

HiAPI-Schlüssel und Referenzbild vorbereiten

Bevor Sie Code schreiben, bereiten Sie zwei Dinge vor.

Einen API-Schlüssel. Erstellen Sie einen in der HiAPI-Konsole und speichern Sie ihn in einer Umgebungsvariable, statt ihn direkt in das Skript einzufügen:

export HIAPI_API_KEY="your-key-here"

Behandeln Sie den Schlüssel als Geheimnis. Committen Sie ihn nicht ins Repository und protokollieren Sie ihn nicht in Request-Logs.

Ein Referenzbild. Wählen Sie eine lokale Bilddatei, die Sie transformieren möchten. Halten Sie die Größe vernünftig – übermäßig große, hochauflösende Quellbilder sind die häufigste Ursache für langsame oder abgelehnte Anfragen. Legen Sie eine PNG- oder JPEG-Datei im Verzeichnis des Skripts ab; das ist für den ersten Lauf am einfachsten:

ls -lh ./reference.png

Notieren Sie sich den Dateipfad; Sie werden ihn sowohl in den curl- als auch in den Python-Beispielen referenzieren. Wenn Sie das Modell von einem Server aus aufrufen möchten, stellen Sie sicher, dass der Prozess Leserechte auf diesen Pfad hat und die Datei ein gültiges Bild ist (keine umbenannte Datei mit falscher Erweiterung).

Mit exportiertem Schlüssel und dem Bild auf der Festplatte ist alles bereit für die erste Anfrage.

Eine funktionierende curl-Anfrage

Der schnellste Weg, Anmeldedaten und Request-Body-Struktur zu verifizieren, ist ein curl-Aufruf. Er reicht den Task ein und gibt das Task-Objekt aus:

curl -sS https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/image-to-image",
    "input": {
      "image": "https://example.com/reference.png",
      "prompt": "Turn this photo into a watercolor illustration"
    }
  }'

Zwei Anmerkungen zu diesem Beispiel. Erstens wird das Referenzbild über das Feld input.image als URL übergeben; wenn die Endpunktdokumentation für Ihren Anwendungsfall Inline-base64 oder Multipart-Upload unterstützt, verwenden Sie diese Form, aber behalten Sie den Feldnamen bei. Zweitens ist der Prompt der Ort, an dem Sie die Transformation beschreiben – seien Sie konkret in Bezug auf Stil, Komposition und welche Inhalte unverändert bleiben sollen.

Führen Sie ihn aus und lesen Sie die Antwort. Eine erfolgreiche Einreichung gibt eine Task-ID und einen nicht-terminalen Status zurück. Bei einem 401 fehlt Ihr Schlüssel oder ist falsch. Bei einem 422 oder einem ähnlichen Validierungsfehler prüfen Sie den Request-Body – meist ist die Modell-ID oder das Format des image-Felds fehlerhaft.

Speichern Sie die Task-ID. Die folgenden Schritte hängen davon ab.

Dasselbe mit Python tun

Die Python-Version sollte exakt dem curl-Aufruf entsprechen, Authentifizierung und Body-Aufbau explizit beibehalten, damit nichts durch eine Abstraktionsschicht verborgen wird. Verwenden Sie requests:

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "gpt-image-2/image-to-image",
    "input": {
        "image": "https://example.com/reference.png",
        "prompt": "Turn this photo into a watercolor illustration",
    },
}

response = requests.post(f"{BASE_URL}/tasks", json=payload, headers=headers, timeout=30)
response.raise_for_status()
task = response.json()
print(task["id"], task["status"])

Wenn Ihre Integration eine lokale Datei statt einer URL sendet, kodieren und hängen Sie das Bild gemäß der Endpunktdokumentation an, statt eigene Felder zu erfinden. Die Disziplin ist dieselbe wie bei curl: den Request-Body als gewöhnliches Dictionary aufbauen, senden, den HTTP-Status prüfen, bevor Sie parsen.

Kapseln Sie die Einreichungslogik in eine Funktion, die eine Task-ID zurückgibt. So ist der Polling-Code im nächsten Abschnitt unabhängig davon, wie der Task erstellt wurde.

Asynchrone Tasks bis zum Abschluss pollen

Der Einreichungsaufruf kehrt bereits zurück, während das Bild noch generiert wird. Um das Ergebnis zu erhalten, pollen Sie den Task-Status-Endpunkt, bis der Task einen terminalen Zustand erreicht. Eine robuste Schleife hat drei Eigenschaften: eine Verzögerung zwischen den Polls, eine maximale Wartezeit und eine explizite Behandlung von Fehlerzuständen.

import time

def wait_for_task(task_id, headers, base_url, timeout=300, interval=3):
    deadline = time.time() + timeout
    while time.time() < deadline:
        r = requests.get(f"{base_url}/tasks/{task_id}", headers=headers, timeout=30)
        r.raise_for_status()
        task = r.json()
        status = task["status"]
        if status == "succeeded":
            return task
        if status == "failed":
            raise RuntimeError(f"Task failed: {task}")
        time.sleep(interval)
    raise TimeoutError(f"Task {task_id} did not finish within {timeout}s")

Einige praktische Verbesserungen:

• Backoff: Beginnen Sie mit einem kurzen Intervall und erhöhen Sie es allmählich, oder halten Sie ein ausreichend großzügiges festes Intervall ein, um die API nicht zu häufig zu belasten. Die Bildgenerierung erfolgt nicht sofort.
• Timeout: Setzen Sie immer eine Obergrenze für die gesamte Wartezeit. Sonst hängt ein festgefahrener Task Ihren Worker unbegrenzt auf.
• Terminale Zustände: Betrachten Sie nur succeeded und failed als terminal. Jeder andere Zustand bedeutet, weiter zu pollen. Falls die API künftig Zwischenzustände hinzufügt, funktioniert Ihre Schleife weiterhin korrekt.

Wenn Sie viele Tasks ausführen, pollen Sie in einem Hintergrund-Worker oder einer Queue, statt eine Web-Anfrage zu blockieren. Derselbe Lebenszyklus, nur ein anderes Nebenläufigkeitsmodell.

Ergebnis herunterladen und verifizieren

Sobald der Task Erfolg meldet, enthält das Task-Objekt den Speicherort des generierten Bildes – meist eine URL in einem Ausgabefeld. Laden Sie sie herunter und schreiben Sie sie auf die Festplatte:

task = wait_for_task(task_id, headers, BASE_URL)
image_url = task["output"]["image"]

img = requests.get(image_url, timeout=60)
img.raise_for_status()

with open("result.png", "wb") as f:
    f.write(img.content)

Wenn signierte URLs eine Gültigkeitsdauer haben, laden Sie sofort nach Abschluss herunter oder persistieren Sie die Datei direkt, statt die URL für später zu speichern. Wenn Ihr Endpunkt base64 statt einer URL zurückgibt, dekodieren Sie zuerst und schreiben Sie dann.

Eine schnelle Integritätsprüfung vermeidet verwirrende nachgelagerte Fehler:

from PIL import Image

with Image.open("result.png") as im:
    im.verify()
print("valid image, bytes:", os.path.getsize("result.png"))

Wenn die Datei kein dekodierbares Bild ist, wirft verify() eine Ausnahme; das fängt abgeschnittene Downloads und als Bild gespeicherte Fehlerseiten ab. Auch die Prüfung der Byte-Größe sagt Ihnen, ob die Antwort plausibel ist. Damit ist der Kreis geschlossen: einreichen, pollen, herunterladen, verifizieren.

Häufige Fehler beheben

Die meisten ersten Integrationen scheitern auf einige vorhersehbare Arten. Diagnostizieren Sie in dieser Reihenfolge.

Authentifizierungsfehler (401/403). Schlüssel fehlt, ist falsch formatiert oder hat keine Berechtigung. Prüfen Sie, ob die Umgebungsvariable in der Shell oder im Prozess, der die Anfrage ausführt, exportiert ist und ob der Authorization-Header das exakte Präfix verwendet, das die API erwartet.

Referenzbild ungültig oder zu groß (400/422). Die Bild-URL ist möglicherweise von der API-Seite aus nicht erreichbar, die Datei ist beschädigt oder die Abmessungen und Dateigröße überschreiten die Grenzen. Testen Sie zuerst mit einem kleinen, nachweislich funktionierenden PNG. Wenn Sie eine URL senden, stellen Sie sicher, dass sie öffentlich erreichbar ist; wenn Sie Inline-Daten senden, bestätigen Sie die korrekte Kodierung.

Polling-Timeout. Wenn der Task wiederholt Ihr Timeout erreicht, erhöhen Sie die Obergrenze, verlängern Sie das Intervall oder prüfen Sie, ob der Task tatsächlich bereits fehlgeschlagen ist und Sie nur den Grund nicht anzeigen. Protokollieren Sie das letzte Task-Objekt vor dem Auslösen der Ausnahme, um den Status einzusehen.

Rate-Limits (429). Führen Sie Backoff mit Jitter und erneutem Versuch durch, statt sofort zu wiederholen. Wenn Sie viele parallele Einreichungen machen, begrenzen Sie die Nebenläufigkeit, damit Stoßverkehr keine Limits auslöst, und machen Sie Wiederholungen durch Protokollierung der Task-ID idempotent.

Protokollieren Sie für jede Fehlerklasse den HTTP-Status, den gekürzten Response-Body und die Task-ID – diese drei reichen meist aus, um zu erkennen, ob das Problem bei der Authentifizierung, dem Body oder dem Timing liegt. Isolieren Sie mit dem curl-Beispiel zunächst, ob das Problem in Ihrem Code oder in der Eingabe liegt, und übertragen Sie die Korrektur dann zurück nach Python.