> ## Documentation Index > Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt > Use this file to discover all available pages before exploring further. # Leitfaden zu Doubao-Assets realer Personen > Assets realer Personen nach persönlicher Bestätigung auf einer Webseite erstellen, mit asset:// für die Videogenerierung mit Doubao Seedance referenzieren, abfragen, erneut anfordern und löschen. 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](#compatible-video) 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](/de/api/async-tasks) 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](#verified-flow). 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: ```bash theme={null} set -euo pipefail : "${AIHUBMIX_API_KEY:?请先配置 AIHUBMIX_API_KEY 环境变量}" BASE_URL="https://aihubmix.com" MODEL="doubao-seedance-2-5-260628" ```

1. Asset-Gruppe erstellen

```bash theme={null} GROUP_JSON=$(curl --fail-with-body -sS --max-time 60 \ -X POST "$BASE_URL/ai/v1/asset-groups" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"我的真人素材"}') printf '%s\n' "$GROUP_JSON" | jq . GROUP_ID=$(printf '%s' "$GROUP_JSON" | jq -er '.id') ``` 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: ```bash theme={null} curl --fail-with-body -sS "$BASE_URL/ai/v1/asset-groups?limit=20" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq . ``` 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.

2. Link zur persönlichen Bestätigung abrufen

Erstellen Sie eine Bestätigungssitzung. Ein Anfragekörper ist nicht erforderlich: ```bash theme={null} SESSION_JSON=$(curl --fail-with-body -sS --max-time 60 \ -X POST "$BASE_URL/ai/v1/asset-groups/$GROUP_ID/verification-sessions" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY") SESSION_ID=$(printf '%s' "$SESSION_JSON" | jq -er '.id') printf '%s' "$SESSION_JSON" | jq '{id, status, expires_at, verification_url}' ``` 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.

3. Bestätigungsergebnis abfragen

```bash theme={null} curl --fail-with-body -sS "$BASE_URL/ai/v1/verification-sessions/$SESSION_ID" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq . curl --fail-with-body -sS "$BASE_URL/ai/v1/asset-groups/$GROUP_ID" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq . ``` | Sitzungsstatus | Nächster Schritt | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `creating` | Die Sitzung wird noch erstellt. Fragen Sie später erneut ab und wenden Sie sich bei anhaltend ausbleibendem Abschluss an den Support. | | `pending` | Die persönliche Bestätigung oder die Bestätigung des Ergebnisses steht noch aus. Fragen Sie später erneut ab. | | `verified` | Die persönliche Bestätigung ist abgeschlossen. Prüfen Sie zusätzlich, ob die Asset-Gruppe `active` ist. | | `rejected` | Dieser Versuch wurde nicht bestätigt. Prüfen Sie die Hinweise auf der Webseite und starten Sie einen neuen Versuch. | | `expired` | Dieser Versuch ist abgelaufen. Starten Sie die Bestätigung erneut. | | `failed` | Dieser Versuch ist fehlgeschlagen. Prüfen Sie die Fehlermeldung und wenden Sie sich bei Bedarf an den Support. | 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](/de/FAQs/Feedback). 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.

