So rufen Sie muse-image-1.0/image-to-image auf der HiAPI API auf: curl, Python und ein funktionierendes Anfragebeispiel

Was eine Image-to-Image-Anfrage tatsächlich sendet

Bevor Sie die erste Codezeile schreiben, ist es hilfreich zu verstehen, was ein Image-to-Image-Aufruf erwartet. Anders als bei reinen Text-to-Image-Anfragen, bei denen der Prompt die einzige kreative Eingabe ist, benötigt muse-image-1.0/image-to-image ein Quellbild sowie Anweisungen, wie es umgewandelt werden soll.

Minimal umfasst Ihre Anfrage-Payload:

• model: der Bezeichner muse-image-1.0/image-to-image.
• image: das Quellbild, das Sie bearbeiten möchten. Dies wird üblicherweise als base64-kodierter String oder als öffentlich zugängliche URL gesendet, je nachdem, welche Form der Endpunkt akzeptiert. Prüfen Sie das Eingabe-Schema des Modells, um den genauen Feldnamen und das Format zu bestätigen.
• prompt: eine Textbeschreibung der gewünschten Bearbeitung. Geben Sie konkret an, was geändert und was beibehalten werden soll.
• Optionale Parameter wie strength oder guidance (falls das Modell sie bereitstellt) ermöglichen es Ihnen, zu steuern, wie stark die Ausgabe vom Quellbild abweicht. Der genaue Parametersatz variiert je nach Modell, daher sollten Sie ihn stets anhand der API-Referenz prüfen, statt ihn anzunehmen.

Die entscheidende mentale Umstellung ist: Sie generieren nicht von Grund auf, sondern liefern einen Ausgangspunkt und eine Richtung. Vage Prompts wie "make it better" führen zu unvorhersehbaren Ergebnissen, weil das Modell zu viele Freiheiten hat. Ein Prompt wie "replace the sky with a sunset and keep the buildings unchanged" gibt dem Modell dagegen eine klare Einschränkung.

Prüfen Sie außerdem vorab die Bildbeschränkungen – unterstützte Formate, maximale Abmessungen und Dateigröße. Wenn Ihr Quellbild ein 12 MB großes PNG ist, müssen Sie es möglicherweise zuerst herunterskalieren oder in JPEG konvertieren, damit die Anfrage akzeptiert wird. Die korrekte Vorverarbeitung des Bildes vor dem Senden erspart Ihnen einen Roundtrip und eine verwirrende Fehlermeldung.

Sobald Sie ein Quellbild und einen klaren Bearbeitungs-Prompt haben, können Sie den ersten Aufruf durchführen.

Die erste Anfrage mit curl senden

Der schnellste Weg, die Integration zu validieren, ist, die Anfrage direkt vom Terminal aus zu senden. Der genaue Endpunktpfad und das Payload-Schema sind in der API-Referenz des Modells definiert; das folgende Beispiel zeigt die allgemeine Form, damit Sie es an die aktuelle Spezifikation anpassen können.

curl -X POST https://api.hiapi.ai/v1/images/edits \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "muse-image-1.0/image-to-image",
    "image": "https://your-bucket.example.com/source.jpg",
    "prompt": "replace the sky with a warm sunset, keep the buildings unchanged",
    "strength": 0.6
  }'

Ersetzen Sie $HIAPI_API_KEY durch eine Umgebungsvariable, anstatt den Schlüssel direkt einzufügen. Exportieren Sie den Schlüssel in Ihrer Shell-Sitzung, falls Ihr Tool dies unterstützt, damit er nicht in der Befehlsverlauf verbleibt.

Die zurückgegebene Antwort enthält eine Job-ID. Da Bildbearbeitung rechenintensiv ist, gibt die API das fertige Bild normalerweise nicht in derselben Antwort zurück. Stattdessen erhalten Sie eine Job-ID und einen Status. Speichern Sie diese ID – im nächsten Schritt werden Sie damit die Ergebnisse abrufen.

Wenn der Aufruf fehlschlägt, lesen Sie den Fehlerantworttext sorgfältig. Ein 400 bedeutet normalerweise, dass die Payload fehlerhaft ist oder das Bildformat nicht unterstützt wird. Ein 401 bedeutet, dass der Schlüssel fehlt oder falsch ist. Ein 429 bedeutet, dass Sie Anfragen zu schnell senden. Diese Probleme im Terminal-Stadium zu beheben ist viel einfacher, als sie in einer vollständigen Anwendung zu debuggen.

Dieselbe Anfrage in Python

Sobald der curl-Aufruf erfolgreich ist, wandeln Sie ihn in eine kleine Python-Funktion um. Die Verwendung von requests hält das Beispiel abhängigkeitsarm und leicht portierbar.

