Zum Hauptinhalt springen
Dieser Artikel stellt eine Anleitung zur Integration der SeeDance Videos Generation API vor, mit der offizielle SeeDance-Videos durch Eingabe benutzerdefinierter Parameter generiert werden können.

Antragsprozess

Um die SeeDance Videos Generation API zu verwenden, rufen Sie zunächst die Ace Data Cloud-Konsole auf, um Ihr API-Token zu erhalten und es als Reserve aufzubewahren. Falls Sie sich noch nicht angemeldet oder registriert haben, werden Sie automatisch zur Anmeldeseite weitergeleitet und zur Registrierung und Anmeldung eingeladen. Nach Abschluss kehren Sie automatisch zur aktuellen Seite zurück. Ein API-Token kann alle Dienste der Plattform aufrufen, ohne dass für jeden Dienst ein separater Antrag erforderlich ist. Beim ersten Antrag wird ein kostenloses Guthaben verschenkt, das kostenlos ausprobiert werden kann; bei unzureichendem Guthaben kann das allgemeine Guthaben in der Konsole aufgeladen werden.
📘 Vollständige Dokumentation: SeeDance Videos Generation API →

Grundlegende Verwendung

Lernen Sie zunächst die grundlegende Verwendung kennen: Geben Sie einfach den Prompt content.text, den Typ content.type=text sowie das Modell model ein, um das verarbeitete Ergebnis zu erhalten. Die konkreten Inhalte sind wie folgt:

Hier sehen wir, dass wir die Request Headers festgelegt haben, einschließlich:
  • accept: Welches Format des Antwortergebnisses empfangen werden soll; hier wird application/json eingetragen, also das JSON-Format.
  • authorization: Der Schlüssel zum Aufrufen der API, der nach dem Antrag direkt aus der Auswahlliste ausgewählt werden kann.
Zusätzlich wurde der Request Body festgelegt, einschließlich:
  • model: Das Modell zur Videogenerierung.
    • Seedance-1.x-Serie: doubao-seedance-1-0-pro-250528, doubao-seedance-1-0-pro-fast-251015, doubao-seedance-1-5-pro-251215, doubao-seedance-1-0-lite-t2v-250428, doubao-seedance-1-0-lite-i2v-250428.
    • Seedance-2.0-Serie (unterstützt multimodale Referenzen für Charaktere sowie Audio und Video): doubao-seedance-2-0-260128 (Standard), doubao-seedance-2-0-fast-260128 (Schnell), doubao-seedance-2-0-mini-260615 (Leichtgewichtig).
    • Seedance 2.5: doubao-seedance-2-5-260628, unterstützt bis zu 30 Sekunden, reine Audio-Referenzen, mehr Materialien, Videobearbeitung und Verlängerung.
  • content: Eingabeinhalts-Array, type kann text (Prompt), image_url (Referenzbild), audio_url (Referenzaudio), video_url (Referenzvideo) sein. Bilder können über role ihren Zweck festlegen: first_frame (erstes Bild) / last_frame (letztes Bild) / reference_image (Charakter- / Subjektreferenz).
  • resolution: Ausgabeauflösung, optional 480p / 720p / 1080p / 4k. 2.5 unterstützt 480p, 720p, 1080p; 2.0 Fast/Mini unterstützt 480p, 720p; 2.0 Standard unterstützt maximal 4k.
  • ratio: Seitenverhältnis, optional 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive.
  • duration: Videodauer (Sekunden, Ganzzahl). 1.0-Serie 2–12; 1.5 Pro 4–12; 2.0-Serie 4–15; 2.5 4–30. 1.5/2.x unterstützt -1 (automatische Dauer).
  • seed: Zufalls-Seed, Ganzzahl, -1 bis 4294967295.
  • camerafixed: Ob die Kamera fixiert wird, true / false.
  • watermark: Ob ein Wasserzeichen hinzugefügt wird, true / false.
  • generate_audio: Ob ein Video mit Ton generiert wird, true / false, wird von Seedance 1.5 Pro und der 2.x-Serie unterstützt.
  • return_last_frame: Ob die Bild-URL des letzten Videobildes im Ergebnis zurückgegeben wird.
  • omni_reference_task_type: Nur 2.5; auto / reference / edit / extend.
  • output_format: Nur 2.5; mp4 / mov, standardmäßig mp4.
  • tools: Nur 2.5; unterstützt derzeit das Online-Suchwerkzeug web_search, das die Anzahl der Ergebnisse, die Anzahl der Schlüsselwörter und die Suchquellen begrenzen kann.
  • priority: Optionale Aufgabenpriorität für 2.5, Ganzzahl 0–9, standardmäßig 0.
  • safety_identifier: Stabile anonyme Endbenutzerkennung mit maximal 64 Zeichen; verwenden Sie bitte einen Hash oder eine interne anonyme ID und übermitteln Sie keine Namen, E-Mail-Adressen oder Telefonnummern.
  • execution_expires_after: Zeitüberschreitung der Aufgabe (Sekunden), Bereich 3600–259200.
  • callback_url: Asynchrone Callback-Adresse; nach der Einstellung gibt die API sofort task_id zurück, und nach Abschluss der Aufgabe wird das Ergebnis per POST an diese Adresse gesendet.
  • async: Optional; wenn auf true gesetzt, gibt die Schnittstelle sofort task_id zurück, ohne dass callback_url bereitgestellt werden muss. Anschließend wird das Ergebnis durch Abfragen der entsprechenden Aufgabenschnittstelle abgerufen.