4. 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](https://docs.byteplus.com/en/docs/ModelArk/2315856) empfiehlt ein klares Foto in Frontalansicht, das die folgenden Anforderungen für die Aufnahme in die Asset-Bibliothek erfüllt: | Eigenschaft | Anforderung | | ------------------- | ----------------------------------------------------------------------------- | | Format | JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, HEIF | | Dateigröße pro Bild | Kleiner als 30 MB | | Seitenverhältnis | Größer als 0.4 und kleiner als 2.5 | | Breite und Höhe | Jeweils größer als 300 Pixel und kleiner als 6000 Pixel | | Person | Dieselbe Person, die die Bestätigung für diese Asset-Gruppe abgeschlossen hat | 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. ```bash theme={null} IMAGE_URL="https://cdn.example.com/portrait.jpg" ASSET_KEY="portrait-image-001" ASSET_BODY=$(jq -n --arg url "$IMAGE_URL" --arg ref "$ASSET_KEY" \ '{url: $url, asset_type: "image", client_reference_id: $ref}') ASSET_JSON=$(curl --fail-with-body -sS --max-time 60 \ -X POST "$BASE_URL/ai/v1/asset-groups/$GROUP_ID/assets" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $ASSET_KEY" \ -d "$ASSET_BODY") printf '%s\n' "$ASSET_JSON" | jq . ASSET_ID=$(printf '%s' "$ASSET_JSON" | jq -er '.id') ``` | Anfragefeld | Pflicht | Beschreibung | | --------------------- | ------- | ---------------------------------------------------------------- | | `url` | Ja | Erreichbare Adresse der Asset-Datei | | `asset_type` | Ja | `image`, `video` oder `audio`; dieses Beispiel verwendet `image` | | `client_reference_id` | Nein | Asset-Kennung Ihrer Anwendung, höchstens 128 Byte | 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.

5. Auf die Verfügbarkeit des Assets warten

```bash theme={null} curl --fail-with-body -sS "$BASE_URL/ai/v1/assets/$ASSET_ID" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq . ``` | Asset-Status | Bedeutung und Vorgehen | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `creating` | Die Erstellung ist noch nicht abgeschlossen. Bewahren Sie die ID auf und fragen Sie später erneut ab. | | `processing` | Die Verarbeitung läuft. Fragen Sie weiter ab. | | `active` | Als Referenz-Asset für Videos verwendbar. | | `failed` | Die Asset-Verarbeitung ist fehlgeschlagen. Prüfen Sie das Bild und die Anforderungen an die Übereinstimmung der Person. | | `reconciling` | Das Ergebnis der Erstellung oder Löschung muss noch bestätigt werden. Fragen Sie weiter ab und verwenden Sie das Asset vorerst nicht für Videos. | | `deleting` | Die Löschung wird verarbeitet. Verwenden Sie das Asset vorerst nicht für Videos. | | `deleted` | Die Löschung ist abgeschlossen. Verwenden Sie das Asset nicht mehr für Videos. | 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.

6. 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://`. 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. | Asset-Typ | Neues `input_references[].type` | Verschachteltes Feld im kompatiblen Protokoll | | --------- | ------------------------------- | --------------------------------------------- | | `image` | `image_url` | `image_url.url` | | `video` | `video_url` | `video_url.url` | | `audio` | `audio_url` | `audio_url.url` | 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: ```bash theme={null} curl --fail-with-body -sS "$BASE_URL/call/schema/models/$MODEL/endpoints" \ | jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema' ``` 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: ```bash theme={null} VIDEO_BODY=$(jq -n --arg model "$MODEL" --arg asset "asset://$ASSET_ID" \ '{model: $model, prompt: "The person in the reference image smiles and waves at the camera.", duration: 4, resolution: "480p", aspect_ratio: "3:4", generate_audio: false, input_references: [{type: "image_url", url: $asset}]}') VIDEO_JSON=$(curl --fail-with-body -sS --max-time 120 \ -X POST "$BASE_URL/ai/v1/videos" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" \ -H "Content-Type: application/json" \ -d "$VIDEO_BODY") printf '%s\n' "$VIDEO_JSON" | jq . VIDEO_ID=$(printf '%s' "$VIDEO_JSON" | jq -er '.id') export VIDEO_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](/de/api/aihubmix-video-generation).

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. ```bash theme={null} COMPAT_MODEL="doubao-seedance-2-0-260128" COMPAT_BODY=$(jq -n --arg model "$COMPAT_MODEL" --arg asset "asset://$ASSET_ID" \ '{model: $model, prompt: "The person in the reference image smiles and waves at the camera.", extra_body: {content: [{type: "image_url", image_url: {url: $asset}, role: "reference_image"}]}}') curl --fail-with-body -sS --max-time 120 \ -X POST "$BASE_URL/v1/videos" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" \ -H "Content-Type: application/json" \ -d "$COMPAT_BODY" | jq . ``` 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](/de/api/Video-Gen).