import os
import requests

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

def submit_edit(image_url: str, prompt: str, strength: float = 0.6) -> str:
    payload = {
        "model": "muse-image-1.0/image-to-image",
        "image": image_url,
        "prompt": prompt,
        "strength": strength,
    }
    headers = {
        "Authorization": f"Bearer {HIAPI_API_KEY}",
        "Content-Type": "application/json",
    }
    response = requests.post(BASE_URL, json=payload, headers=headers, timeout=30)
    response.raise_for_status()
    data = response.json()
    return data["id"]

Einige Anmerkungen zu dieser Funktion:

• Der Parameter timeout verhindert, dass das Skript bei einer Netzwerkblockade unbegrenzt hängt. Für einen Submit-Aufruf sind 30 Sekunden großzügig, können aber nach Bedarf angepasst werden.
• raise_for_status() wandelt HTTP-Fehler in Ausnahmen um, sodass Sie sie an einer Stelle abfangen können.
• Nur die Job-ID zurückzugeben hält die Funktion fokussiert. Die Polling-Logik sollte in einer separaten Funktion untergebracht werden.

Wenn Sie das Quellbild lieber als Bytes statt als URL senden möchten, lesen Sie die Datei ein, kodieren Sie sie in base64 und legen Sie das Ergebnis in das Feld image. Bestätigen Sie vor dem Wechsel das in der Dokumentation erwartete Format, da diese beiden Kodierungen nicht immer austauschbar sind.

Diese Funktion ist bewusst minimal gehalten. In einem echten Service würden Sie Logging, Retry-Handling und Typvalidierung hinzufügen, aber das Kern-Anfragemuster ist genau das, was Sie hier sehen.

Asynchrone Jobs behandeln und Ergebnisse abrufen

Bildbearbeitung braucht Zeit – je nach Prompt und Auflösung in der Regel zwischen einigen Sekunden und mehreren Dutzend Sekunden. Die API handhabt dies, indem sie Ihre Anfrage annimmt, eine Job-ID zurückgibt und die Arbeit im Hintergrund ausführt. Ihre Aufgabe ist es, wiederholt zu prüfen, bis der Status einen Endzustand erreicht.

Polling klingt einfach, aber eine naive Schleife, die alle 100 Millisekunden ausgelöst wird, verschwendet Kontingent und kann Rate-Limits auslösen. Verwenden Sie ein vernünftiges Intervall und eine Obergrenze für Wiederholungen:

import time
import requests

def poll_job(job_id: str, interval: float = 2.0, max_attempts: int = 30) -> dict:
    url = f"https://api.hiapi.ai/v1/jobs/{job_id}"
    headers = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}
    for attempt in range(max_attempts):
        response = requests.get(url, headers=headers, timeout=15)
        response.raise_for_status()
        data = response.json()
        status = data["status"]
        if status == "succeeded":
            return data
        if status == "failed":
            raise RuntimeError(data.get("error", "job failed"))
        time.sleep(interval)
    raise TimeoutError(f"job {job_id} did not finish after {max_attempts} attempts")

Ein Intervall von zwei Sekunden ist ein vernünftiger Ausgangspunkt. Wenn Ihre Jobs normalerweise innerhalb von fünf Sekunden abgeschlossen sind, können Sie anfangs häufiger pollen und dann schrittweise zurückgehen. Wenn sie in der Regel länger dauern, senken Sie die Polling-Frequenz, um unnötige Aufrufe zu vermeiden.

Die Obergrenze für Wiederholungen ist Ihr Sicherheitsnetz. Ohne sie könnte ein hängender Job eine Endlosschleife verursachen. Wenn die Obergrenze erreicht ist, werfen Sie einen klaren Fehler, damit der Aufrufer weiß, dass der Vorgang abgelaufen ist, anstatt stillschweigend zu hängen.

In einer Produktionsumgebung sollten Sie erwägen, das Polling in einen Hintergrund-Worker oder eine Queue zu verlagern, damit Ihr Anforderungsverarbeitungs-Thread nicht blockiert wird, während er auf das Rendern des Bildes wartet.

Das Ausgabebild herunterladen und speichern

Wenn der Job den Status succeeded erreicht, enthält die Antwort ein oder mehrere Ausgabebilder, üblicherweise als URLs bereitgestellt. Ihr nächster Schritt ist, die Bilder herunterzuladen und dauerhaft zu speichern.

def download_image(result: dict, dest_path: str) -> None:
    image_url = result["output"][0]["url"]
    response = requests.get(image_url, timeout=30)
    response.raise_for_status()
    with open(dest_path, "wb") as f:
        f.write(response.content)

Einige praktische Überlegungen:

