Tutorial
So rufen Sie die seedance-2.5 Image-to-Video-API auf: verfügbare curl- und Python-Beispiele
Auf dieser Seite
Was der seedance-2.5 Image-to-Video-Endpunkt Ihnen bietet
seedance-2.5 Image-to-Video ist ein asynchroner Modell-Endpunkt auf HiAPI, der ein oder zwei statische Bilder in einen kurzen Videoclip verwandelt. Sie senden ihm ein Bild (oder ein Bildpaar, das Start- und Endpunkt der Bewegung darstellt), beschreiben die gewünschte Veränderung, und die Plattform gibt eine Aufgabe zurück, die bei abgeschlossener Generierung in eine Video-Datei-URL aufgelöst wird.
In einem typischen Video-Generierungs-Stack befindet sich dieser Endpunkt auf der Ebene „statische Bilder in Bewegung bringen“. Sie haben bereits Ausgangsbilder – Produktbilder, Charakter-Renderings, Storyboard-Frames – und benötigen Bewegung, kein neues Bild. Da der Aufruf asynchron ist, besteht Ihre Aufgabe darin, eine Aufgabe einzureichen, die Aufgabenkennung zu speichern und kontinuierlich abzufragen, bis das Ergebnis bereit ist. Dieses Muster aus Einreichen und anschließendem Abfragen gilt für die langlaufenden Generierungsendpunkte von HiAPI allgemein, sodass der hier geschriebene Client auf andere Modelle übertragbar ist.
Der Endpunkt bietet außerdem native Audio-Optionen, was wichtig ist, wenn Ihr Verarbeitungsablauf einen Videoclip mit Ton benötigt und nicht ein stummes Material, das später vertont wird. Wenn Sie eine präzise Kameraführung bis auf die Frame-Ebene oder eine loopbare Bewegung benötigen, ist Image-to-Video mit explizitem erstem und letztem Frame oft die kontrollierbarste Wahl, ohne eine 3D-Szene aufzubauen.
Voraussetzungen und Authentifizierung
Bevor Sie den ersten Aufruf tätigen, halten Sie drei Dinge bereit.
1. Ein HiAPI-API-Schlüssel
Jede Anfrage wird mit Ihrem Schlüssel authentifiziert, der als Bearer-Token im Authorization-Header gesendet wird. Committen Sie ihn nicht in die Quellcodeverwaltung – lesen Sie ihn aus einer Umgebungsvariable, damit dasselbe Skript sowohl lokal als auch in der CI ausgeführt werden kann.
export HIAPI_API_KEY="your_key_here"
2. Ein für die API abrufbares Ausgangsbild
Bildeingaben sind URLs. Hosten Sie das Bild an einem für den Dienst erreichbaren Ort – Objektspeicher mit signierter URL, CDN oder jede öffentliche HTTPS-Adresse. Wenn Sie das Bild nicht öffentlich zugänglich machen möchten, erzeugen Sie eine kurzlebige signierte URL, statt den Bucket öffentlich zu machen.
Für den Erstes-Frame/Letztes-Frame-Workflow benötigen Sie ein Bild (nur erstes Frame) oder zwei Bilder (erstes und letztes Frame).
3. Einen HTTP-Client
Jedes Tool, das JSON senden kann, ist geeignet: curl für schnelle Smoke-Tests, requests oder httpx in Python, fetch in Node. Sie benötigen kein spezielles SDK.
Die modellspezifische Basis-URL, der Pfad und die Feldnamen stehen auf der Modellseite der HiAPI-Konsole; verwenden Sie diese Werte in den folgenden Beispielen wortgetreu. Sobald Sie Schlüssel und Bild-URL haben, können Sie einreichen.
Eingabe des ersten Frames und des letzten Frames
Zwei Bildeingaben steuern die verschiedenen Enden des Videoclips, und welche Sie wählen, verändert Ihr Maß an Kontrolle über die Bewegung.
Nur erstes Frame. Sie stellen ein Bild bereit, und das Modell generiert von dort aus nach vorne. Dies ist die richtige Wahl, wenn das Modell die Bewegung selbst erfinden soll: ein Porträt, das sich langsam dreht, ein rotierendes Produkt, eine Landschaft mit ziehenden Wolken. Sie geben die Sicherheit über die Endposition des Clips auf, gewinnen aber größeren kreativen Spielraum und benötigen nur ein Material.
Erstes und letztes Frame. Sie stellen zwei Bilder bereit, und das Modell generiert den Pfad zwischen ihnen. Dies ist die richtige Wahl, wenn die Endpunkte wichtig sind: ein Logo, das sich zum finalen Markenzeichen zusammensetzt, eine Figur, die von Pose A zu Pose B wechselt, ein Objekt, das von links nach rechts durchs Bild gleitet. Das Bereitstellen des letzten Frames beschränkt die Bewegung, was in der Regel weniger Überraschungen und – wenn Sie den Clip wiederholt abspielen möchten – eine bessere Loopbarkeit bedeutet.
Eine praktische Faustregel: Wenn Sie den Clip als „an diesem Bild geschieht etwas“ beschreiben können, verwenden Sie nur das erste Frame. Wenn Sie ihn als „dieses Bild wird zu jenem Bild“ beschreiben können, geben Sie zwei an. Wenn Sie zwei bereitstellen, halten Sie beide Bilder hinsichtlich Komposition, Seitenverhältnis und Beleuchtung konsistent – ein unpassendes Bildpaar zwingt das Modell, einen Sprung zu verarbeiten, der wie ein Fehler aussieht.
Ihr Prompt sollte die Bilder ergänzen und nicht mit ihnen konkurrieren. Beschreiben Sie die Bewegung, nicht den statischen Inhalt, den das Modell bereits sehen kann.
Erste Anfrage mit curl einreichen
Die folgende Anfrage reicht eine Image-to-Video-Aufgabe ein. Ersetzen Sie den Endpunktpfad, den Modellbezeichner und die Feldnamen durch die Werte, die auf der Modellseite des seedance-2.5 Image-to-Video-Modells in der HiAPI-Konsole angezeigt werden, und setzen Sie Ihre eigene Bild-URL ein.
curl -X POST "$HIAPI_BASE_URL/<image-to-video-path>" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5/image-to-video",
"prompt": "The camera slowly pushes in as the subject turns toward the light",
"first_frame_image": "https://your-cdn.example.com/frame-01.jpg",
"last_frame_image": "https://your-cdn.example.com/frame-02.jpg"
}'
Zur Anfragestruktur gibt es einige Punkte zu beachten:
promptbeschreibt die Bewegung. Halten Sie ihn kurz und konkret; lange Adjektivlisten verwässern die Anweisung oft.first_frame_imageist für Image-to-Video erforderlich.last_frame_imageist optional – entfernen Sie das Feld bei der Generierung nur mit dem ersten Frame vollständig.- Wenn Sie Audio-Optionen benötigen, sind diese zusätzliche Felder im selben JSON-Body (weiter unten beschrieben).
Die Antwort ist ein Aufgabenobjekt mit Kennung und Status. Speichern Sie diese Kennung; Sie benötigen sie bei jeder Abfrage. Wenn der Aufruf einen Authentifizierungs- oder Validierungsfehler zurückgibt, prüfen Sie zuerst Header und Bild-URL, bevor Sie es erneut versuchen.
Dieselbe Anfrage in Python
Im Folgenden finden Sie den entsprechenden Einreichungscode in Python, umstrukturiert, sodass die Aufgabenkennung einfach erfasst werden kann.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
ENDPOINT = f"{BASE_URL}/<image-to-video-path>"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def submit_video(first_frame, last_frame=None, prompt="", audio=False):
payload = {
"model": "seedance-2.5/image-to-video",
"prompt": prompt,
"first_frame_image": first_frame,
}
if last_frame:
payload["last_frame_image"] = last_frame
if audio:
payload["audio"] = True
resp = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
resp.raise_for_status()
data = resp.json()
return data["task_id"], data
task_id, raw = submit_video(
first_frame="https://your-cdn.example.com/frame-01.jpg",
last_frame="https://your-cdn.example.com/frame-02.jpg",
prompt="The camera slowly pushes in as the subject turns toward the light",
)
print(task_id)
Zwei Gewohnheiten lohnen sich früh. Erstens: Legen Sie ein explizites timeout für den Einreichungsaufruf fest – hängende Anfragen sollten schnell fehlschlagen, statt Ihren Worker zu blockieren. Zweitens: Behalten Sie während der Entwicklung die Rohantwort. Das Feld, das die Aufgabenkennung speichert, kann sich je nach Endpunktversion von task_id unterscheiden; das einmalige Ausgeben des rohen JSON erspart eine Debugging-Runde.
Asynchrone Aufgabe abfragen, bis das Video bereit ist
Die Image-to-Video-Generierung dauert länger, als eine HTTP-Anfrage geöffnet bleiben sollte, daher verwendet die Plattform einen Lebenszyklus aus Einreichen und anschließendem Abfragen. Das Einreichen gibt die Aufgabenkennung zurück; dann fragen Sie den Aufgaben-Endpunkt regelmäßig ab, bis sein Status einen Endzustand erreicht.
import time
import requests
def wait_for_video(task_id, interval=5, max_wait=600):
url = f"{BASE_URL}/<task-path>/{task_id}"
deadline = time.time() + max_wait
while time.time() < deadline:
resp = requests.get(url, headers=HEADERS, timeout=30)
resp.raise_for_status()
task = resp.json()
status = task.get("status")
if status == "succeeded":
return task["video_url"]
if status in ("failed", "cancelled"):
raise RuntimeError(f"Task {task_id} ended as {status}: {task.get('error')}")
time.sleep(interval)
raise TimeoutError(f"Task {task_id} not ready after {max_wait}s")
Gestalten Sie das Abfragen nach vier Regeln:
- Fragen Sie in angemessenen Abständen ab. Fünf Sekunden sind ein sinnvoller Standardwert. Das Bombardieren des Endpunkts lässt das Video nicht schneller rendern.
- Legen Sie stets eine Frist fest. Aufgaben können fehlschlagen oder länger als erwartet in der Warteschlange stehen; eine unbegrenzte Schleife verwandelt ein vorübergehendes Problem in einen hängenden Worker.
- Behandeln Sie
failedundcancelledals Endzustände. Geben Sie das Fehlerfeld aus, statt dieselbe Aufgabe ewig erneut zu versuchen. - Verwenden Sie Backoff beim kontinuierlichen Abfragen. Wenn Sie viele Aufgaben gleichzeitig abfragen, erhöhen Sie den Abstand schrittweise, um Lastspitzen zu vermeiden.
In der Produktion sollten Sie aus einem Hintergrund-Worker oder einer Queue heraus abfragen, nicht innerhalb eines Web-Request-Handlers. Das Ergebnis ist eine Video-URL; laden Sie sie zeitnah herunter und kopieren Sie sie in Ihren eigenen Speicher, da generierte Asset-URLs in der Regel nicht dauerhaft sind.
Umgang mit dem nativen Audio-Flag
seedance-2.5 kann Clips mit nativem Audio generieren, und diese Steuerung ist ein Anfragefeld neben den Bildeingaben und dem Prompt – kein separater Endpunkt. Der genaue Feldname und die zulässigen Werte sind auf der Modellseite aufgeführt; die obige Python-Hilfsfunktion veranschaulicht dies anhand eines übergebenen audio-Booleschen Werts.
Ob Sie es aktivieren, hängt davon ab, wie der Clip verwendet wird.
Fordern Sie Audio an, wenn: die Ausgabe direkt an das Publikum gerichtet ist – Social-Post, Vorschau, Präsentation – und Sie möchten, dass der Clip ohne Nachbearbeitung vollständig wirkt. Natives Audio hilft Prüfern außerdem, das Timing zu beurteilen, da der Ton die Bewegungsabläufe leichter lesbar macht.
Überspringen Sie Audio, wenn: Ihr Verarbeitungsablauf eine eigene Tonspur darüberlegt, der Clip in ein Compositing- oder Bearbeitungstool weitergegeben wird oder Sie viele Varianten generieren möchten und nur die endgültig ausgewählte Version vertonen. Eine stumme Generierung hält das Material neutral und vermeidet spätere Synchronisationsprobleme.
Ein praktischer Hinweis zur Eingrenzung: Betrachten Sie Audio als Entscheidung pro Anfrage, nicht als globale Einstellung. Wie oben gezeigt, kann eine einzelne Hilfsfunktion, die ein audio-Flag akzeptiert, denselben Code-Pfad sowohl für stumme Hintergrund-Batches als auch für ausgefeilte finale Renderings nutzen.
Wenn das Flag vorhanden ist, das Ergebnis aber stumm bleibt, prüfen Sie zunächst, ob der Wert wie erwartet serialisiert wurde – die Zeichenkette "true" und der boolesche Wert true sind ein häufiges Missverhältnis –, bevor Sie annehmen, dass das Modell es ignoriert hat.
Häufige Fehlerquellen und nächste Schritte
Die meisten Probleme bei der ersten Integration lassen sich in vier Kategorien einordnen.
Vom Dienst nicht abrufbare Eingaben
Eine URL, die in Ihrem Browser funktioniert, kann serverseitig fehlschlagen: private Buckets, abgelaufene Links oder Hosts, die Nicht-Browser-User-Agents blockieren. Verwenden Sie signierte URLs, deren Lebensdauer den gesamten Generierungsprozess abdeckt, und bestätigen Sie, dass das Bild von einer Maschine außerhalb Ihres Netzwerks geladen werden kann.
Nicht übereinstimmende Frames
Wenn sich erstes und letztes Frame in Seitenverhältnis, Zuschnitt oder Farbtemperatur unterscheiden, muss das Modell diesen Sprung ausgleichen. Vor dem Einreichen sollten Sie das Bildpaar auf dieselbe Größe und eine ähnliche Farbabstimmung vorverarbeiten.
Falsche Feldnamen oder Modellbezeichner
Die Beispiele hier verwenden die Anfragestruktur von der Modellseite; kopieren Sie Feldnamen und Modellzeichenkette wortgetreu aus der Konsole, nicht aus dem Gedächtnis oder alten Snippets. Tippfehler in Feldnamen werden oft stillschweigend ignoriert statt abgelehnt.
Nicht endende Abfragen
Wenn Ihre Schleife wiederholt in ein Timeout läuft, protokollieren Sie jeden Statuswert, den Sie beobachten. Ein unerwarteter Status-String erklärt meist die Stagnation – Ihre Endzustandsprüfung stimmt möglicherweise einfach nicht mit dem überein, was die API zurückgibt.
Sobald ein einzelner Clip durchgängig funktioniert, sind die natürlichen nächsten Schritte: mehrere Bilder über dieselbe Hilfsfunktion zum Einreichen und Abfragen im Batch zu verarbeiten, um die Einreichung herum Wiederholungsversuche mit Backoff hinzuzufügen und die Ergebnisse in persistenten Speicher zu schreiben. Die Endpunktdetails, Anfragefelder und Parameterreferenzen finden Sie auf der Modellseite von seedance-2.5 Image-to-Video; passen Sie den obigen Code damit an Ihre eigenen Bilder an.
Ähnliche Artikel
Alle Artikel ansehen →-
Tutorial
gpt-6.2-sol Praxisleitfaden: 5 hochwertige Einsatzszenarien für Textmodelle im Geschäftsalltag
-
Tutorial
gpt-6.2-astra Praxisleitfaden: Integration und Umsetzung von 5 hochwertigen Text-Szenarien
Eine Entwickler-Checkliste von der Szenarioauswahl bis zur technischen Umsetzung
-
Tutorial
Tripo H3.1 Anwendungsszenarien in der Praxis: 5 wertvolle Einsatzmöglichkeiten und Umsetzungshinweise
Von Text-zu-3D bis Multi-View-Rekonstruktion: den richtigen Modus und die richtigen Parameter je nach Geschäftsszenario wählen