So rufen Sie seedream-4.5/image-to-image über die HiAPI API auf: curl und Python

Was dieser Endpunkt tut und wann Sie ihn wählen

seedream-4.5/image-to-image verwandelt ein oder mehrere Referenzbilder zusammen mit einem Text-Prompt in ein neues Bild. Er gehört zur Bild-zu-Bild-Familie auf HiAPI: Sie liefern visuellen Kontext, und das Modell interpretiert ihn gemäß Ihren Anweisungen neu. Genau darin liegt der entscheidende Unterschied zur Text-zu-Bild-Generierung – dort ist der Prompt die einzige Eingabe, und das Modell erschafft alles aus dem Nichts.

Wählen Sie Bild-zu-Bild, wenn das visuelle Ergebnis an vorhandenem Material verankert bleiben soll: einen bestehenden Asset neu gestalten, Beleuchtung oder Hintergrund ändern und dabei Produktform und Layout erhalten, die Komposition iterieren, ohne das Motiv zu verlieren, oder eine Reihe von Ergebnissen konsistent halten, indem dieselben Referenzbilder wiederverwendet werden.

Wählen Sie Text-zu-Bild, wenn Sie kein Referenzmaterial haben und eine Szene nur mit Worten beschreiben möchten.

Dieser Endpunkt ist asynchron. Sie reichen eine Aufgabe ein, erhalten eine Kennung und fragen dann ab, bis die Aufgabe einen Endzustand erreicht, um anschließend die Ausgabe abzurufen. Planen Sie diesen Lebenszyklus von Anfang an ein; der Rest dieser Anleitung baut eine ausführbare Anfrage auf und härtet sie anschließend.

Eine ausführbare curl-Anfrage erstellen

Jede Anfrage an diesen Endpunkt hat dieselbe Grundstruktur. Gehen Sie Feld für Feld vor.

Endpunkt und Methode

Die Anfrage geht als POST an die Bild-zu-Bild-Route unter der HiAPI-Basis-URL, mit dem Modellbezeichner seedream-4.5/image-to-image. Der Modellname ist ein Wert im Anfrage-Payload, nicht Teil des Pfads.

Authentifizierung

Übergeben Sie Ihren HiAPI-API-Schlüssel als Bearer-Token im Authorization-Header. Bewahren Sie ihn in einer Umgebungsvariable auf, damit er nicht in der Shell-History oder in der Versionsverwaltung landet:

export HIAPI_API_KEY="your-key-here"

Minimaler Anfrage-Payload

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-4.5/image-to-image",
    "prompt": "restyle this photo as a warm studio portrait",
    "image": "https://example.com/reference.jpg"
  }'

Feld für Feld:

• model — der literale Bezeichner seedream-4.5/image-to-image.
• prompt — was mit dem Referenzbild geschehen soll. Beschreiben Sie den Transformationsprozess, nicht nur das Motiv.
• image — die Referenzeingabe. Bei einem einzelnen Bild ist dies ein Wert; der nächste Abschnitt behandelt mehrere Referenzbilder.

Die erste Antwort lesen

Der Aufruf liefert eine angenommene Aufgabe, nicht das fertige Bild. Erfassen Sie die Aufgabenkennung aus dem Antwort-Body und bewahren Sie sie auf; Sie benötigen sie beim Polling. Betrachten Sie einen Status im 200-Bereich nicht als „Bild ist fertig“.

Führen Sie diese Anfrage einmal unverändert aus, bevor Sie Client-Code schreiben. Ein Payload, der in curl scheitert, scheitert in Python aus denselben Gründen – und in der Shell lässt sich schneller debuggen.

Die Anfrage nach Python übertragen

Die Python-Version hält den Payload Byte für Byte identisch und ersetzt nur die Transportschicht und die Authentifizierungsbehandlung. Genau diese Trennung ist entscheidend: Wenn curl funktioniert, sollte Python beim ersten Versuch laufen.

import os
import requests

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

payload = {
    "model": "seedream-4.5/image-to-image",
    "prompt": "restyle this photo as a warm studio portrait",
    "image": "https://example.com/reference.jpg",
}

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

resp = requests.post(
    f"{BASE_URL}/v1/images/generations",
    json=payload,
    headers=headers,
    timeout=30,
)
resp.raise_for_status()
job = resp.json()
print(job["id"])

Diese Hinweise sparen später Zeit:

• Bauen Sie den Payload als Python-Dict, damit json= die Serialisierung übernimmt. Von Hand geschriebene JSON-Strings sind die Quelle von Anführungszeichenfehlern.
• Kapseln Sie die Authentifizierungslogik in einer Hilfsfunktion. Ändert sich das Header-Format, ändern Sie nur eine Stelle.
• Übergeben Sie auch beim Einreichungsaufruf stets ein explizites timeout. Ein hängender Socket beim Einreichen ist nicht von einem langsamen Modell zu unterscheiden.
• Speichern Sie die zurückgegebene Aufgabenkennung sofort, statt sie später aus Logs zu rekonstruieren.

Der Polling-Code in den folgenden Abschnitten verwendet dieselben BASE_URL, API_KEY und headers, daher sollten Sie sie im Modulbereich oder in einer kleinen Client-Klasse ablegen.

Mehrere Referenzbilder übergeben

Mehrere Referenzbilder sind der häufigste Fehlerquellen bei Bild-zu-Bild-Anfragen – meist weil das Modell drei Bilder erhält, der Prompt aber nur eines davon beschreibt.

Eingaben explizit organisieren

Legen Sie die Referenzbilder als Liste unter demselben image-Feld ab, in der gewünschten Reihenfolge, und lassen Sie den Prompt die Rolle jeder Position benennen:

payload = {
    "model": "seedream-4.5/image-to-image",
    "prompt": (
        "Use the first reference for the subject's pose, "
        "the second for the background setting, "
        "and the third for color grading. Keep the subject sharp."
    ),
    "image": [
        "https://example.com/pose.jpg",
        "https://example.com/background.jpg",
        "https://example.com/grading.jpg",
    ],
}

Warum Beschriftung besser ist als Position

Die Listenreihenfolge ist eine Konvention, aber der Prompt ist der Schlüssel, der dem Modell sagt, wie diese Reihenfolge zu interpretieren ist. Ein vager Array mit einem unklaren Prompt zwingt das Modell, zu raten, welches Bild bei Konflikten Vorrang hat. Die Rolle jedes Bildes im Prompt zu benennen, verwandelt implizite Positionsannahmen in explizite Anweisungen.

Praktische Regeln:

• Halten Sie die Anzahl der Referenzbilder klein, und geben Sie jedem einen klaren Zweck. Überflüssige Referenzen verdünnen das Ergebnis, statt es zu bereichern.
• Legen Sie die Konfliktlösung fest: Wenn Posen- und Hintergrundreferenz in der Bildkomposition nicht zusammenpassen, geben Sie an, welches Bild Vorrang hat.
• Verwenden Sie stabile, öffentlich zugängliche URLs oder einen gleichwertigen Upload-Mechanismus. Eine Referenz, die mitten in der Aufgabe einen 404 zurückgibt, lässt die gesamte Anfrage scheitern.

Wenn die Ausgabe ein Referenzbild ignoriert, besteht die übliche Lösung nicht darin, das Modell erneut aufzurufen, sondern die Rolle dieses Bildes in einem klareren Prompt-Satz zu benennen.

Den asynchronen Aufgabenlebenszyklus behandeln

Die Bildgenerierung dauert, daher ist dieser Endpunkt aufgabenbasiert. Betrachten Sie den Lebenszyklus als vier getrennte Schritte und schreiben Sie Code für jeden einzeln.

1. Einreichen

Senden Sie den zuvor gezeigten POST. Bevor Sie irgendetwas anderes tun, persistieren Sie die Aufgabenkennung aus der Antwort.

2. Polling

Senden Sie mit denselben Authentifizierungs-Headern einen GET-Aufruf an die Aufgabenroute, bis der Status einen Endzustand erreicht:

import time

def poll_job(job_id, interval=2.0, max_interval=30.0, deadline=300.0):
    start = time.monotonic()
    while True:
        r = requests.get(
            f"{BASE_URL}/v1/images/generations/{job_id}",
            headers=headers,
            timeout=30,
        )
        r.raise_for_status()
        data = r.json()
        status = data["status"]
        if status in ("succeeded", "failed"):
            return data
        if time.monotonic() - start > deadline:
            raise TimeoutError(f"job {job_id} not finished within {deadline}s")
        time.sleep(interval)
        interval = min(interval * 2, max_interval)

3. Endzustände erkennen

Nur zwei Ergebnisse beenden die Schleife: Erfolg oder Fehlschlag. Alles andere bedeutet weiter warten. Gehen Sie niemals davon aus, dass die Ausgabe sofort verfügbar ist, und legen Sie niemals eine feste Anzahl von Polling-Versuchen ohne tatsächliche Zeitfrist fest.

4. Ergebnis abrufen

Dies wird im nächsten Abschnitt behandelt.