Nach der Auswahl können Sie feststellen, dass auf der rechten Seite auch der entsprechende Code generiert wurde, wie in der Abbildung gezeigt:

Klicken Sie auf die Schaltfläche „Try“, um einen Test durchzuführen. Wie in der obigen Abbildung gezeigt, erhalten wir hier folgendes Ergebnis:
Das zurückgegebene Ergebnis enthält mehrere Felder, die wie folgt vorgestellt werden:
  • success, der Status der Videogenerierungsaufgabe zu diesem Zeitpunkt.
  • task_id, die ID der Videogenerierungsaufgabe zu diesem Zeitpunkt.
  • trace_id, die Tracking-ID der Videogenerierung zu diesem Zeitpunkt.
  • data, die Ergebnisliste der Videogenerierungsaufgabe zu diesem Zeitpunkt.
    • task_id, die serverseitige ID der Videogenerierungsaufgabe zu diesem Zeitpunkt.
    • video_url, der Videolink der Videogenerierungsaufgabe zu diesem Zeitpunkt.
    • status, der Status der Videogenerierungsaufgabe zu diesem Zeitpunkt.
      • model, das zur Videogenerierung verwendete Modell.
Wir können sehen, dass wir zufriedenstellende Videoinformationen erhalten haben. Wir müssen nur die SeeDance-Videos anhand der Videolink-Adresse von data im Ergebnis abrufen. Wenn Sie außerdem den entsprechenden Integrationscode generieren möchten, können Sie ihn direkt kopieren und generieren, zum Beispiel lautet der CURL-Code wie folgt:

Beschreibung der Inline-Parameter

Am Ende des content[].text-Prompts können Generierungsparameter durch Anhängen im Format --parameter value übergeben werden (alte Methode, schwache Validierung; bei fehlerhaften Angaben werden automatisch Standardwerte verwendet). Die vollständige Parameterliste lautet wie folgt:
Empfohlene Vorgehensweise: Verwenden Sie direkt die entsprechenden Felder der obersten Ebene im Request Body (wie resolution, ratio usw.). Dies ist ein Modus mit starker Validierung; bei fehlerhaften Parameterangaben werden eindeutige Fehlermeldungen zurückgegeben, wodurch Probleme leichter untersucht werden können.

Videos mit Ton generieren

Seedance 1.5 Pro und die 2.x-Serie unterstützen über den Parameter generate_audio die Generierung von Videos mit Audio:
Die 1.0-Serie unterstützt diesen Parameter nicht.

Seedance 2.5 multimodale Generierung, Bearbeitung und Verlängerung

