Wie man grok-imagine/image-to-image über die HiAPI API aufruft: Ein Leitfaden mit curl und Python

Was grok-imagine/image-to-image Entwicklern bietet

grok-imagine/image-to-image ist ein Bildtransformations-Endpunkt: Sie übergeben ihm ein Referenzbild und einen Prompt, und er liefert ein neues Bild zurück, das dem Prompt folgt und dabei visuell mit dem Referenzbild verbunden bleibt. Man kann es als gesteuerte Generierung verstehen, nicht als Generierung von Grund auf. Die Modell-ID, die Sie auf HiAPI aufrufen, ist genau grok-imagine/image-to-image, und der Rest der Anfrage dient dazu, die gewünschte Änderung zu beschreiben.

Wann immer die Ausgabe bestimmte Inhalte aus vorhandenem Material bewahren muss – ein Produktfoto mit auszutauschender Hintergrund, eine Charakterskizze, die gerendert werden soll, eine Komposition, deren Stil geändert werden soll –, sollten Sie diesen Endpunkt statt eines Text-zu-Bild-Aufrufs wählen. Text-zu-Bild eignet sich für Szenarien, in denen Sie kein Quellbild, sondern nur eine Beschreibung haben; image-to-image eignet sich, wenn das Quellbild selbst Teil der Spezifikation ist.

Da HiAPI ihn als eine einzige einheitliche Schnittstelle bereitstellt, beschränkt sich Ihre Integrationsarbeit darauf, eine Anfragestruktur zu erstellen und eine Antwortstruktur zu verarbeiten. Sie müssen weder für jede Modellfamilie ein separates SDK einbinden noch für jeden Endpunkt die Authentifizierung neu erlernen.

Aufbau einer Anfrage: Modell, Referenzbild und Prompt

Jeder gültige Aufruf besteht konzeptionell aus vier Teilen. Wenn Sie jeden davon vor dem Schreiben von Code richtig hinbekommen, ersparen Sie sich den Großteil der späteren Debugging-Arbeit.

Modell-ID

Das Feld model enthält den String grok-imagine/image-to-image. Behandeln Sie ihn als Konstante in Ihrem Client und nicht als hartcodiertes Literal, das über die gesamte Codebasis verstreut ist – falls Sie später andere HiAPI-Modelle ausprobieren möchten, sollten Sie nur eine Stelle ändern müssen.

Referenzbild

Das Referenzbild ist der Anker. Wie Sie es übergeben, hängt vom gewählten Transportweg ab: entweder eine URL, die die API abrufen kann, oder Inline-Base64-Daten, geeignet für ad-hoc generierte Bilder oder Bilder ohne öffentlichen Zugriff. Bevorzugen Sie bei Material, das Sie bereits hosten, eine URL; bevorzugen Sie bei Benutzer-Uploads, die noch nicht an einem öffentlichen Ort persistiert sind, Inline-Daten. Validieren Sie das Bild in beiden Fällen vor dem Senden: Format unterstützt, Größe nicht null, Abmessungen ausreichend aussagekräftig.

Prompt

Der Prompt beschreibt die Transformation, nicht die gesamte Szene. Wenn das Referenzbild bereits das Motiv enthält, beschreiben Sie, was sich ändern soll – Stil, Beleuchtung, Hintergrund, Material – und lassen Sie das Unveränderte implizit. Eine Überbestimmung von Inhalten, die im Referenzbild bereits sichtbar sind, steht oft in Konflikt mit der Bildkonditionierung, statt zu helfen.

Umgang mit dem Seitenverhältnis

Der verbleibende Teil betrifft die Frage, wie die Ausgabegröße bestimmt wird – das ist Gegenstand des nächsten Abschnitts. Halten Sie diese vier Teile im Code, der die Anfrage baut, getrennt, damit jeder unabhängig validiert und protokolliert werden kann.

Die Option auto aspect verwenden

Die Option auto aspect überlässt der API die Wahl der Ausgabegröße, anstatt dass Sie explizite Breite und Höhe festlegen. Wenn sie aktiviert ist, leitet der Dienst ein passendes Seitenverhältnis aus dem Anfragekontext – vor allem aus dem Referenzbild – ab, sodass die Form der Ausgabe relativ zu Ihrer Eingabe sinnvoller ist, statt in ein Standardformat gezwungen zu werden.

