So verwendest du seedream-5.0-pro/image-to-image über die hiapi API: curl, Python und ein lauffähiges Anfragebeispiel

Seedream 5.0 Pro ist das Flaggschiff-Bildmodell von ByteDance. Sein Image-to-Image-Endpunkt nimmt ein oder mehrere Referenzbilder sowie eine Textanweisung entgegen und liefert ein bearbeitetes Ergebnis zurück – neu gestylte Bilder, ausgetauschte Hintergründe, bereinigte Produktfotos, Kompositionen aus mehreren Bildern. Auf hiapi läuft es über die einheitliche asynchrone tasks-API: Du erstellst zunächst eine Aufgabe, fragst dann per Polling ab (oder empfängst einen Callback) und lädst schließlich die Ausgabe herunter. Jeder Parameter, jeder Enum-Wert und jede Fehlermeldung in diesem Leitfaden wurde vor der Veröffentlichung gegen die Live-API verifiziert.

Was du baust und was du vorbereiten musst

Ziel: Sende ein Referenzbild und eine Bearbeitungsanweisung an seedream-5.0-pro/image-to-image, hole das bearbeitete Bild zurück und speichere es lokal.

Du brauchst zwei Dinge:

1. Einen hiapi API-Schlüssel – erhältlich in deiner Konsole. Er muss im Request-Header Authorization: Bearer sk-... übergeben werden.
2. Öffentlich erreichbare Bild-URLs – die API ruft deine Referenzbilder serverseitig ab, daher müssen sie über HTTPS erreichbar sein. Vorsignierte URLs aus deinem eigenen Bucket funktionieren einwandfrei; localhost oder private Pfade dagegen nicht. Wenn eine URL nicht abgerufen werden kann, erhältst du einen normalisierten Fehler statt eines stillen Fehlschlags.

Parameter (verifiziert)

Die Modell-ID lautet seedream-5.0-pro/image-to-image und entspricht exakt dem, was GET /v1/models zurückgibt. Alle vier Eingabefelder sind Pflichtfelder:

Feld	Typ	Pflicht	Werte / Beschreibung
prompt	string	ja	Die Bearbeitungsanweisung.
image_urls	String-Array	ja	1–10 öffentlich erreichbare Bild-URLs. Immer ein Array, auch bei nur einem Bild.
aspect_ratio	string	ja	match_input_image, 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 21:9
resolution	string	ja	1K oder 2K

Zwei Stolperfallen:

• Das Schema ist strikt. Unbekannte Felder werden abgelehnt – sendest du n, size oder seed, erhältst du einen 400-Fehler mit additional properties ... not allowed. Auf hiapi unterscheidet sich das Eingabe-Schema jedes Modells (manche Modelle verwenden size, andere aspect_ratio), also kopiere Felder nicht zwischen Modellfamilien.
• resolution unterstützt hier nur 1K/2K. Andere seedream-Endpunkte akzeptieren unterschiedliche Auflösungssätze, daher lohnt es sich, jeden Endpunkt einzeln zu prüfen, statt es anzunehmen.

Minimales lauffähiges Beispiel: curl

Aufgabe erstellen:

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

Bei erfolgreicher Erstellung wird die Aufgaben-ID in data.taskId zurückgegeben (Antwort vereinfacht):

{ "data": { "taskId": "<your-task-id>" } }

Per Polling abfragen, bis die Aufgabe einen Endzustand erreicht:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

data.status wird schließlich success – deine Bild-URL findest du in data.output[0].url – oder fail, wobei Details in data.error.code und data.error.message stehen.

Vollständiges Python-Skript: Erstellen, Polling, Herunterladen

Nur mit der Standardbibliothek – nichts zu installieren:

import json
import time
import urllib.request

API = "https://api.hiapi.ai/v1/tasks"
KEY = "sk-YOUR_KEY"


def call(url, payload=None):
    req = urllib.request.Request(
        url,
        data=json.dumps(payload).encode() if payload is not None else None,
        headers={
            "Authorization": f"Bearer {KEY}",
            "Content-Type": "application/json",
        },
        method="POST" if payload is not None else "GET",
    )
    with urllib.request.urlopen(req) as resp:
        return json.load(resp)


# 1. Erstelle die Bearbeitungsaufgabe
create = call(API, {
    "model": "seedream-5.0-pro/image-to-image",
    "input": {
        "prompt": "Restyle this living room as a Scandinavian interior, keep the layout and window positions",
        "image_urls": ["https://your-bucket.example.com/room.jpg"],
        "aspect_ratio": "match_input_image",
        "resolution": "2K",
    },
})
task_id = create["data"]["taskId"]
print("task created:", task_id)

# 2. Polling bis zum Endzustand
while True:
    task = call(f"{API}/{task_id}")["data"]
    if task["status"] == "success":
        break
    if task["status"] == "fail":
        err = task.get("error") or {}
        raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
    time.sleep(5)