doubao-seedance-2-5-260628 unterstützt 480p / 720p / 1080p, 4–30 Sekunden oder automatische Dauer und erhöht das Materiallimit auf 30 Referenzbilder, 10 Referenzvideos und 10 Referenzaudios (insgesamt maximal 50). 2.5 unterstützt außerdem die Übermittlung von ausschließlich Referenzaudio, ohne dass gleichzeitig Bilder oder Videos bereitgestellt werden müssen. Bei der normalen multimodalen Generierung kann omni_reference_task_type weggelassen, auf auto gesetzt oder explizit auf reference gesetzt werden. Für Videobearbeitung und -verlängerung muss reference_video übergeben werden:
  • reference: Übergeben Sie mindestens ein reference_image, reference_video oder reference_audio; 2.5 unterstützt die Übermittlung von ausschließlich Referenzaudio.
  • edit: Es müssen ratio: adaptive und duration: -1 verwendet werden; die Ausgabezeit wird gemäß dem tatsächlichen Ergebnis abgerechnet.
  • extend: Es muss ratio: adaptive verwendet werden; duration kann 4–30 oder -1 sein.
  • auto: Das Modell wählt anhand des Prompts und der Materialien automatisch Generierung, Bearbeitung oder Verlängerung aus.
  • Wenn der Aufgabentyp nicht mit den Materialien oder dem Prompt übereinstimmt, schlägt die Aufgabe fehl und gibt einen lokalisierbaren Parameterfehler zurück; passen Sie sie gemäß den obigen Einschränkungen an und reichen Sie sie erneut ein.

Erstes Bild für Bild-zu-Video

Wenn Sie eine Bild-zu-Video-Aufgabe wünschen, muss der Parameter content zunächst ein Element mit type gleich image_url enthalten, und das Feld image_url muss im Objektformat vorliegen: {"url": "https://..."} oder im Base64-Format {"url": "data:image/png;base64,..."}.
Hinweis: image_url unterstützt nicht die direkte Übergabe im String-Format (wie "image_url": "https://cdn.acedata.cloud/e724d7f13d.png"). Es muss das Objektformat "image_url": {"url": "https://..."} verwendet werden, andernfalls wird ein 400-Fehler zurückgegeben.
Der entsprechende Code:
Nach dem Klicken auf „Ausführen“ können Sie feststellen, dass sofort ein Ergebnis wie folgt erhalten wird:
Wie zu sehen ist, handelt es sich beim generierten Effekt um die Erstellung eines Videos aus einem Bild, und das Ergebnis ähnelt dem oben beschriebenen.

Erstes und letztes Bild für Bild-zu-Video

Wenn Sie für Bild-zu-Video das erste und letzte Bild verwenden möchten, muss der Parameter content zunächst den Typ image_url übergeben und role jeweils auf first_frame und last_frame gesetzt werden, um die folgenden Inhalte festzulegen:
  • role: Gibt das erste oder letzte Bild an.
  • image_url
    • url Bildlink Gleichzeitig muss content auch den Typ text als Prompt eingeben.
Der entsprechende Code:
Klicken Sie auf Ausführen, dann werden Sie feststellen, dass Sie sofort ein Ergebnis erhalten, wie folgt:
Man kann sehen, dass der Generierungseffekt ein Video mit einer Figur ist, und das Ergebnis dem obigen ähnlich ist.

Figur und multimodale Audio- und Videoreferenzen (Seedance 2.0)

Die Seedance-2.0-Serie (doubao-seedance-2-0-260128, doubao-seedance-2-0-fast-260128, doubao-seedance-2-0-mini-260615) unterstützt reference_image, reference_audio und reference_video. Es können eigene oder autorisierte Materialien verwendet werden, um die Konsistenz von Figuren, Subjekten, Bewegungen, Kameraführung, Stimmen und Rhythmus zu gewährleisten.
Bitte laden Sie nur eigene oder autorisierte Materialien von realen Personen und Figuren hoch. Verschiedene Modelle unterstützen Materialien von realen Personen auf unterschiedliche Weise; das Anfrageformat bleibt unverändert, und bei nicht konformen Materialien wird ein eindeutiger Fehler zurückgegeben.
Wichtige Hinweise zur Verwendung:
  • Nur Modelle der Seedance-2.0-Serie unterstützen reference_image; für 1.x-Modelle verwenden Sie bitte first_frame / last_frame (erstes und letztes Bild bei Bild-zu-Video).
  • Erstes Bild bei Bild-zu-Video, erstes und letztes Bild bei Bild-zu-Video sowie vollmodale Referenzen sind drei sich gegenseitig ausschließende Szenarien: first_frame / last_frame dürfen nicht zusammen mit reference_image / reference_video / reference_audio verwendet werden.
  • Wenn Sie in vollmodalen Referenzen erstes und letztes Bild festlegen möchten, markieren Sie die Bilder als reference_image und schreiben Sie im Prompt „Bild 1 als erstes Bild“ oder „Bild 2 als letztes Bild“; wenn erstes und letztes Bild strikt festgelegt werden müssen, verwenden Sie nur first_frame / last_frame.
  • Obergrenze für multimodale Referenzen: maximal 9 image_url; 2.0 unterstützt außerdem audio_url (role ist reference_audio, maximal 3 Einträge) und video_url (role ist reference_video, maximal 3 Einträge).
  • Anforderungen an Referenz-Audio (audio_url): Format wav / mp3; Dauer pro Eintrag 2–15 Sekunden, maximal 3 Einträge und eine Gesamtdauer von höchstens 15 Sekunden; pro Eintrag höchstens 15 MB. Bei Überschreitung des Zeitbereichs schlägt die Verarbeitung des Materials fehl.
  • Anforderungen an Referenz-Video (video_url): Format mp4 / mov; Dauer pro Eintrag 2–15 Sekunden, maximal 3 Einträge und eine Gesamtdauer von höchstens 15 Sekunden.
  • Für Referenzbilder werden Fotos mit einer einzelnen Person, frontalem Gesicht, klarer Sicht und ohne Verdeckung empfohlen; je klarer das Gesicht, desto höher die Ähnlichkeit.