Das ist wichtiger, als es klingt. Wenn Sie eine Größe festlegen, die nicht zum Verhältnis des Referenzbildes passt, erhalten Sie Letterbox-Artefakte, unglückliche Beschnitte des Motivs oder eine Komposition, die die Bildkomposition der Quelle ignoriert. auto aspect vermeidet solche Diskrepanzen, indem die Geometrie der Eingabe folgt.

Wann auto aktiviert bleiben sollte

• Die Referenzbilder stammen von Benutzern und haben unterschiedliche Formen.
• Sie prototypen und wissen noch nicht, welche Größe für den Anwendungsfall geeignet ist.
• Die Ausgabe fließt in eine Pipeline, die ohnehin zuschneidet oder skaliert.

Wann Größen explizit festgelegt werden sollten

• Sie haben feste Slots in einer UI oder einem Druckziel und benötigen eine exakte Ausgabegeometrie.
• Sie generieren eine Charge von Bildern, die in der Größe visuell konsistent sein müssen.

Eine praktische Vorgehensweise: Lassen Sie auto aspect während der Entwicklung aktiviert, prüfen Sie die Größen, die die API für reale Eingaben zurückgibt, und entscheiden Sie dann, ob Sie die Größe für die Produktion festlegen. Protokollieren Sie die Metadaten des zurückgegebenen Bildes zusammen mit der Anfrage, damit diese Entscheidung auf Belegen statt auf Vermutungen beruht.

Verfügbare curl-Anfrage

Die folgende Anfrage ist bis auf die in spitzen Klammern markierten Platzhalter vollständig. Ersetzen Sie sie durch Ihre eigenen Werte, dann ist sie direkt ausführbar.

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/image-to-image",
    "prompt": "<describe the transformation you want>",
    "image": "<publicly reachable URL of your reference image>",
    "aspect_ratio": "auto"
  }'

Zu ersetzende Platzhalter

• $HIAPI_API_KEY – lesen Sie Ihren Schlüssel aus einer Umgebungsvariable, statt ihn in den Befehl einzufügen. Ist die Variable nicht gesetzt, schlägt die Anfrage mit einem Authentifizierungsfehler fehl, und der Schlüssel gelangt nie in Ihre Shell-Historie.
• <describe the transformation you want> – eine kurze, konkrete Anweisung, etwa eine Stil- oder Hintergrundänderung.
• <publicly reachable URL of your reference image> – eine URL, die der Dienst ohne Authentifizierung abrufen kann. Wenn Ihr Material privat ist, verwenden Sie stattdessen Inline-Base64-Daten.

Die Antwort lesen

Führen Sie die Ausgabe beim ersten Lauf durch ein JSON-Formatierungswerkzeug, um die Antwortstruktur klar zu sehen. Achten Sie auf zwei Dinge: die Bildnutzlast (je nach Antwortmodus entweder eine URL oder codierte Daten) und den Aufgabenbezeichner, falls der Aufruf asynchron verarbeitet wird. Speichern Sie während der Entwicklung die vollständige Rohantwort in den Logs – das ist der schnellste Weg, die Frage „was wurde tatsächlich zurückgegeben“ zu beantworten, wenn etwas nicht stimmt.

Dieselbe Anfrage in Python

Die Python-Version sollte der curl-Anfrage feldweise entsprechen. Der Wert der Beibehaltung dieser Ausrichtung liegt darin: Ein in einer Version reproduzierter Fehler kann in der anderen bestätigt werden, ohne raten zu müssen.

import os
import requests

API_URL = "https://api.hiapi.ai/v1/images/generations"
MODEL = "grok-imagine/image-to-image"

def generate_from_reference(prompt: str, image_url: str) -> dict:
    payload = {
        "model": MODEL,
        "prompt": prompt,
        "image": image_url,
        "aspect_ratio": "auto",
    }
    response = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=120,
    )
    response.raise_for_status()
    return response.json()

Wo die Fehlerbehandlung hingehört

