Blog

Tutorial

seedance-2.5-flash 图生视频 API 教程:curl 与 Python Requests

Eine praktische Integrationsübung für Entwickler: Anfragestruktur, Start-/Endbild-Eingaben, asynchrones Polling und Fehlersuche

Nov 19, 2026
Titelbild: Auf dunkelbraunem Grund sind unterschiedlich breite Stoffstreifen in Beige und Kupfer zu einem flachen geometrischen Korbgeflechtmuster verwoben.
Auf dieser Seite

Was ein Image-to-Video-Aufruf tatsächlich tut

Bevor Sie die erste Codezeile schreiben, ist es hilfreich zu verstehen, was die API am anderen Ende tut. Der Aufruf von seedance-2.5-flash/image-to-video ist keine synchrone Anfrage, die blockiert, bis eine Videodatei zurückkommt. Es ist ein zweistufiger, asynchroner Workflow: Sie reichen einen Task ein und fragen dann dessen Ergebnis ab.

Die Einreichungsphase

Sie senden eine POST-Anfrage mit dem Eingabebild und den Generierungseinstellungen. Die API validiert den Anfragetext, stellt den Task in die Warteschlange und gibt sofort eine Antwort mit einer Task-ID und dem Anfangszustand zurück. Dieser Vorgang ist schnell — meist nur ein Augenblick —, weil zu diesem Zeitpunkt noch keine Pixel gerendert wurden. Ihre Aufgabe ist es, diese ID zu erfassen und sicher zu speichern.

Die Renderingphase

Die Generierung läuft im Hintergrund ab. Je nach Cliplänge und Einstellungen kann das eine beträchtliche reale Zeit in Anspruch nehmen. Erwarten Sie in diesem Zeitfenster nicht, dass die endgültige Video-URL bereits verfügbar ist. Stattdessen sollten Sie den Status des Tasks abfragen.

Die Ergebnisphase

Der Task erreicht schließlich einen Endzustand: Erfolg mit einem herunterladbaren Video-Artefakt oder Fehlschlag mit einem Fehler, der untersucht werden kann. Sobald ein Endzustand erreicht ist, sollte das Polling beendet werden.

Warum das für Ihren Code wichtig ist

Da das Modell asynchron arbeitet, sind die häufigsten Integrationsfehler architektonischer und nicht syntaktischer Natur: anzunehmen, dass die erste Antwort das Video enthält, in festen Intervallen zu schlafen statt das Statusfeld abzufragen, und es zu versäumen, den transienten Zustand processing von einem dauerhaften Fehler zu unterscheiden. Alles in diesem Tutorial dreht sich um eine saubere Schleife „Einreichen → Abfragen → Beenden“, deshalb sollten Sie diese drei Phasen beim Lesen im Hinterkopf behalten.

Voraussetzungen und Anfragestruktur

Was vor dem ersten Aufruf vorbereitet sein muss

  • API-Zugangsdaten. Ihr HiAPI-API-Schlüssel, der mit jeder Anfrage gesendet wird. Bewahren Sie ihn in einer Umgebungsvariable (HIAPI_API_KEY) auf und nicht in der Versionsverwaltung — die folgenden Beispiele lesen ihn genau so.
  • Modell-ID. In diesem Tutorial ist der String fest: seedance-2.5-flash/image-to-video. Behandeln Sie ihn als undurchsichtige Konstante; setzen Sie ihn nicht aus Teilen zusammen.
  • Quellbild. Eine öffentliche URL oder eine unterstützte Inline-Bildreferenz. Das Modell benötigt mindestens ein Startbild.
  • HTTP-Client. curl für den Smoke-Test und requests für alles, was Sie behalten wollen.

Die logischen Felder des Anfragetexts

Unabhängig von der Sprache besteht der Anfragetext für Image-to-Video aus mehreren konzeptionellen Gruppen. Wenn Sie sie getrennt betrachten, wird das JSON leichter verständlich:

Modell und Eingabe

  • Die Modell-ID.
  • Ein Eingabeobjekt mit dem Startbild und optional einem Endbild. Kapitel 4 beschreibt, wie sie zusammenspielen.

Ausgabeeinstellungen

  • Schalter für Auflösung und Dauer.
  • Der Schalter für natives Audio, der festlegt, ob der generierte Clip eine begleitende Tonspur erhält. Kapitel 5 erklärt, wann Sie ihn aktivieren sollten.

Was zurückgegeben wird