Beispiel eins: Nahaufnahme mit Beibehaltung des Aussehens der Person

Übergeben Sie ein Gesichtsfoto, damit diese Person in die Kamera lächelt und winkt. Der entsprechende Code:
Das zurückgegebene Ergebnis lautet wie folgt, die Person im generierten Video bleibt mit dem Referenzfoto übereinstimmend:

Beispiel zwei: Dieselbe Person in eine völlig neue Szene versetzen

Die Stärke von reference_image liegt darin: Nur die Identität der Person wird beibehalten, während Szene, Kleidung und Bewegung vollständig durch den Prompt bestimmt werden. Im Folgenden wird dieselbe Gesichtsfotografie verwendet, damit diese Person in einem beigefarbenen Mantel durch einen herbstlichen Park geht:
Das zurückgegebene Ergebnis lautet wie folgt: Das Aussehen der Person bleibt erhalten, während die Szene bereits in einen herbstlichen Park gewechselt wurde:
💡 Wenn die Figur die Komposition auf dem Foto exakt nachbilden soll (statt „dieselbe Person in einer anderen Szene“), kann first_frame (erstes Bild bei Bild-zu-Video) verwendet werden, damit das Video von diesem Foto aus in Bewegung startet.

Asynchroner Callback

Da die Generierungszeit der SeeDance Videos Generation API relativ lang ist (etwa 1–2 Minuten), kann über das Feld callback_url der asynchrone Modus verwendet werden, um eine lange Belegung der HTTP-Verbindung zu vermeiden. Gesamtprozess: Der Client gibt beim Initiieren einer Anfrage callback_url an, und die API gibt sofort eine Antwort mit task_id zurück; nachdem die Aufgabe abgeschlossen ist, sendet die Plattform das Generierungsergebnis als POST JSON an callback_url, wobei das Ergebnis ebenfalls task_id zur Zuordnung enthält.
Nach Abschluss der Aufgabe sendet die Plattform folgenden Inhalt an callback_url:
Das Feld task_id im Ergebnis stimmt mit dem bei der Anfrage zurückgegebenen Feld überein; über dieses Feld kann die Zuordnung der Aufgaben erfolgen.

Fehlerbehandlung

Wenn beim Aufrufen der API ein Fehler auftritt, gibt die API den entsprechenden Fehlercode und die zugehörige Information zurück. Zum Beispiel:
  • 400 token_mismatched:Ungültige Anfrage, möglicherweise aufgrund fehlender oder ungültiger Parameter.
  • 400 api_not_implemented:Ungültige Anfrage, möglicherweise aufgrund fehlender oder ungültiger Parameter.
  • 401 invalid_token:Nicht autorisiert, ungültiges oder fehlendes Autorisierungstoken.
  • 429 too_many_requests:Zu viele Anfragen, Sie haben das Ratenlimit überschritten.
  • 500 api_error:Interner Serverfehler, auf dem Server ist etwas schiefgelaufen.

Beispiel für eine Fehlerantwort

Fazit

Durch dieses Dokument haben Sie bereits erfahren, wie Sie die Seedance Videos Generation API für Text-zu-Video, die Generierung mit erstem und letztem Bild sowie multimodale Referenzgenerierung verwenden und wie Sie mit Seedance 2.5 Videos bearbeiten oder verlängern. Wir hoffen, dass dieses Dokument Ihnen bei der API-Integration helfen kann; bei Fragen wenden Sie sich bitte an den technischen Support.