In den Wrapper, nicht in den Aufrufer. response.raise_for_status() wandelt Nicht-2xx-Antworten in Ausnahmen um, sodass ein einzelnes try/except um generate_from_reference sowohl Transportfehler als auch API-Ablehnungen abdeckt. Wenn Sie strukturierte Protokollierung der Fehlerursache wünschen, prüfen Sie innerhalb der Funktion response.status_code und den Fehlertext bevor Sie die Ausnahme werfen.

Den Client sauber halten

Lesen Sie den API-Schlüssel einmal beim Start, setzen Sie explizite Timeouts und geben Sie geparstes JSON statt des rohen Antwortobjekts zurück. Aufrufer sollten nichts über HTTP-Details wissen müssen. Richten Sie in Tests API_URL auf einen Stub-Server, sodass Sie die Logik zum Aufbau der Anfrage ohne echte Generierungsaufrufe verifizieren können.

Synchrones und asynchrones Antworten

Manche image-to-image-Anfragen sind schnell genug, um ihr Ergebnis in derselben HTTP-Antwort zurückzugeben. Andere werden als Job verarbeitet: Der erste Aufruf liefert einen Bezeichner, das Bild ist später verfügbar. Ihr Client sollte weder das eine noch das andere voraussetzen.

Wie man beides unterscheidet

Prüfen Sie nach jedem Aufruf den Antworttext. Enthält er direkt die Bildnutzlast, befinden Sie sich auf dem synchronen Pfad – extrahieren und zurückgeben. Enthält er einen Job- oder Aufgabenbezeichner, befinden Sie sich auf dem asynchronen Pfad und müssen abfragen, bis der Job einen Endzustand erreicht.

Struktur für beides entwerfen

Eine kleine Verteilerfunktion hält beide Pfade aus der Geschäftslogik heraus:

def resolve_result(response_json: dict) -> dict:
    if "image" in response_json or "data" in response_json:
        return response_json
    job_id = response_json.get("id") or response_json.get("job_id")
    if job_id:
        return poll_until_done(job_id)
    raise RuntimeError(f"Unrecognized response shape: {response_json}")

Polling-Regeln, die Ärger vermeiden

• Verwenden Sie exponentielles Backoff mit Obergrenze statt einer engen Schleife.
• Legen Sie eine maximale Gesamtwartezeit fest und scheitern Sie sauber, wenn sie überschritten wird.
• Behandeln Sie jeden Nicht-Endzustand als „weiter warten“; nur zwei Zustände sind final: Erfolg und Fehler.
• Protokollieren Sie die Job-ID bei jeder Abfrage, sodass ein hängender Job allein anhand der Logs nachvollzogen werden kann.

Der Verteileransatz bedeutet, dass Code, der resolve_result aufruft, nie geändert werden muss, wenn Sie zwischen synchronem und asynchronem Verhalten wechseln.

Häufige Fehlercodes debuggen

Die meisten fehlgeschlagenen Aufrufe an diesem Endpunkt fallen in wenige Kategorien. Gehen Sie die folgende Liste der Reihe nach durch – sie ist von der häufigsten zur seltensten Ursache sortiert.

Authentifizierungsfehler

Wenn die Antwort auf ein Authentifizierungsproblem hindeutet, fehlt der Schlüssel, ist er fehlerhaft formatiert oder wurde nicht gesendet. Prüfen Sie, ob die Umgebungsvariable in dem Prozess, der den Aufruf ausführt, tatsächlich gefüllt ist und ob der Header exakt Authorization: Bearer <key> lautet. Ein Schlüssel, der in Ihrer Shell funktioniert, aber im Dienst nicht, bedeutet meist, dass die Umgebung des Dienstes nicht Ihre Shell-Umgebung ist.

Validierungsfehler des Referenzbildes

Bildbezogene Ablehnungen bedeuten meist eines von vier Dingen: Die URL ist nicht öffentlich abrufbar, das Format wird nicht unterstützt, die Nutzlast ist zu groß oder das Bild ist zu klein oder beschädigt. Testen Sie die URL im Browser ohne Anmeldedaten – wenn sie dort nicht lädt, kann die API sie auch nicht abrufen. Stellen Sie bei Inline-Base64 sicher, dass die Codierung reines Base64 ist und kein data-URL-Präfix enthält (es sei denn, der Parameter erwartet dies).