• Ausgabe-URLs können temporär sein. Behandeln Sie sie als kurzlebige Ressourcen und laden Sie sie zeitnah herunter, anstatt die URL als einzige Referenz zu speichern.
• Schreiben Sie Dateien im Binärmodus. Bildantworten sind kein Text; das Öffnen mit "w" würde die Daten beschädigen.
• Überprüfen Sie vor dem Erfolgsausruf, dass die Datei nicht leer ist. Ein Download von null Bytes bedeutet normalerweise, dass die URL abgelaufen ist oder die Anfrage blockiert wurde.

Für alles, was über ein lokales Skript hinausgeht, streamen Sie den Download direkt zu Ihrem Speicheranbieter, anstatt ihn zuerst auf die Festplatte zu speichern. Die meisten Object-Storage-SDKs akzeptieren dateiähnliche Objekte oder Byte-Streams, sodass Sie response.raw oder response.content direkt in den Upload-Aufruf weiterleiten können, ohne eine Zwischendatei.

Protokollieren Sie abschließend die Job-ID zusammen mit dem gespeicherten Objekt. Wenn die Ausgabe später beschädigt wird oder Sie eine bestimmte Bearbeitung reproduzieren müssen, ermöglichen Ihnen die Job-ID plus die ursprünglichen Eingaben, nachzuvollziehen, was gesendet wurde.

Häufige Fehlerquellen und ihre Behebung

Die meisten Integrationsprobleme fallen in einige wenige Kategorien. So diagnostizieren Sie jede davon.

Anfrage wird vor der Job-Erstellung abgelehnt

Ein 400-Fehler beim Senden deutet normalerweise auf eine fehlerhafte Payload hin. Prüfen Sie, ob model exakt muse-image-1.0/image-to-image ist, ob image zugänglich oder korrekt base64-kodiert ist und ob prompt ein nicht-leerer String ist. Wenn das Bild eine URL ist, bestätigen Sie, dass es öffentlich zugänglich ist – ein privater Bucket oder eine abgelaufene signierte URL wird die Validierung nicht bestehen.

Job schlägt während der Verarbeitung fehl

Wenn das Polling den Status failed zurückgibt, lesen Sie die Fehlermeldung im Antworttext. Häufige Ursachen sind ein zu großes Bild, ein Prompt, der gegen die Inhaltsrichtlinie verstößt, oder Parameterwerte außerhalb des erlaubten Bereichs. Verkleinern Sie das Bild und vereinfachen Sie den Prompt, um die Ursache einzugrenzen.

Polling-Timeout

Wenn Sie die Obergrenze für Wiederholungen erreichen, ohne einen Endzustand zu erhalten, benötigt der Job möglicherweise tatsächlich mehr Zeit oder er hängt. Erhöhen Sie zunächst max_attempts und prüfen Sie anhand der API-Referenz die typische Verarbeitungszeit. Wenn der Job weiterhin Timeouts hat, prüfen Sie, ob das Quellbild ungewöhnlich groß ist. Entfernen Sie nicht einfach die Obergrenze für Wiederholungen – begrenzte Wiederholungen verhindern stille Endlosschleifen.

Rate-Limits

Eine 429-Antwort bedeutet, dass Sie Anfragen zu schnell senden. Gehen Sie zurück, beachten Sie etwaige retry-after-Header und staffeln Sie gleichzeitige Übermittlungen. Wenn Sie einen Stapel von Bildern verarbeiten, verarbeiten Sie sie sequenziell oder mit einem kleineren Parallelitätslimit, anstatt alle auf einmal zu senden.

Ausgabe fehlt oder ist abgeschnitten

Wenn der Job erfolgreich ist, aber die heruntergeladene Datei leer ist, ist die Ausgabe-URL möglicherweise zwischen Polling und Download abgelaufen. Laden Sie direkt nach dem Erfolg herunter. Wenn das Bild beschädigt ist, bestätigen Sie, dass Sie im Binärmodus schreiben und keine Textkodierung auf den Stream angewendet haben.

Das Debuggen ist einfacher, wenn Sie die Anfrage-Payload, die Job-ID und die Statusübergänge protokollieren. Mit diesen drei Informationen lässt sich fast jeder Fehler bis zur Quelle zurückverfolgen.

Mit der Anfrageform, den curl- und Python-Mustern, der Polling-Logik und dem Download-Schritt verfügen Sie über eine funktionierende Pipeline zur Verwendung von muse-image-1.0/image-to-image auf der HiAPI API. Beginnen Sie mit dem Terminal-Beispiel, verschieben Sie es in ein Skript und fügen Sie erst dann Wiederholungen und Logging hinzu, wenn der normale Pfad stabil ist.