Eine erfolgreiche Einreichung gibt ein Task-Objekt zurück. Die Felder, die Sie tatsächlich benötigen, sind die Task-ID und der aktuelle Status. Alles andere sind Metadaten, die Sie protokollieren oder ignorieren können. Parsen Sie die gesamte Antwort nicht schon am ersten Tag in ein typisiertes Modell — protokollieren Sie, prüfen Sie und grenzen Sie dann ein.

Eine kurze Realitätsprüfung vor dem Weitergehen: Wenn Ihr Anfragetext Felder enthält, deren Namen Sie nicht in einem Satz erklären können, entfernen Sie sie und beginnen Sie mit dem Minimum. Die Modellseite von seedance-2.5-flash/image-to-video ist die Referenz für die exakt akzeptierten Feldnamen.

Einen Task mit curl einreichen

Beginnen Sie mit der minimalen Anfrage, die funktionieren kann, und fügen Sie dann jeweils ein Feld hinzu. Hier ist die minimale Einreichung mit curl:

curl -X POST "$HIAPI_BASE_URL/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5-flash/image-to-video",
    "input": {
      "first_frame_image": "https://your-bucket.example.com/frame-001.jpg"
    }
  }'

Feldweise Erläuterung

  • Authorization —— Ihr API-Schlüssel als Bearer-Token. Wenn hier ein Fehler auftritt, erhalten Sie einen Authentifizierungsfehler, bevor eine Validierung ausgeführt wird; prüfen Sie ihn daher zuerst bei der Fehlersuche.
  • Content-Type: application/json —— erforderlich; wird es weggelassen, entstehen verwirrende Fehler in nachgelagerten Systemen.
  • model —— die feste Modell-ID. Ein Tippfehler hier führt zu einem 4xx und nicht zu einem stillen Fallback.
  • input.first_frame_image —— das Eröffnungsbild des Clips. Verwenden Sie eine URL, die aus Ihrem Netzwerk tatsächlich erreichbar ist; private oder abgelaufene URLs schlagen beim Abruf fehl, nicht bei der Einreichung.

Die Antwort lesen

Die Antwort ist JSON mit einer Task-ID und einem Status. Speichern Sie die ID sofort — das ist es, was Sie in Kapitel 7 abfragen werden. Eine schnelle Methode, sie in der Shell zu extrahieren:

# Nach dem obigen curl durch jq leiten
# {"job_id": "...", "status": "queued"}

Ein Endbild hinzufügen

Um auch das Endbild zu steuern, fügen Sie ein zweites Bild im selben input-Objekt hinzu. Feldname und akzeptierte Formate entnehmen Sie der Modelldokumentation — raten Sie keine alternativen Schreibweisen; die API lehnt unbekannte Schlüssel ab, statt sie zu ignorieren.

Sobald die minimale Anfrage funktioniert, haben Sie einen Smoke-Test, den Sie bei Problemen erneut ausführen können. Bewahren Sie ihn in einer Datei auf; wenn der Dienst um zwei Uhr morgens ausfällt, ist er wertvoller als jede lange Abhandlung.

Eingaben für Start- und Endbild

Die Eingabebilder sind der größte Einflussfaktor darauf, ob ein Task erfolgreich ist. Sie prägen den Inhalt des Clips und sind zugleich die häufigste Quelle für abgelehnte Anfragen.

Was das Startbild steuert

Das Startbild legt den Eröffnungszustand des generierten Clips fest: Komposition, Motiv, Beleuchtung und Farbe. Das Modell erzeugt Bewegung und Fortsetzung von diesem Ausgangspunkt aus, daher sollte das Bild wie ein Frame aussehen, das Sie zum Zeitpunkt null tatsächlich sehen möchten. Unscharfe, beschnittene oder stark komprimierte Quellbilder werden im weiteren Verlauf nicht auf magische Weise besser.

Was das Endbild steuert

Ein Endbild legt den Endzustand fest. Das ist nützlich, wenn der Clip auf einer bestimmten Einstellung enden muss — ein Produktfoto-Frame, eine Logo-Enthüllung, ein Match-Cut im Schnitt. Wird es weggelassen, wählt das Modell das Ende selbst, was für explorative Arbeit in Ordnung ist, für die Produktion aber unvorhersehbar.

Wie beide zusammenspielen

