/ai/v1/videos zur Videogenerierung. Für bestehende Clients mit /v1/videos steht das Beispiel für das kompatible Protokoll zur Verfügung.
Voraussetzungen
- Halten Sie einen gültigen AIHubMix API Key bereit und lesen Sie ihn aus der Umgebungsvariablen
AIHUBMIX_API_KEY. - Aktivieren Sie vor der Verwendung der neuen Videoschnittstelle asynchrone Aufgaben in der Konsole und stellen Sie sicher, dass Ihr Konto über ausreichend Guthaben und die Berechtigung zur Nutzung des Zielmodells verfügt.
- Die abgebildete Person muss den vorgesehenen Verwendungszwecken zustimmen und den Bestätigungsablauf auf der Webseite persönlich abschließen. Fügen Sie einer Asset-Gruppe ausschließlich Assets derselben Person hinzu.
- Bereiten Sie eine direkte Bild-URL vor, die der Modellanbieter abrufen kann und die während der gesamten Asset-Verarbeitung gültig bleibt.
- Die Befehlszeilenbeispiele benötigen Bash, curl und jq. Führen Sie die Schritte im selben Terminal aus und bewahren Sie die zurückgegebenen IDs der Asset-Gruppe, der Bestätigungssitzung, des Assets und der Videoaufgabe auf.
Der offizielle BytePlus-Leitfaden zu Assets realer Personen behandelt Seedance 2.0 und Seedance 2.5. Das Hauptbeispiel für die neue Videoschnittstelle auf dieser Seite verwendet die im Produktivbetrieb geprüfte AIHubMix-Modell-ID
doubao-seedance-2-5-260628; maßgeblich für konkrete Versionen, Referenzmedientypen und Parameter sind das aktuelle Modell-Schema und die für Ihr Konto verfügbaren Funktionen. Den Umfang der Prüfung beschreibt Validierung dieses Ablaufs. Daraus lässt sich keine Unterstützung für Assets realer Personen in allen Seedance-Versionen ableiten.
- Asset-Gruppe erstellen
name. Der Name darf nicht leer sein und darf höchstens 100 Zeichen enthalten. Bei erfolgreicher Erstellung wird HTTP 201 zurückgegeben; der Anfangsstatus lautet pending_auth.
Die öffentlichen Felder einer Asset-Gruppe sind id, object, name, status, created_at und updated_at. object hat den festen Wert asset_group; Zeitfelder enthalten Unix-Zeitstempel in Sekunden. Der Status status=active zeigt anschließend an, dass der Gruppe Assets hinzugefügt werden können.
Falls die Erstellungsantwort verloren geht, fragen Sie zunächst die Liste ab, um eine unmittelbare doppelte Erstellung zu vermeiden:
data, has_more und next_after zurück. Übergeben Sie für die nächste Seite after mit dem Wert von next_after der vorherigen Seite; limit beträgt standardmäßig 20 und höchstens 100. Der Name dient nicht als Idempotenzkennung. Identifizieren Sie Asset-Gruppen anhand ihrer ID und ihres Erstellungszeitpunkts.
- Link zur persönlichen Bestätigung abrufen
Erstellen Sie eine Bestätigungssitzung. Ein Anfragekörper ist nicht erforderlich:
201 zurückgegeben. Die öffentlichen Felder sind id, object, group_id, status, created_at, expires_at und completed_at. object hat den festen Wert verification_session; Zeitfelder enthalten Unix-Zeitstempel in Sekunden. Solange die Sitzung nicht abgeschlossen ist, ist completed_at gleich null.
Die Person öffnet verification_url, prüft die auf der Seite angegebene verantwortliche Stelle und den Verwendungszweck, liest und bestätigt die zugehörigen Bedingungen und folgt den Anweisungen auf der Seite. Laut offiziellem BytePlus-Leitfaden ist hierfür die Anmeldung mit einem persönlichen BytePlus-Konto erforderlich. Falls die Seite Kamerazugriff benötigt, muss die Person das Gerät selbst bedienen und den Zugriff erlauben.
Die offizielle Seite kann Schritte wie das Hochladen von Assets enthalten. Befolgen Sie die tatsächlich angezeigten Anweisungen. Die nachfolgend beschriebene Asset-Erstellung per API muss weiterhin durchgeführt werden, damit Sie die von AIHubMix zurückgegebene Asset-ID erhalten. Verwenden Sie andere auf der Webseite angezeigte Asset-IDs nicht direkt in den API-Beispielen.
- Bestätigungsergebnis abfragen
Clients können alle 10 bis 15 Sekunden abfragen und eine lokale Wartezeitbegrenzung festlegen. Dieses Intervall ist eine Nutzungsempfehlung. Auch wenn die Webseite den Abschluss anzeigt oder eine leere Seite zurückgibt, müssen Sie vor dem Hinzufügen von Assets per API prüfen, ob die Sitzung
verified und die Asset-Gruppe active ist.
Falls eine erneute Erstellung 409 verification_session_active zurückgibt, fragen Sie zunächst die bestehende Sitzung und die Asset-Gruppe ab. Erstellen Sie nicht wiederholt neue Sitzungen, solange eine gültige Sitzung besteht, die Asset-Gruppe bereits bestätigt wurde oder das Ergebnis des vorherigen Versuchs noch auf Bestätigung wartet. Wenden Sie sich bei anhaltend ausbleibendem Abschluss an den Support.
- Asset über eine Bild-URL erstellen
Bild vorbereiten
Geben Sie eine absolute HTTP(S)-Adresse an, die eine Bilddatei zurückgibt, vorzugsweise über HTTPS. Der Link muss ohne Anmeldung oder zusätzliche Anfrageheader abrufbar sein. Lokale Pfade, interne Netzwerkadressen, Base64 und URLs mit Benutzername und Passwort eignen sich nicht für die Asset-Erstellungsschnittstelle. Die URL sollte kein#-Fragment enthalten.
Der BytePlus-Leitfaden zu Assets realer Personen empfiehlt ein klares Foto in Frontalansicht, das die folgenden Anforderungen für die Aufnahme in die Asset-Bibliothek erfüllt:
Dies sind die offiziellen Anforderungen der Asset-Bibliothek. Videomodelle können zusätzliche, eigenständige Einschränkungen für Referenz-Assets haben. Prüfen Sie vor dem Hochladen auch die Anforderungen des Zielmodells. Eine erfolgreiche HTTP-Antwort auf die Erstellung bedeutet noch nicht, dass die Asset-Verarbeitung erfolgreich abgeschlossen wurde.
Erstellungsanfrage
Ersetzen SieIMAGE_URL durch eine direkte Bild-URL, für deren Verwendung die abgebildete Person bereits ihre Zustimmung erteilt hat. Die Beispieldomain dient ausschließlich als Platzhalter und stellt kein Bild einer realen Person bereit.
Der Anfragekörper akzeptiert ausschließlich diese drei Felder.
Idempotency-Key wird im Anfrageheader übergeben, ist optional und darf höchstens 128 Byte lang sein. Führende oder nachgestellte Leerzeichen sowie Steuerzeichen sind nicht zulässig. Die Dateibeschränkungen für Audio und Video finden Sie im oben verlinkten offiziellen Leitfaden. Prüfen Sie außerdem die vom Zielmodell unterstützten Typen und Laufzeiten.
Die erstmalige Erstellung gibt üblicherweise HTTP 201 zurück, die Wiederverwendung eines vorhandenen Assets 200. Wenn das Ergebnis noch bestätigt werden muss und der Status reconciling lautet, wird 202 zurückgegeben. Lesen Sie stets den status des Objekts.
Die öffentlichen Asset-Felder sind id, object, group_id, asset_type, status, client_reference_id, created_at, updated_at und deleted_at. object hat den festen Wert asset. Eine nicht angegebene oder bereits gelöschte client_reference_id wird nicht zurückgegeben; solange das Asset nicht gelöscht ist, ist deleted_at gleich null. Zeitfelder enthalten Unix-Zeitstempel in Sekunden. Abfragen geben die ursprüngliche Bild-URL nicht zurück; bewahren Sie daher eigene Aufzeichnungen in Ihrer Anwendung auf.
- Auf die Verfügbarkeit des Assets warten
Sie können alle 10 bis 15 Sekunden abfragen und eine lokale Wartezeitbegrenzung festlegen. Das Beenden der lokalen Abfragen bricht den serverseitigen Vorgang nicht ab.
- Video mit dem Asset generieren
Verwenden Sie für die Videoreferenz die vollständige id aus der AIHubMix-Antwort auf die Asset-Erstellung im Format asset://<asset_id>. Alle in einer Anfrage referenzierten Assets müssen derselben Asset-Gruppe angehören, dem aktuellen Konto gehören und active sein. Auch die Asset-Gruppe muss weiterhin verfügbar sein.
Der Referenztyp muss mit dem bei der Asset-Erstellung angegebenen
asset_type übereinstimmen. asset:// ist für Videoreferenzfelder vorgesehen und keine Downloadadresse für den Browser.
Neues Videoprotokoll
Prüfen Sie zunächst das aktuelle Modell-Schema anhand des Endpunktpfads:duration=4, resolution="480p", aspect_ratio="3:4" und generate_audio=false. Das neue Protokoll verwendet direkt input_references[].url; ASSET_ID ist die zuvor von AIHubMix zurückgegebene Asset-ID:
duration für die angeforderte Laufzeit. Weitere zulässige Werte richten sich nach dem Modell-Schema. resolution="480p" bezeichnet die angeforderte Auflösungsstufe und garantiert keine feste Ausgabebreite oder -höhe von 480 Pixeln. Maßgeblich sind die tatsächlichen Abmessungen der generierten Datei. Für Anfangs- und Endbilder kann frame_images[].image_url.url zusammen mit frame_type verwendet werden, sofern das Modell diese Funktion unterstützt. Die vollständigen Parameter finden Sie unter Videogenerierung.
Kompatibles Videoprotokoll
Wenn ein bestehender Client/v1/videos verwendet, übergeben Sie die Referenz in content oder extra_body.content und verschachteln die URL im jeweiligen Medienobjekt. Dieses Beispiel verwendet extra_body.content:
Das kompatible Beispiel verwendet weiterhin
doubao-seedance-2-0-260128 und basiert auf den bestehenden Vorgaben der kompatiblen Schnittstelle sowie den offiziellen BytePlus-Hinweisen zu Asset-Referenzen. Die Videogenerierung mit Seedance 2.0 und die kompatible Erstellung über /v1/videos wurden bei dieser Prüfung nicht praktisch getestet. Die Validierungsergebnisse für Seedance 2.5 mit dem neuen Protokoll sind nicht direkt auf dieses Beispiel übertragbar.input_references nicht in kompatible Anfragen. Wenn content an beiden Stellen angegeben wird, überschreibt extra_body.content das content auf oberster Ebene. Es wird empfohlen, nur eine der beiden Stellen zu verwenden.
Die vom kompatiblen Protokoll zurückgegebene id ist für Abfragen über GET /v1/videos/{id} zu verwenden. Nach Abschluss erfolgt der Download über GET /v1/videos/{id}/content. Übergeben Sie kompatible IDs nicht an /ai/v1/videos zur Abfrage. Einzelheiten finden Sie unter Kompatible Videoschnittstelle.
- Video des neuen Protokolls abfragen und herunterladen
Das folgende Python-Beispiel setzt ausschließlich die vorangegangene Erstellung mit dem neuen Protokoll fort. Es liest VIDEO_ID aus der Umgebung und erstellt keine neue Aufgabe. Das Paket requests muss installiert sein.
200 bei einer Abfrage bedeutet nicht, dass die Generierung erfolgreich war. Prüfen Sie stets status. Verwenden Sie für die wiederholten Abfragen /ai/v1/videos/{id}; die einheitliche Aufgabenschnittstelle /ai/v1/tasks/{id} bietet eine schreibgeschützte Momentaufnahme.
Verwenden Sie für Abfrage und Download denselben API Key wie bei der Aufgabenerstellung. Laden Sie das Video nach Abschluss zeitnah herunter und speichern Sie es selbst. Ergebnisse haben eine Aufbewahrungsfrist, die sich nach expires_at richtet. Nach deren Ablauf kann 410 artifact_expired zurückgegeben werden.
Validierung dieses Ablaufs
Bei der Prüfung im Produktivbetrieb am 2026-09-07 wurden eine öffentlich erreichbare direkte HTTPS-URL zu einem JPEG-Bild, die von der Person selbst abgeschlossene Bestätigung auf der Webseite und die oben genannten Seedance-2.5-Parameter verwendet. Dabei wurden folgende Ergebnisse beobachtet:
Die Datei dieses Durchlaufs hatte 1,558,358 Byte. ffprobe ermittelte H.264, 24 fps, 560 × 752 Pixel, 4.041667 Sekunden und keine Audiospur. Diese Werte beziehen sich auf das Ergebnis dieses einzelnen Durchlaufs und bedeuten nicht, dass jede Anfrage dieselben Abmessungen, dieselbe Laufzeit oder dieselbe Dateigröße erzeugt.
Beim ersten Öffnen der Bestätigungsseite erschien
internal error; die anschließende API-Abfrage zeigte weiterhin pending. Die Ursache des Webseitenfehlers wurde noch nicht bestätigt. Im weiteren Verlauf dieses Tests wurde eine neue Seite einer separaten Testgruppe verwendet. Nachdem die Person die Schritte selbst abgeschlossen hatte, wurde die Sitzung als verified und die Asset-Gruppe als active bestätigt. Die neue Gruppe war lediglich das Vorgehen in diesem Test. Daraus ergibt sich keine allgemeine Empfehlung zum wiederholten Neuerstellen von Asset-Gruppen und auch keine Aussage darüber, dass die ursprüngliche Sitzung beendet war.
Bei dieser Prüfung wurden die Videogenerierung mit Seedance 2.0, die Erstellung über die kompatible Schnittstelle, Audio- und Video-Assets, Anfangs- und Endbilder, Löschvorgänge sowie weitere Kombinationen von Fehlerfällen nicht praktisch getestet. Die zugehörigen Erläuterungen beruhen weiterhin auf den Schnittstellenvorgaben und offiziellen Unterlagen. Diese Validierung deckt nicht alle Szenarien des gesamten Leitfadens ab.
Idempotente Wiederholungsversuche
- Wenn die Asset-Erstellung das Zeitlimit überschreitet oder die Antwort verloren geht, behalten Sie den ursprünglichen
Idempotency-Key, dieclient_reference_id, die URL und denasset_typebei und senden dieselbe Anfrage erneut. Sobald eine der beiden Kennungen ein vorhandenes Asset desselben Kontos und derselben Asset-Gruppe identifiziert, wird dieses Asset wiederverwendet. - Wenn sich die URL oder der
asset_typebei gleicher Kennung ändert, wird409 asset_idempotency_conflictzurückgegeben. Auch die Aktualisierung einer signierten Bild-URL gilt als URL-Änderung. - Ohne eine der beiden Kennungen ist eine anfrageübergreifende Deduplizierung nicht garantiert. Verwenden Sie eine neue Kennung nur, wenn Sie tatsächlich ein weiteres Asset erstellen möchten.
- Sobald eine Asset-ID vorliegt, fragen Sie bevorzugt über
GET /ai/v1/assets/{id}ab.reconcilingbedeutet nicht, dass der Vorgang fehlgeschlagen ist; erstellen Sie das Asset nicht erneut mit einer neuen Kennung. - Nach abgeschlossener Asset-Löschung werden die ursprünglichen Idempotenzkennungen nicht mehr aufbewahrt. Verlassen Sie sich nicht darauf, damit gelöschte Assets wiederzufinden, und senden Sie alte Erstellungsanfragen nicht erneut.
- Die Idempotenzregeln dieses Abschnitts gelten ausschließlich für die Asset-Erstellung. Sie sind nicht auf die Erstellung von Asset-Gruppen, Bestätigungssitzungen oder Videos übertragbar. Falls die Antwort auf eine Videoerstellung mit dem neuen Protokoll verloren geht, suchen Sie zuerst mit
GET /ai/v1/videos?limit=20&order=descnach der ursprünglichen Aufgabe, um eine doppelte Generierung zu vermeiden.
Assets und Asset-Gruppen löschen
Prüfen Sie vor dem Löschen, ob alle Videoaufgaben, die das Asset referenzieren, beendet sind, einschließlich der über die kompatible Schnittstelle übermittelten Aufgaben. Löschvorgänge können nicht rückgängig gemacht werden. Bereits heruntergeladene Videodateien verwalten Sie selbst. Einzelnes Asset löschen:202 bedeutet, dass die Löschung noch verarbeitet wird. Fragen Sie über GET /ai/v1/assets/{id} weiter ab, bis status=deleted erreicht ist. Eine wiederholte Löschanfrage gibt den aktuellen Status zurück. Bei reconciling prüfen Sie das Ergebnis weiter und wenden sich bei anhaltend ausbleibendem Abschluss an den Support.
Beim Löschen einer gesamten Asset-Gruppe werden auch die darin enthaltenen Assets gelöscht. Hierfür muss ausdrücklich cascade=true übergeben werden:
202 zurückgegeben. Fragen Sie über GET /ai/v1/asset-groups/{id} ab. deleting bedeutet, dass die Verarbeitung läuft, partially_deleted, dass noch nicht alles gelöscht wurde, und erst deleted bestätigt den Abschluss. Gelöschte Asset-Gruppen werden standardmäßig nicht in der Liste angezeigt.
409 asset_group_in_use bedeutet, dass noch Vorgänge oder Videoaufgaben ausstehen. Warten Sie, fragen Sie die zugehörigen Statuswerte ab und versuchen Sie es anschließend erneut. Den Abschluss kompatibler Videoaufgaben müssen Sie selbst prüfen. Verlassen Sie sich nicht darauf, dass die Löschanfrage automatisch die Nutzung durch alle kompatiblen Aufgaben erkennt.
Häufige Fragen
Warum kann ich nach Abschluss der Schritte auf der Webseite noch keine Assets hinzufügen?
Fragen Sie zuerst die Bestätigungssitzung und die Asset-Gruppe ab. Maßgeblich sindverified und active. Führen Sie dieselbe Prüfung auch bei internal error auf der Webseite durch. Erstellen Sie während pending nicht wiederholt Sitzungen für dieselbe Gruppe. Falls das Ergebnis noch nicht bestätigt ist, fragen Sie später erneut ab. Wenden Sie sich bei anhaltend ausbleibendem Abschluss unter Angabe der IDs an den Support. Der Bestätigungslink und Fotos der Person müssen nicht übermittelt werden.
Warum schlägt die Videogenerierung trotz verfügbarem Asset fehl?
Prüfen Sie, ob die Referenz die von AIHubMix zurückgegebene Asset-ID verwendet, alle Assets derselben Gruppe angehören, die Medientypen übereinstimmen und das aktuelle Modell die jeweiligen Eingaben unterstützt.active bestätigt die Verfügbarkeit des Assets. Abschlussstatus und Fehlermeldungen der Videoaufgabe müssen weiterhin gesondert geprüft werden.
Wie gehe ich mit häufigen Schnittstellenfehlern um?
Weitere Videofehler finden Sie unter Fehlercodes für asynchrone Aufgaben. Geben Sie bei einer Supportanfrage den Zeitpunkt, den HTTP-Status,
error.code, die zurückgegebene error.tid (falls vorhanden) und die zugehörigen Ressourcen-IDs an. Übermitteln Sie keinen API Key, keinen Bestätigungslink und keine signierte Bild-URL.
Referenzen
- BytePlus: Assets realer Personen hinzufügen
- BytePlus: Porträtvideos mit Seedance generieren
- Native AIHubMix-Videogenerierung
- OpenAI-kompatible Videoschnittstelle
- Asynchrone Aufgaben