7. 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. ```python theme={null} import os import time from pathlib import Path import requests base_url = "https://aihubmix.com" video_id = os.environ["VIDEO_ID"] headers = {"Authorization": f"Bearer {os.environ['AIHUBMIX_API_KEY']}"} deadline = time.monotonic() + 1800 while time.monotonic() < deadline: response = requests.get( f"{base_url}/ai/v1/videos/{video_id}", headers=headers, timeout=30 ) response.raise_for_status() task = response.json() status = task["status"] if status == "completed": break if status in {"failed", "cancelled"}: raise RuntimeError(f"视频任务未完成：{task.get('error') or status}") time.sleep(15) else: raise TimeoutError(f"本地等待已结束，请稍后继续查询原任务：{video_id}") temporary = Path("result.mp4.part") with requests.get( f"{base_url}/ai/v1/videos/{video_id}/content", headers=headers, timeout=120, stream=True, ) as response: response.raise_for_status() with temporary.open("wb") as output: for chunk in response.iter_content(chunk_size=1024 * 1024): if chunk: output.write(chunk) temporary.replace("result.mp4") print("视频已保存为 result.mp4") ``` 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: | Schritt | Ergebnis dieser Prüfung | | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | Asset-Gruppe erstellen | HTTP `201`, `status=pending_auth` | | Bestätigungssitzung erstellen | HTTP `201`, `status=pending` | | Nach persönlicher Bestätigung abfragen | Sitzung mit HTTP `200`, `status=verified`; Asset-Gruppe `active` | | Bild-Asset erstellen und abfragen | Erstellung mit HTTP `201`, `status=processing`; spätere Abfrage mit HTTP `200`, `status=active` | | Video mit dem neuen Protokoll erstellen und abfragen | Erstellung mit HTTP `200`, `status=in_progress`; spätere Abfrage mit HTTP `200`, `status=completed`, `error=null` | | Video herunterladen | HTTP `200`, `Content-Type: video/mp4`; vollständige Dekodierung der Datei mit ffmpeg erfolgreich | 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: ```bash theme={null} curl --fail-with-body -sS -X DELETE "$BASE_URL/ai/v1/assets/$ASSET_ID" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq . ``` 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: ```bash theme={null} curl --fail-with-body -sS -X DELETE \ "$BASE_URL/ai/v1/asset-groups/$GROUP_ID?cascade=true" \ -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq . ``` 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?

| HTTP | `error.code` | Vorgehen | | ---- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | 400 | `invalid_request` | Anfragefelder, Struktur und verwendetes Videoprotokoll prüfen | | 400 | `asset_group_invalid` | Namen der Asset-Gruppe prüfen | | 400 | `asset_invalid` | URL, Asset-Typ und Anfragekennungen prüfen | | 400 | `asset_binding_mismatch` | In einer Videoanfrage ausschließlich Assets derselben Asset-Gruppe referenzieren | | 400 | `cascade_confirmation_required` | Nach Bestätigung der beabsichtigten Löschung der gesamten Gruppe `cascade=true` übergeben | | 401 | `authentication_failed` | API-Key-Umgebungsvariable und Authentifizierungsheader prüfen | | 403 | `async_not_enabled` | Asynchrone Aufgaben aktivieren, bevor die neue Videoschnittstelle verwendet wird | | 404 | `asset_group_not_found`, `asset_not_found`, `verification_session_not_found` | Ressourcen-ID und zugehöriges Konto prüfen | | 409 | `asset_group_not_verified` | Ergebnis der persönlichen Bestätigung abfragen und auf die Verfügbarkeit der Asset-Gruppe warten | | 409 | `verification_session_active` | Bestehende Sitzung oder Asset-Gruppe abfragen und doppelte Erstellung vermeiden | | 409 | `asset_not_ready` | Asset-Status abfragen und vor der Videogenerierung auf `active` warten | | 409 | `asset_idempotency_conflict` | Ursprüngliche URL und Typ der Kennung prüfen | | 409 | `asset_group_in_use` | Vor dem Löschen auf den Abschluss der zugehörigen Vorgänge und Videoaufgaben warten | | 503 | `asset_group_unavailable`, `verification_unavailable`, `asset_unavailable` | Später erneut versuchen; bei anhaltender Nichtverfügbarkeit den Support kontaktieren | Weitere Videofehler finden Sie unter [Fehlercodes für asynchrone Aufgaben](/de/api/async-tasks#error-codes). 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](https://docs.byteplus.com/en/docs/ModelArk/2315856) * [BytePlus: Porträtvideos mit Seedance generieren](https://docs.byteplus.com/en/docs/ModelArk/2608626) * [Native AIHubMix-Videogenerierung](/de/api/aihubmix-video-generation) * [OpenAI-kompatible Videoschnittstelle](/de/api/Video-Gen) * [Asynchrone Aufgaben](/de/api/async-tasks) Zuletzt aktualisiert: 2026-09-07