Skip to main content
Assets realer Personen dienen dazu, das Erscheinungsbild einer Person in Videos zu referenzieren, nachdem diese Person es selbst bestätigt hat. Der Ablauf umfasst das Erstellen einer Asset-Gruppe, die persönliche Bestätigung auf einer Webseite, das Hinzufügen von Assets, das Warten auf deren Verfügbarkeit und anschließend das Erstellen einer Videoaufgabe. Diese Seite erläutert die Asset-Verwaltung über die AIHubMix API anhand von Bild-Assets und verwendet vorzugsweise den neuen Endpunkt /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.
Bereiten Sie die Terminalumgebung vor. Der API Key sollte bereits von Ihrer Laufzeitumgebung bereitgestellt worden sein:

  1. Asset-Gruppe erstellen

Der Anfragekörper akzeptiert ausschließlich 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:
Die Liste gibt 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.

  1. Link zur persönlichen Bestätigung abrufen

Erstellen Sie eine Bestätigungssitzung. Ein Anfragekörper ist nicht erforderlich:
Bei erfolgreicher Erstellung wird HTTP 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.
verification_url wird ausschließlich in der erfolgreichen Erstellungsantwort zurückgegeben. Spätere Abfragen enthalten den Link nicht erneut. Geben Sie ihn zeitnah an die abgebildete Person weiter und nehmen Sie ihn nicht in öffentliche Protokolle, Code-Repositories oder Screenshots für Supportanfragen auf. Die Gültigkeitsdauer richtet sich nach expires_at; nach Ablauf kann der ursprüngliche Link nicht weiterverwendet werden.
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.

  1. 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.
Die Meldung internal error auf der Webseite bedeutet nicht, dass die Bestätigungssitzung beendet ist. Führen Sie zunächst die beiden GET-Anfragen dieses Abschnitts aus, um Sitzung und Asset-Gruppe abzufragen. Solange die Sitzung pending ist, erstellen Sie nicht wiederholt Sitzungen für dieselbe Gruppe. Fügen Sie erst dann Assets hinzu, wenn die Sitzung verified und die Asset-Gruppe active ist. Aus dem Webseitenfehler allein lässt sich die Ursache nicht bestimmen. Bewahren Sie bei anhaltend ausbleibendem Abschluss die IDs auf und wenden Sie sich an den Support.

  1. 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 Sie IMAGE_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.

  1. 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.
Wenn das Erstellungsergebnis unbekannt ist und dauerhaft kein zugehöriges Ergebnis gefunden wird, kann das Asset im Status reconciling verbleiben. Dies kann auch die Löschung des Assets oder der Asset-Gruppe beeinträchtigen. Bewahren Sie die ID und die ursprünglichen Anfragekennungen auf und wenden Sie sich an den Support. Erstellen Sie nicht wiederholt Assets mit geänderten Kennungen und gehen Sie nicht davon aus, dass nach einer Wartezeit automatisch eine Bereinigung erfolgt.

  1. 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:
Senden Sie die Anfrage, nachdem Sie die Unterstützung für Referenzbilder bestätigt haben. Das folgende Beispiel verwendet die in dieser Prüfung im Produktivbetrieb erfolgreich getesteten Seedance-2.5-Parameter: 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:
Das neue Protokoll verwendet eine ganzzahlige 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.
Führen Sie eines der beiden Beispiele aus; jede Videoerstellung ist eine eigenständige Anfrage. Mischen Sie 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.

  1. 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.
Die 30 Minuten sind die lokale Wartezeitbegrenzung dieses Beispiels und entsprechen keinem serverseitigen Aufgabenzeitlimit. HTTP 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, die client_reference_id, die URL und den asset_type bei 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_type bei gleicher Kennung ändert, wird 409 asset_idempotency_conflict zurü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. reconciling bedeutet 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=desc nach 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:
Eine Antwort mit 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:
Nach Annahme wird 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 sind verified 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

Zuletzt aktualisiert: 2026-09-07