Wenn beide angegeben sind, interpoliert das Modell zwischen ihnen. Das hat praktische Konsequenzen:

  • Kontinuität schlägt Kontrast. Zwei Frames derselben Szene mit mäßiger Bewegungsamplitude ergeben einen kohärenteren Clip als zwei nicht zusammenhängende Bilder. Bei extrem unterschiedlichen Frames rechnen Sie mit sichtbaren Verformungen statt mit einem plausiblen Übergang.
  • Seitenverhältnisse sollten übereinstimmen. Unpassende Seitenverhältnisse zwischen Start- und Endbild zwingen das Modell zu einer unschönen Neukomposition. Beschneiden Sie beide vor der Einreichung auf dasselbe Verhältnis.
  • Die Auflösungen sollten vergleichbar sein. Ein scharfes Startbild und ein niedrig aufgelöstes Endbild geben dem Modell widersprüchliche Signale.

Checkliste vor der Einreichung

Prüfen Sie vor dem Senden: Beide Bild-URLs sind öffentlich erreichbar und laufen nicht mitten im Task ab; beide haben ein unterstütztes Format; beide haben dasselbe Seitenverhältnis; keines ist ein Screenshot mit UI-Elementen, die Sie nicht gerendert haben möchten. Eine schnelle HEAD-Anfrage für jede URL fängt die meisten dieser Probleme günstiger ab als ein fehlgeschlagener Generierungs-Task.

Wenn Sie doch eine Ablehnung erhalten, verweist die Fehlermeldung meist auf das Eingabeobjekt. Validieren Sie die Bilder zuerst lokal — Abmessungen, Format und Erreichbarkeit —, bevor Sie die API verdächtigen.

Einstellungen für Auflösung und natives Audio

Ausgabeeinstellungen sind der Bereich, in dem Entwickler zu viel konfigurieren. Die gute Nachricht ist, dass die Standardwerte vernünftig sind; das Risiko besteht darin, Werte aus der Dokumentation eines anderen Modells zu übernehmen.

Auflösung

Die Auflösung bestimmt die Größe des gelieferten Videos und damit auch Generierungszeit und Ausgabevolumen. Zwei Faustregeln:

  • Wählen Sie nach dem Zielort, nicht nach der Zahl. Ein Clip für einen mobilen Feed muss nicht in großer Größe gerendert und dann wieder verkleinert werden. Wählen Sie die kleinste Auflösung, die die Zielplattform erfüllt.
  • Bevorzugen Sie eine der dokumentierten Voreinstellungen. Beliebige oder nicht unterstützte Werte sind eine häufige Ursache für abgelehnte Anfragen. Wenn Sie einen bestimmten Frame benötigen, beschneiden oder skalieren Sie nach der Generierung, statt gegen den Request-Validator zu kämpfen.

Natives Audio

Der Schalter für natives Audio legt fest, ob der generierte Clip eine zusammen mit dem Video erzeugte Tonspur enthält. Überlegen Sie, ob Sie sie brauchen:

  • Aktivieren Sie ihn, wenn der Clip das endgültige, mit Ton angesehene Ergebnis ist — Social-Content, kurze Werbeclips, Charakterszenen, bei denen Umgebungsgeräusche die Bewegung verstärken.
  • Deaktivieren Sie ihn, wenn Sie im Editor eigene Musik oder Voiceover hinzufügen oder der Clip ein Zwischenprodukt ist. Audio zu generieren, das Sie verwerfen werden, ist verschwendete Arbeit und macht die nachgelagerte Verarbeitung aufwendiger.

Dauer

Die Dauer ist mit allem anderen gekoppelt: Längere Clips brauchen länger zur Generierung und neigen eher zu Drift in der Konsistenz des Motivs. Beginnen Sie für die erste Integration mit kurzen Clips. Bestätigen Sie mit einem kurzen Clip, dass die Pipeline Ende-zu-Ende funktioniert, und verlängern Sie erst dann, wenn Sie der Pipeline vertrauen.

Halten Sie das Einstellungsobjekt klein

Wenn Sie feststellen, dass Sie Einstellungen hinzufügen, um Qualitätsprobleme zu beheben, halten Sie inne und prüfen Sie, ob das Problem tatsächlich in den Eingabebildern liegt. Die meisten enttäuschenden Ergebnisse lassen sich auf Kapitel 4 zurückführen und nicht auf einen fehlenden Regler. Konfigurieren Sie bewusst, protokollieren Sie das exakte Einstellungsobjekt zusammen mit jeder Task-ID, dann können Sie Qualitätsänderungen bestimmten Anpassungen zuordnen.

Dieselbe Anfrage in Python