Backoff ist wichtig. Eine enge sleep(0.1)-Schleife verbraucht Ihr Ratenbudget mit Statusprüfungen. Bei etwa zwei Sekunden beginnen und bis zu einer Obergrenze verdoppeln hält die Latenz niedrig, ohne die API zu überfluten.

Ausgabe abrufen und speichern

Wenn das Polling einen Erfolgsstatus zurückgibt, enthält die Antwort eine Ausgabereferenz. Zurückgegeben wird ein Zeiger auf das generierte Bild, nicht unbedingt die Bytes selbst.

Bewusst herunterladen

data = poll_job(job_id)
url = data["output"][0]["url"] if isinstance(data["output"], list) else data["output"]

with requests.get(url, stream=True, timeout=60) as r:
    r.raise_for_status()
    with open(f"{job_id}.png", "wb") as f:
        for chunk in r.iter_content(chunk_size=8192):
            f.write(chunk)

Passen Sie den Pfad an die tatsächliche Antwortstruktur an, die Sie beim ersten echten Task beobachten, statt ein festes Schema anzunehmen.

Speicherregeln, die Nacharbeit vermeiden

• Benennen Sie Dateien nach der Aufgabenkennung. Sie ist eindeutig, nachvollziehbar und verknüpft das Artefakt mit der Anfrage, die es erzeugt hat.
• Laden Sie zeitnah herunter. Ausgabelinks können zeitlich begrenzt sein, daher sollten Sie sofort nach erfolgreichem Polling persistieren, statt die URL für später zwischenzuspeichern.
• Streamen Sie große Dateien, statt sie vollständig in den Speicher zu laden.
• Protokollieren Sie Prompt und Referenzbildliste zusammen mit der Datei. Wenn die Ausgabe unerwartet ist, sind die Eingaben der Debug-Datensatz.

Wenn Sie deterministische Wiederholungen benötigen, bedeutet das Speichern der Aufgabenkennung, dass Sie erneut pollen oder erneut herunterladen können, ohne für eine zweite Generierung zu bezahlen.

Fehler, Wiederholungen und Kostenkontrolle

Die meisten Fehler fallen in drei Kategorien, die jeweils eine andere Behandlung erfordern.

Client-Fehler

Fehlerhafter Payload, fehlendes model, nicht erreichbare Referenzbild-URL oder falscher Schlüssel. Diese Fehler werden sofort zurückgegeben und würden bei Wiederholung erneut zurückgegeben. Korrigieren Sie die Anfrage; wiederholen Sie nicht in einer Schleife. Prüfen Sie vor dem Einreichen, ob die Referenzbild-URL auflösbar ist.

Temporäre Server- und Netzwerkfehler

Timeouts, Verbindungsabbrüche, Rate-Limit-Antworten. Diese verdienen Wiederholungen mit exponentiellem Backoff und Jitter, begrenzt auf eine kleine maximale Anzahl von Versuchen. Wiederholen Sie den spezifischen Schritt – Einreichen, Polling oder Herunterladen – und nicht die gesamte Pipeline. Das erneute Einreichen nach einem erfolgreichen Einreichen ist genau der Weg zu versehentlicher doppelter Bezahlung.

Fehler auf Aufgabenebene

Die Aufgabe erreicht einen Fehler-Endzustand. Die gleiche Aufgabenkennung erneut zu versuchen, hilft nicht. Entscheiden Sie ausdrücklich, ob Sie mit geändertem Prompt oder geändertem Referenzbildsatz erneut einreichen, und protokollieren Sie den Fehlergrund, um Eingabefehler von temporären Störungen zu unterscheiden.

def with_retries(fn, attempts=4, base=1.0):
    for i in range(attempts):
        try:
            return fn()
        except requests.RequestException:
            if i == attempts - 1:
                raise
            time.sleep(base * (2 ** i))

Kostenkontrolle

Die Abrechnung ist an die Generierung gebunden, daher sind doppelte Einreichungen der teure Fehler. Setzen Sie eine tatsächliche Zeitfrist für das Polling durch, halten Sie die Einreichung idempotent, indem Sie die Aufgabenkennung vor dem Polling speichern, und begrenzen Sie die Parallelität, damit ein Wiederholungssturm nicht zu Dutzenden abgerechneten Aufgaben anwächst. Protokollieren Sie jede Einreichung mit ihrer Aufgabenkennung; dieses Log ist Ihr Ausgaben-Audit-Trail.

Wenn Sie diese drei Belange einmal im Client verankern, kann derselbe Code Anfragen mit einem und mit mehreren Referenzbildern ohne Änderung verarbeiten.