Tutorial

So verwenden Sie seedream-4.5/image-to-image über die hiapi API: curl, Python und verfügbare Anfragen

Jul 10, 2026

Um ein Bild mit seedream-4.5 zu bearbeiten, senden Sie einfach ein POST an die einheitliche Aufgaben-API von hiapi, führen einen kurzen Polling-Durchlauf durch und laden dann das Ergebnis herunter. Dieser Leitfaden bietet funktionierende curl-Anfragen und ein vollständiges Python-Skript für seedream-4.5/image-to-image, dazu eine präzise Beschreibung der Eingabefelder (gegen die Live-API verifiziert), die Verwendung mehrerer Referenzbilder und die Fehler, auf die Sie tatsächlich stoßen werden.

Was Sie bauen und was Sie benötigen

Ziel: Ein oder mehrere Quellbilder zusammen mit einer Bearbeitungsanweisung an seedream-4.5/image-to-image senden und die URL des fertigen Bildes zurückerhalten.

Voraussetzungen:

Ein hiapi-API-Schlüssel – zu erhalten in Ihrer Konsole. Jede der folgenden Anfragen verwendet ihn als Bearer-Token.
Quellbilder, die unter einer öffentlich zugänglichen URL gehostet werden. Die API ruft sie serverseitig ab; lokale Dateipfade oder private URLs funktionieren nicht.

Das Modell läuft auf dem asynchronen Aufgaben-Endpunkt: POST /v1/tasks erstellt eine Aufgabe, GET /v1/tasks/<taskId> meldet den Status, und das fertige Bild erscheint in data.output[0].url.

Beschreibung der Eingabefelder (verifiziert)

seedream-4.5/image-to-image hat vier Pflicht-Eingabefelder und akzeptiert keine weiteren – die Feldspezifikation ist strikt, unbekannte Felder werden mit 400 abgelehnt:

Feld	Typ	Einschränkung
`prompt`	string	Bearbeitungsanweisung
`image_urls`	String-Array	Öffentliche URLs, maximal 14 Bilder
`aspect_ratio`	string	Einer von `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `2:3`, `3:2`, `21:9`
`resolution`	string	Nur `2K` oder `4K`

Zwei Dinge sind erwähnenswert: Es gibt keinen n-Parameter (eine Ausgabe pro Aufgabe – für mehrere Varianten bitte mehrere Aufgaben parallel erstellen); und anders als bei seedream-5.0-pro image-to-image (das 1K/2K akzeptiert) verlangt 4.5 2K oder 4K. Wird hier 1K gesendet, gibt es einen Validierungsfehler.

Minimal funktionierende Anfrage: curl

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-4.5/image-to-image",
    "input": {
      "prompt": "Turn this product shot into a clean studio photo on a seamless white background with soft shadows",
      "image_urls": ["https://your-cdn.example.com/source.jpg"],
      "aspect_ratio": "1:1",
      "resolution": "2K"
    }
  }'

Bei erfolgreicher Erstellung wird die Aufgaben-ID in data.taskId zurückgegeben. Fragen Sie sie per Polling ab:

curl -s https://api.hiapi.ai/v1/tasks/<taskId> \
  -H "Authorization: Bearer sk-<your-key>"

Wenn data.status den Wert success erreicht, steht die Bild-URL in data.output[0].url. Bei fail steht der Grund in data.error.

Vollständiges Python-Skript

Kein SDK erforderlich – nur requests und eine Polling-Schleife:

import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
API_KEY = "sk-<your-key>"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def edit_image(prompt: str, image_urls: list[str],
               aspect_ratio: str = "1:1", resolution: str = "2K") -> bytes:
    # 1. Create the task
    resp = requests.post(API_BASE, headers=HEADERS, json={
        "model": "seedream-4.5/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": image_urls,   # public URLs, max 14
            "aspect_ratio": aspect_ratio,
            "resolution": resolution,   # "2K" or "4K"
        },
    }, timeout=60)
    resp.raise_for_status()
    task_id = resp.json()["data"]["taskId"]

    # 2. Poll until terminal state
    deadline = time.time() + 600
    while time.time() < deadline:
        task = requests.get(f"{API_BASE}/{task_id}",
                            headers=HEADERS, timeout=30).json()["data"]
        if task["status"] == "success":
            url = task["output"][0]["url"]
            # 3. Output URLs expire -- download immediately
            return requests.get(url, timeout=120).content
        if task["status"] == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(5)
    raise TimeoutError(f"task {task_id} did not finish in 600s")

png = edit_image(
    "Turn this product shot into a clean studio photo on a seamless white background",
    ["https://your-cdn.example.com/source.jpg"],
)
with open("edited.png", "wb") as f:
    f.write(png)

Beachten Sie den Kommentar in Schritt 3: Ausgabe-URLs tragen einen Ablaufzeitstempel. Sobald eine Aufgabe erfolgreich ist, sollten Sie die Bytes sofort in Ihrem eigenen Speicher persistieren – speichern Sie nicht nur die zurückgegebene URL und gehen Sie davon aus, dass sie morgen noch funktioniert.

Bearbeitung mit mehreren Referenzbildern

image_urls akzeptiert in einer Aufgabe bis zu 14 Bilder. Das ist ein starkes Werkzeug für Stiltransfers und Kompositionsaufgaben: Übergeben Sie das zu bearbeitende Bild sowie Referenzbilder und beschreiben Sie im Prompt, wie sie kombiniert werden sollen.

{
  "model": "seedream-4.5/image-to-image",
  "input": {
    "prompt": "Apply the color grading and lighting style of the second image to the first image, keep the subject unchanged",
    "image_urls": [
      "https://your-cdn.example.com/subject.jpg",
      "https://your-cdn.example.com/style-reference.jpg"
    ],
    "aspect_ratio": "3:2",
    "resolution": "2K"
  }
}

Die Reihenfolge ist für den Prompt von Bedeutung, nicht für die API – verweisen Sie deshalb positional auf die Bilder ("das erste Bild", "das zweite Bild"), damit das Modell weiß, welches welches ist.

Hinweise für den Produktionseinsatz

Verwenden Sie Callbacks statt Polling. Für alles außerhalb von Skripten fügen Sie beim Erstellen der Aufgabe ein callback-Objekt auf oberster Ebene hinzu und überspringen die Polling-Schleife vollständig:

{
  "model": "seedream-4.5/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://yourapp.com/hooks/hiapi", "when": "final" }
}

Wenn die Aufgabe abgeschlossen ist, sendet hiapi den finalen Status der Aufgabe per POST an Ihre URL. Polling eignet sich für CLI-Tools und Notebooks; für ein Web-Backend ist der Callback die richtige Wahl – sonst halten Sie einen Worker-Prozess für die Dutzenden Sekunden blockiert, die eine 2K-Bearbeitung benötigt.

Idempotenz. Die Aufgabenerstellung ist nicht idempotent – ein erneuter Erstellungsversuch nach einem Netzwerk-Timeout kann zwei Aufgaben erzeugen (und abrechnen). Speichern Sie die taskId in dem Moment, in dem Sie sie erhalten, und prüfen Sie bei Wiederholungen zuerst, ob bereits eine aktive Aufgabe existiert, bevor Sie eine neue erstellen.

Fehlerbehandlung. Die beiden Fehlerarten, auf die Sie zuerst stoßen werden:

401 permission_denied – falscher Schlüssel oder der Schlüssel hat keinen Zugriff auf dieses Modell. Der Antworttext ähnelt {"error": {"code": "permission_denied", "message": "This API key cannot use the selected model...", "request_id": "..."}}. Bitte geben Sie beim Support-Kontakt die request_id an.
400 INVALID_REQUEST – Verstoß gegen die Feldspezifikation, mit präziser Meldung: falscher resolution-Wert, mehr als 14 Einträge in image_urls, unbekanntes Feld oder image_urls ist kein Array. Diese werden vor dem Start der Aufgabe abgefangen, sodass keine Kosten entstehen.

Fehlgeschlagene Aufgaben melden auf der Aufgabe selbst status: "fail" mit einem error-Objekt – behandeln Sie dies als anderen Fall als HTTP-Fehler, wie es das obige Python-Skript tut.

Preisgestaltung

Die Kosten pro Bild hängen von der Auflösung ab. Die aktuellen Tarife finden Sie auf der Preisseite. Anfragen, die in der Validierungsphase abgelehnt werden (400), starten nie eine Aufgabe, daher sind Fehler in der Feldspezifikation während der Integration kostenlos.

Häufig gestellte Fragen

Kann ich lokale Dateien oder base64-Bilder statt URLs übergeben? Nein. image_urls muss ein Array öffentlich zugänglicher URLs sein – die Plattform ruft sie serverseitig ab und normalisiert sie. Laden Sie sie zuerst in Ihren eigenen Speicher hoch (S3, R2, beliebiges CDN) und übergeben Sie dann die URL.

Wie viele Referenzbilder unterstützt seedream-4.5 image-to-image? Bis zu 14 pro Aufgabe. Darüber hinaus wird ein 400 zurückgegeben, dessen Meldung image_urls: maxItems enthält.

Warum erhalte ich ein 400, wenn ich resolution auf 1K setze? Der Endpunkt von 4.5 image-to-image akzeptiert nur 2K oder 4K. Die Option 1K gehört zu seedream-5.0-pro image-to-image – verschiedene Stufen-Serien haben unterschiedliche Enumerationen.

Kann ich mehrere Varianten in einer Anfrage erzeugen? Nein – die Feldspezifikation enthält keinen n-Parameter und lehnt unbekannte Felder ab. Erstellen Sie für jede Variante eine Aufgabe und führen Sie sie parallel aus; jede Aufgabe liefert nur eine Ausgabe.

Wie lange sind Ergebnis-URLs gültig? Ausgabe-URLs tragen eine Signatur und eine Ablaufzeit. Laden Sie das Bild nach erfolgreicher Aufgabe sofort herunter und speichern Sie es selbst, statt die Aufgabenausgabe zu hotlinken.

Was ist der Unterschied zwischen einem HTTP-Fehler und einer fehlgeschlagenen Aufgabe? Ein HTTP-Fehler (400/401) bedeutet, dass die Anfrage nie zu einer Aufgabe wurde – korrigieren Sie die Payload oder den Schlüssel und senden Sie erneut. Eine Aufgabe, die mit status: "fail" endet, wurde angenommen, konnte aber nicht abgeschlossen werden; der Grund steht im error-Objekt der Aufgabe, und bei transienten Fehlern ist ein erneuter Versuch mit denselben Eingaben in der Regel richtig.