Eine curl-Anfrage lässt sich direkt nach Python übertragen. Das Ziel ist hier kein Framework — sondern ein kleiner, lesbarer Client, der einen Task einreicht und die ID zurückgibt, damit die Polling-Schicht getrennt bleiben kann.

import os
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "seedance-2.5-flash/image-to-video"


def submit_job(first_frame_url: str, last_frame_url: str | None = None) -> dict:
    payload = {
        "model": MODEL,
        "input": {"first_frame_image": first_frame_url},
    }
    if last_frame_url:
        payload["input"]["last_frame_image"] = last_frame_url

    response = requests.post(
        f"{BASE_URL}/image-to-video",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

Warum diese Struktur

  • Konfiguration über Umgebungsvariablen. Basis-URL und Schlüssel liegen außerhalb des Codes, sodass derselbe Client gegen verschiedene Umgebungen laufen kann.
  • timeout=30 beim Einreichen. Das Einreichen geht schnell; ein hängendes Einreichen deutet auf ein Netzwerk- oder Authentifizierungsproblem hin, das Sie früh erkennen wollen, statt einen Worker unbegrenzt zu blockieren.
  • raise_for_status() vor dem Parsen. Ein 4xx-Antfragetext ist meist ein JSON-Fehlerobjekt und kein Task. Eine früh geworfene Exception hält den normalen Pfad sauber und lässt den Aufrufer Fehler explizit behandeln.
  • Einreichen und Polling getrennt. submit_job tut nur eine Sache. Die Polling-Schleife im nächsten Kapitel nimmt das zurückgegebene Dictionary entgegen und kümmert sich um das Warten.

Portierung in einen Dienst

Umhüllen Sie den Aufruf in einem echten Dienst so, dass Fehler als typisierte Exceptions mit Statuscode und Antworttext auftreten — beim Debuggen in der Produktion werden Sie den Rohtext der Antwort brauchen. Protokollieren Sie den Anfragetext zusammen mit der zurückgegebenen Task-ID; wenn ein Kollege fragt, warum ein Clip falsch aussieht, ist diese Logzeile die gesamte Untersuchung.

Die Feldnamen sind mit den curl-Beispielen identisch. Wenn Sie das eine lesen können, können Sie auch das andere lesen — genau dafür lohnt es sich, fünf Minuten mit curl zu beginnen.

Ergebnisse abfragen, ohne die API zu bombardieren

Jetzt existiert der Task und hat eine ID. Der naive Ansatz — sechzig Sekunden schlafen und dann beten — scheitert auf zwei Arten: Er verschwendet Zeit, wenn der Task früher fertig ist, und scheitert vollständig, wenn der Task länger dauert.

Das Statusfeld abfragen, nicht die Uhr

Schreiben Sie eine Schleife, die den aktuellen Status des Tasks abfragt und danach verzweigt:

import time
import requests


def wait_for_job(job_id: str, timeout_s: int = 600) -> dict:
    deadline = time.monotonic() + timeout_s
    delay = 2.0
    while time.monotonic() < deadline:
        r = requests.get(
            f"{BASE_URL}/jobs/{job_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=30,
        )
        r.raise_for_status()
        job = r.json()
        status = job.get("status")

        if status == "succeeded":
            return job
        if status == "failed":
            raise RuntimeError(f"job failed: {job.get('error')}")

        time.sleep(delay)
        delay = min(delay * 1.5, 15.0)  # begrenzter exponentieller Backoff

    raise TimeoutError(f"job {job_id} not terminal after {timeout_s}s")

Die wichtigen Eigenschaften

  • Explizite Endzustände. Nur succeeded und failed beenden die Schleife. Jeder andere Status ist transient. Behandeln Sie unbekannte Status nicht als Fehler — neue Zwischenzustände entstehen mit der Zeit, und Ihre Schleife sollte sie tolerieren.
  • Begrenzter Backoff. Beginnen Sie klein (wenige Sekunden), erhöhen Sie mit einem moderaten Faktor und begrenzen Sie auf etwa zehn bis fünfzehn Sekunden. Das hält kurze Tasks agil, ohne den Endpunkt während langer Renderings zu bombardieren.
  • Harte Frist. Begrenzen Sie immer die Gesamtwartezeit. Ohne sie belegt ein hängender Task dauerhaft einen Worker. Wählen Sie die Obergrenze anhand Ihrer längsten realistischen Rendering-Zeit plus Puffer.
  • Fehlschlag von Timeout trennen. Ein failed-Task ist ein Generierungsfehler, der dem Benutzer gemeldet werden sollte. Ein Timeout ist ein Infrastrukturzustand, der einen erneuten Versuch oder eine separate Untersuchung verdient. Beides zu vermischen macht Post-Mortems mühsam.

In einem Webdienst

Führen Sie diese Schleife nicht im Request-Handler aus, während der Benutzer wartet. Reichen Sie ein, speichern Sie die Task-ID, geben Sie sofort zurück und lassen Sie einen Hintergrund-Worker pollen und das Ergebnis liefern — per Webhook, Queue oder einer vom Frontend überwachten Zeilenaktualisierung. Die obige Schleife ist ein Anliegen des Workers, nicht des HTTP.

Häufige Fehler beheben

Die meisten Fehler fallen in drei Kategorien. Bestimmen Sie zuerst die Kategorie und dann die konkrete Ursache.

Kategorie 1: Eingabevalidierungsfehler

Symptom: ein 4xx bei der Einreichung, unmittelbar und vor jedem Rendering.

Diagnose in dieser Reihenfolge:

  1. Ist die Bild-URL erreichbar? Rufen Sie sie selbst aus demselben Netzwerk ab. Abgelaufene signierte URLs und private Buckets sind die häufigste Ursache.
  2. Ist das Format unterstützt? Kodieren Sie in ein Standardformat neu, statt zu diskutieren.
  3. Sind Start- und Endbild konsistent? Unpassende Seitenverhältnisse oder extrem unterschiedliche Szenen äußern sich meist als Validierungs- oder Qualitätsproblem.
  4. Haben Sie Felder mit falschem Namen hinzugefügt? Unbekannte Schlüssel werden meist abgelehnt statt ignoriert. Vergleichen Sie mit der Modellreferenz.

Kategorie 2: Parameterfehlanpassungen

Symptom: Die Anfrage wird wegen einer Einstellung abgelehnt, oder die Ausgabe ignoriert Ihre Konfiguration.

  • Nicht unterstützte Auflösung oder Dauer. Verwenden Sie nur die dokumentierten Werte; beliebige Zahlen sind eine häufige Ursache für Ablehnungen.
  • Tippfehler in der Modell-ID. Sie ist ein fester String — kopieren Sie sie, tippen Sie sie nicht neu ein.
  • Verschachtelungsfehler. Einstellungen, die auf die oberste Ebene gehören, im input abzulegen oder umgekehrt, erzeugt verwirrende Fehler. Orientieren Sie sich an der Anfragestruktur aus Kapitel 3.

Kategorie 3: Polling-Timeouts und Task-Fehler

Symptom: Der Task wird angenommen, erreicht aber nie einen erfolgreichen Endzustand.

  • Prüfen Sie, ob Sie die richtige ID abfragen. Copy-and-Paste-Fehler zwischen Tasks in Batch-Skripten sind überraschend häufig.
  • Prüfen Sie, ob der Status tatsächlich fortschreitet. Protokollieren Sie den Status bei jeder Abfrage, um zu sehen, ob der Task vorankommt oder stagniert.
  • Unterscheiden Sie API-Fehler von Generierungsfehlern. Wenn die Polling-Anfrage selbst fehlschlägt, ist das ein Transportproblem. Wenn der Task failed meldet, lesen Sie den Fehlertext — er verweist meist auf die problematische Eingabe.
  • Führen Sie den minimalen curl-Smoke-Test erneut aus. Wenn auch der Smoke-Test fehlschlägt, liegt das Problem bei den Zugangsdaten oder dem Dienst; wenn er erfolgreich ist, liegt es in Ihrem Anfragetext.

Allgemeine Debugging-Haltung

Protokollieren Sie für jeden Task drei Dinge: den exakten Anfragetext, die zurückgegebene Task-ID und den Endzustand zusammen mit dem Fehlertext. Mit diesen drei Dingen ist fast jedes Vorkommnis eine Fünf-Minuten-Diagnose statt eines ganzen Nachmittags. Im Zweifel reduzieren Sie die Anfrage auf die Minimalform aus Kapitel 3 und fügen Feld für Feld hinzu, bis der Fehler auftritt — das zuletzt hinzugefügte Feld ist der Übeltäter.

Ähnliche Artikel

Alle Artikel ansehen →

Starte mit persistenten KI-Artefakten

Hol dir deinen API-Key und rufe Bild-, Video- und Audiomodelle über eine einzige task-basierte API auf.

API-Dokumentation lesen