# 3. Sofort herunterladen -- Ausgabe-URLs laufen ab
image_url = task["output"][0]["url"]
urllib.request.urlretrieve(image_url, "edited.png")
print("saved edited.png")

Hinweise für den Produktivbetrieb

Bevorzuge auf Servern Callbacks statt Polling. Füge beim Erstellen der Aufgabe ein Objekt callback auf oberster Ebene hinzu, und hiapi sendet einmalig einen POST an deinen Endpunkt, sobald ein Endzustand erreicht ist:

{
  "model": "seedream-5.0-pro/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://your-server.example.com/hiapi-hook", "when": "final" }
}

Behandle den Callback in deinem Handler als Signal, nicht als Wahrheitsquelle: Nimm die Aufgaben-ID daraus, frage dann selbst erneut GET /v1/tasks/<id> ab und handle erst danach. Für Skripte, Notebooks und einmalige Aufgaben bleibt Polling die richtige Wahl – halte das Intervall einfach bei etwa 5 Sekunden.

Mache Wiederholungsversuche idempotent. Speichere beim Erstellen einer Aufgabe deine eigene Zuordnung von Quellbild → taskId. Wenn der Prozess mitten im Polling abstürzt, ordne ihn der gespeicherten taskId wieder zu, statt die Bearbeitung erneut einzureichen – eine erneute Einreichung erzeugt eine zweite abgerechnete Aufgabe.

Lade Ausgaben sofort herunter. Die URL in data.output[0].url ist zeitlich begrenzt (mit Ablaufzeit). Lade die Bytes herunter und speichere sie in deinem eigenen Bucket; verlinke die Ausgabe-URLs von Aufgaben niemals direkt in benutzerseitigen Inhalten.

Fehler, die dir tatsächlich begegnen werden:

• 401 mit permission_denied – API-Schlüssel fehlt oder ist fehlerhaft formatiert. Prüfe, ob der Header exakt Authorization: Bearer sk-... lautet.
• 400 mit INVALID_REQUEST – Verstoß gegen das Eingabe-Schema. Die Fehlermeldungen sind präzise, z. B. resolution: value must be one of '1K', '2K' oder image_urls: maxItems: got 11, want 10.
• image_urls must be an array – du hast einen nackten String übergeben. Packe ihn auch bei nur einem Bild in eine Liste.

Nächste Schritte

• Modellseite: seedream-5.0-pro/image-to-image – Fähigkeiten und aktueller Status.
• Die Preise pro Bild findest du auf der Preisseite.
• Günstigere Bearbeitung für Pipelines mit hoher Parallelität: So verwendest du seedream-5.0-lite Image-to-Image.
• Die Wahl zwischen Modellen treffen: Die besten Image-to-Image-APIs 2026 vergleicht dieselbe Bearbeitungsaufgabe über drei Modelle hinweg.
• Vollständige API-Referenz: hiapi-Dokumentation.

Häufige Fragen

Wie viele Referenzbilder kann ich höchstens senden? Bis zu 10 URLs in image_urls. Die Grenze wird serverseitig durchgesetzt – 11 Bilder führen zu maxItems: got 11, want 10.

Kann die Ausgabe das Seitenverhältnis des Eingabebilds beibehalten? Ja – setze aspect_ratio auf match_input_image. Bei Bearbeitungen und Umgestaltungen ist das meist genau das, was du willst; wähle ein explizites Verhältnis wie 16:9 nur, wenn du bewusst neu komponieren möchtest.

Unterstützt seedream-5.0-pro Image-to-Image 4K? Nein. Dieser Endpunkt akzeptiert nur 1K und 2K. Wenn du einen anderen Wert anforderst, erhältst du einen 400-Fehler mit den erlaubten Werten.

Müssen meine Bild-URLs öffentlich sein? Sie müssen von den Servern von hiapi über HTTPS abrufbar sein. Vorsignierte URLs (S3, R2, GCS) funktionieren gut und ermöglichen es dir, den Bucket selbst privat zu halten.

Wie viel kostet seedream-5.0-pro Image-to-Image pro Bild? Die Abrechnung erfolgt pro erfolgreich generiertem Bild und variiert je nach Auflösung – aktuelle Tarife findest du auf der Preisseite.

Worin unterscheidet sich das von seedream-5.0-lite Image-to-Image? Pro ist die Flaggschiff-Stufe für schwierigere Bearbeitungen mit höherer Detailtreue; lite ist die schnellere, günstigere Option für große Stückzahlen. Die Anfragestruktur ist ähnlich, daher ist der klarste Weg zur Entscheidung, dieselbe Bearbeitungsaufgabe mit beiden auszuführen – beginne mit dem lite-Leitfaden und vergleiche die Ergebnisse mit deinen eigenen Referenzbildern.