Prompt- und Parameterfehler

Leere oder übermäßig große Prompts oder unbekannte Parameterwerte erzeugen eine Validierungsantwort. Protokollieren Sie die exakte gesendete Nutzlast zusammen mit dem Fehler – ein erheblicher Teil der Fehler sind Tippfehler in Feldnamen, nicht in Werten.

Ratenbegrenzung

Eine Antwort zur Ratenbegrenzung bedeutet Backoff, nicht sofortiges Wiederholen. Befolgen Sie die Wiederholungsrichtlinie in den Antwortheadern, fügen Sie Jitter hinzu und begrenzen Sie die Anzahl der Wiederholungen. Wiederholungen ohne Backoff verwandeln eine vorübergehende Begrenzung in eine dauerhafte.

Serverseitige Fehler

5xx-Antworten liegen auf der Serverseite. Wiederholen Sie eine begrenzte Anzahl von Malen mit Backoff; wenn der Fehler bestehen bleibt, erfassen Sie die Anfrage-ID und den Zeitstempel aus der Antwort und senken Sie während der Untersuchung die Parallelität.

Produktions-Checkliste vor dem Start

Eine funktionierende Anfrage ist der Anfang, nicht das Ende. Bevor dieser Endpunkt echten Datenverkehr verarbeitet, bestätigen Sie die folgenden Punkte.

Eingaben an den Grenzen validieren

Bevor die Anfrage Ihren Dienst verlässt, prüfen Sie Format und Größe des Referenzbildes, die Prompt-Länge sowie die Parameterwerte. Ungültige Eingaben lokal abzulehnen ist schneller, günstiger und erzeugt klarere Fehlermeldungen für Benutzer.

Nur sicher wiederholbare Anfragen wiederholen

Wiederholen Sie Transportfehler, Ratenbegrenzungen und 5xx-Antworten mit exponentiellem Backoff und Jitter. Wiederholen Sie keine Validierungs- oder Authentifizierungsfehler – sie schlagen auf dieselbe Weise fehl und erhöhen nur die Last.

Genug protokollieren, um Fehler zu rekonstruieren

Protokollieren Sie Modell-ID, einen Hash oder eine gekürzte Form des Prompts, den Bezeichner des Referenzbildes (nicht die vollständige Nutzlast), den Antwortstatus, die Job-ID (falls vorhanden) und die Anfrage-ID. Diese Angaben reichen in der Regel, um die Frage „was ist passiert“ zu beantworten, ohne sensible Inhalte zu speichern.

Schlüssel aus dem Code heraushalten

Lesen Sie den API-Schlüssel aus der Umgebung oder einem Secret-Manager, niemals aus einem Literal im Quellcode. Rotieren Sie Schlüssel regelmäßig und widerrufen Sie sie sofort, wenn Sie einen Verdacht auf Kompromittierung haben.

Das Kostenverhalten im Blick behalten

Die Abrechnung an diesem Endpunkt wird durch die Generierung gesteuert; die entscheidenden Hebel sind daher Anfragevolumen, Wiederholungen und Abfragehäufigkeit. Vermeiden Sie Wiederholungsstürme, verwenden Sie Backoff beim Abfragen und cachen Sie Ergebnisse nach Prompt und Referenzbild für Szenarien, in denen dieselbe Transformation wiederholt angefordert wird. Prüfen Sie das HiAPI-Preisdashboard auf die aktuellen Tarife, statt Annahmen hart zu codieren.

Die unglücklichen Pfade testen

Schreiben Sie Tests für ungültige Bild-URLs, Ratenbegrenzungsantworten und asynchrone Jobs, die nie abgeschlossen werden. Diese drei decken die Fehler ab, die am ehesten unbemerkt in die Produktion gelangen.

Mit solider Konstruktion der Anfrage, Verteilung der Antworten und Fehlerbehandlung wird grok-imagine/image-to-image zu einem regulären Teil Ihrer Pipeline statt zu einem Sonderfall.