> ## 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.
# Guide des ressources de personnes réelles pour Doubao
> Créez des ressources de personnes réelles après confirmation par la personne sur le Web, utilisez les références asset:// avec Doubao Seedance pour générer des vidéos, puis consultez, relancez et supprimez vos ressources.
Les ressources de personnes réelles permettent de faire référence, dans une vidéo, à l'apparence d'une personne ayant elle-même donné sa confirmation. Le processus consiste à créer un groupe de ressources, à faire effectuer la confirmation sur le Web par la personne concernée, à ajouter une ressource, à attendre sa disponibilité, puis à soumettre une tâche de génération vidéo.
Cette page prend pour exemple une ressource image, utilise l'API AIHubMix pour gérer les ressources et privilégie la nouvelle API `/ai/v1/videos` pour générer les vidéos. Les clients utilisant déjà `/v1/videos` peuvent consulter l'[exemple du protocole compatible](#compatible-video).
Prérequis
* Préparez une clé API AIHubMix valide, lue depuis la variable d'environnement `AIHUBMIX_API_KEY`.
* Avant d'utiliser la nouvelle API vidéo, activez les [tâches asynchrones](/fr/api/async-tasks) dans la console et vérifiez que le compte dispose d'un solde suffisant et des droits d'accès au modèle cible.
* La personne représentée dans les ressources doit consentir aux utilisations prévues et effectuer elle-même la confirmation sur le Web. Un groupe de ressources doit contenir uniquement les ressources d'une même personne.
* Préparez un lien direct vers l'image, accessible au fournisseur de modèles, et assurez-vous qu'il reste valide pendant le traitement de la ressource.
* Les exemples en ligne de commande nécessitent Bash, curl et jq. Exécutez les étapes dans le même terminal et conservez les ID du groupe de ressources, de la session de confirmation, de la ressource et de la tâche vidéo renvoyés.
Le guide officiel BytePlus sur les ressources de personnes réelles couvre Seedance 2.0 et Seedance 2.5. L'exemple principal de la nouvelle API vidéo sur cette page utilise l'ID de modèle AIHubMix `doubao-seedance-2-5-260628`, validé en production ; les versions, types de médias de référence et paramètres disponibles dépendent du Schema actuel du modèle et des capacités accessibles au compte. Consultez la [validation de ce processus](#verified-flow) pour connaître le périmètre vérifié, sans en déduire que toutes les versions de Seedance acceptent les ressources de personnes réelles.
Préparez l'environnement du terminal. La clé API doit déjà être injectée par votre environnement d'exécution :
```bash theme={null}
set -euo pipefail
: "${AIHUBMIX_API_KEY:?请先配置 AIHUBMIX_API_KEY 环境变量}"
BASE_URL="https://aihubmix.com"
MODEL="doubao-seedance-2-5-260628"
```
1. Créer un groupe de ressources
```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')
```
Le corps de la requête accepte uniquement `name`. Le nom doit être non vide et comporter au maximum 100 caractères. Une création réussie renvoie HTTP `201`, avec le statut initial `pending_auth`.
Les champs publics du groupe sont `id`, `object`, `name`, `status`, `created_at` et `updated_at`. La valeur de `object` est toujours `asset_group` et les champs temporels sont exprimés en secondes Unix. Le statut `status=active` indique ensuite que des ressources peuvent être ajoutées au groupe.
Si la réponse de création est perdue, consultez d'abord la liste pour éviter de créer immédiatement un doublon :
```bash theme={null}
curl --fail-with-body -sS "$BASE_URL/ai/v1/asset-groups?limit=20" \
-H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq .
```
La liste renvoie `data`, `has_more` et `next_after`. Pour la page suivante, passez dans `after` la valeur de `next_after` de la page précédente ; `limit` vaut `20` par défaut, avec un maximum de `100`. Le nom ne sert pas d'identifiant d'idempotence : identifiez le groupe à l'aide de son ID et de sa date de création.
2. Obtenir le lien de confirmation personnelle
Créez une session de confirmation, sans corps de requête :
```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}'
```
Une création réussie renvoie HTTP `201`. Les champs publics sont `id`, `object`, `group_id`, `status`, `created_at`, `expires_at` et `completed_at`. La valeur de `object` est toujours `verification_session`, les champs temporels sont exprimés en secondes Unix et `completed_at` vaut `null` tant que la session n'est pas terminée.
`verification_url` est renvoyé uniquement dans la réponse de création réussie ; les consultations ultérieures ne renvoient plus ce lien. Transmettez-le rapidement à la personne représentée dans les ressources et ne l'incluez pas dans des journaux publics, des dépôts de code ou des captures d'écran destinées au support. Sa validité est définie par `expires_at` ; le lien initial ne peut plus être utilisé après son expiration.
La personne concernée ouvre `verification_url`, vérifie l'entité et l'utilisation présentées sur la page, lit et accepte les conditions applicables, puis suit les instructions affichées. Le guide officiel BytePlus indique que cette procédure nécessite une connexion à un compte personnel BytePlus ; si la page demande l'accès à la caméra, la personne doit manipuler elle-même l'appareil et accorder cette autorisation.
La page officielle peut inclure des étapes telles que l'importation de ressources ; suivez les instructions effectivement affichées. L'étape suivante de création de ressource par API reste nécessaire pour obtenir l'ID de ressource renvoyé par AIHubMix ; n'utilisez pas directement d'autres ID de ressources affichés sur la page Web dans les exemples d'API.
3. Consulter le résultat de la confirmation
```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 .
```
| Statut de la session | Étape suivante |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `creating` | La session est encore en cours de création ; consultez-la plus tard et contactez le support si elle reste inachevée |
| `pending` | En attente de l'action de la personne ou de la confirmation du résultat ; consultez à nouveau plus tard |
| `verified` | La confirmation personnelle est terminée ; vérifiez ensuite que le groupe de ressources est `active` |
| `rejected` | Cette tentative a été refusée ; vérifiez les indications de la page Web avant de recommencer |
| `expired` | Cette tentative a expiré ; lancez une nouvelle confirmation |
| `failed` | Cette tentative a échoué ; vérifiez le message d'erreur et contactez le support si nécessaire |
Le client peut consulter le statut toutes les 10 à 15 secondes et définir une durée maximale d'attente locale. Cet intervalle constitue une recommandation d'utilisation. Même si la page Web indique que l'opération est terminée ou affiche une page vide, vérifiez par API que la session est `verified` et que le groupe est `active` avant d'ajouter des ressources.
Si une nouvelle création renvoie `409 verification_session_active`, consultez d'abord la session existante et le groupe de ressources. Évitez les créations répétées lorsqu'une session valide existe encore, que la confirmation du groupe est déjà terminée ou que le résultat précédent reste à confirmer. Contactez le [support](/fr/FAQs/Feedback) si le processus reste inachevé.
L'affichage de `internal error` sur la page Web ne signifie pas que la session de confirmation est terminée. Exécutez d'abord les deux requêtes GET de cette section pour consulter la session et le groupe ; tant que la session reste `pending`, ne créez pas de sessions répétées pour ce groupe. Ajoutez des ressources uniquement lorsque la session est `verified` et le groupe `active`. L'erreur de la page Web seule ne permet pas d'en déterminer la cause ; si le processus reste inachevé, conservez les ID et contactez le support.
4. Créer une ressource à partir d'une adresse d'image
Préparer l'image
Fournissez une adresse HTTP(S) absolue renvoyant un fichier image, de préférence en HTTPS. Le lien doit être accessible sans connexion ni en-têtes supplémentaires ; les chemins locaux, adresses de réseau interne, données Base64 et URL contenant un nom d'utilisateur et un mot de passe ne conviennent pas à l'API de création de ressources. L'URL ne doit pas contenir de fragment `#`.
Selon le [guide BytePlus sur les ressources de personnes réelles](https://docs.byteplus.com/en/docs/ModelArk/2315856), il est recommandé d'utiliser une photo nette de face respectant les exigences suivantes pour l'ajout à la bibliothèque de ressources :
| Élément | Exigence |
| ----------------------- | ----------------------------------------------------------------------------- |
| Format | JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, HEIF |
| Taille par image | Inférieure à 30 MB |
| Rapport largeur/hauteur | Supérieur à 0.4 et inférieur à 2.5 |
| Largeur et hauteur | Toutes deux supérieures à 300 pixels et inférieures à 6000 pixels |
| Personne | Identique à celle ayant effectué la confirmation pour ce groupe de ressources |
Ces exigences sont celles de la bibliothèque officielle de ressources ; le modèle vidéo peut imposer des restrictions distinctes aux ressources de référence. Vérifiez également les exigences du modèle cible avant l'importation ; la réussite de la création HTTP ne signifie pas que le traitement de la ressource a abouti.
Requête de création
Remplacez `IMAGE_URL` par le lien direct vers une image dont la personne concernée a autorisé l'utilisation. Le domaine de l'exemple est un espace réservé et ne fournit aucune image de personne réelle.
```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')
```
| Champ de requête | Obligatoire | Description |
| --------------------- | ----------- | ---------------------------------------------------------------- |
| `url` | Oui | Adresse accessible du fichier de ressource |
| `asset_type` | Oui | `image`, `video` ou `audio` ; cet exemple utilise `image` |
| `client_reference_id` | Non | Identifiant de ressource côté application, de 128 octets maximum |
Le corps de la requête accepte uniquement ces trois champs. `Idempotency-Key` est un en-tête de requête facultatif, de 128 octets maximum, sans espaces en début ou en fin ni caractères de contrôle. Pour les limites des fichiers audio et vidéo, consultez le guide officiel ci-dessus et vérifiez les types et durées pris en charge par le modèle cible.
La première création renvoie généralement HTTP `201` ; la réutilisation d'une ressource existante renvoie `200` ; lorsque le résultat reste à confirmer et que le statut est `reconciling`, la réponse est `202`. Lisez toujours le champ `status` de l'objet.
Les champs publics d'une ressource sont `id`, `object`, `group_id`, `asset_type`, `status`, `client_reference_id`, `created_at`, `updated_at` et `deleted_at`. La valeur de `object` est toujours `asset` ; `client_reference_id` n'est pas renvoyé s'il n'a pas été fourni ou a été supprimé, et `deleted_at` vaut `null` tant que la ressource n'est pas supprimée. Les champs temporels sont exprimés en secondes Unix. Les consultations ne renvoient pas l'adresse d'origine de l'image : conservez vos propres enregistrements applicatifs.
5. Attendre la disponibilité de la ressource
```bash theme={null}
curl --fail-with-body -sS "$BASE_URL/ai/v1/assets/$ASSET_ID" \
-H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq .
```
| Statut de la ressource | Signification et action |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `creating` | La création n'est pas terminée ; conservez l'ID et consultez à nouveau plus tard |
| `processing` | Traitement en cours ; continuez les consultations |
| `active` | Disponible comme ressource de référence vidéo |
| `failed` | Le traitement de la ressource a échoué ; vérifiez l'image et les exigences de correspondance de la personne |
| `reconciling` | Le résultat de la création ou de la suppression reste à confirmer ; continuez les consultations et ne l'utilisez pas encore pour une vidéo |
| `deleting` | Suppression en cours ; ne l'utilisez pas pour une vidéo |
| `deleted` | Suppression terminée ; ne l'utilisez plus pour une vidéo |
Vous pouvez consulter le statut toutes les 10 à 15 secondes et définir une durée maximale d'attente locale. L'arrêt de l'interrogation périodique locale n'annule pas l'opération côté serveur.
Si le résultat de la création est inconnu et qu'aucun résultat correspondant n'est trouvé durablement, la ressource peut rester `reconciling`, ce qui peut également affecter la suppression de la ressource ou du groupe. Conservez les ID et les identifiants de la requête d'origine, puis contactez le support ; ne changez pas d'identifiants pour multiplier les créations et ne supposez pas qu'un nettoyage automatique aura lieu après un certain délai.
6. Générer une vidéo à l'aide de la ressource
La référence vidéo utilise l'`id` complet renvoyé dans la réponse de création de ressource AIHubMix, au format `asset://`. Toutes les ressources référencées dans une même requête doivent appartenir au même groupe, être détenues par le compte courant et avoir le statut `active`. Le groupe de ressources doit également rester disponible.
| Type de ressource | `input_references[].type` de la nouvelle API | Champ imbriqué de l'API compatible |
| ----------------- | -------------------------------------------- | ---------------------------------- |
| `image` | `image_url` | `image_url.url` |
| `video` | `video_url` | `video_url.url` |
| `audio` | `audio_url` | `audio_url.url` |
Le type de référence doit correspondre à l'`asset_type` utilisé lors de la création de la ressource. `asset://` s'utilise dans les champs de référence vidéo et ne constitue pas une adresse de téléchargement pour un navigateur.
Nouveau protocole vidéo
Vérifiez d'abord le Schema actuel du modèle en sélectionnant le chemin de l'endpoint :
```bash theme={null}
curl --fail-with-body -sS "$BASE_URL/call/schema/models/$MODEL/endpoints" \
| jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema'
```
Soumettez la requête après avoir confirmé que le modèle accepte les images de référence. Les paramètres ci-dessous sont ceux de Seedance 2.5 validés en production lors de ce test : `duration=4`, `resolution="480p"`, `aspect_ratio="3:4"`, `generate_audio=false`. La nouvelle API utilise directement `input_references[].url`, où `ASSET_ID` est l'ID de ressource renvoyé précédemment par AIHubMix :
```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
```
La nouvelle API utilise un entier `duration` pour la durée demandée ; les autres valeurs autorisées dépendent du Schema du modèle. `resolution="480p"` désigne le niveau de résolution demandé et ne garantit pas une largeur ou une hauteur de sortie fixée à 480 pixels ; les dimensions réelles sont celles du fichier généré. Les images de début et de fin peuvent utiliser `frame_images[].image_url.url`, avec `frame_type`, uniquement si le modèle prend en charge cette capacité. Pour l'ensemble des paramètres, consultez [Génération de vidéos](/fr/api/aihubmix-video-generation).
Protocole vidéo compatible
Pour les clients existants utilisant `/v1/videos`, placez la référence dans `content` ou `extra_body.content`, avec l'URL imbriquée dans l'objet média correspondant. Cet exemple utilise `extra_body.content` :
L'exemple compatible conserve `doubao-seedance-2-0-260128` et repose sur les conventions de l'API compatible existante et les indications officielles BytePlus relatives aux références de ressources. La génération vidéo avec Seedance 2.0 et la création compatible via `/v1/videos` n'ont pas été testées lors de cette validation ; les résultats de la nouvelle API avec Seedance 2.5 ne peuvent pas être appliqués directement à cet exemple.
```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 .
```
Exécutez un seul des deux exemples : chaque création vidéo est une requête indépendante. N'ajoutez pas `input_references` à une requête compatible. Si les deux emplacements `content` sont fournis, `extra_body.content` remplace le `content` de premier niveau ; il est recommandé de n'en fournir qu'un seul.
L'`id` renvoyé par l'API compatible doit être utilisé avec `GET /v1/videos/{id}` pour la consultation, puis avec `GET /v1/videos/{id}/content` pour le téléchargement une fois la tâche terminée. N'utilisez pas un ID de l'API compatible pour une consultation via `/ai/v1/videos`. Pour plus de détails, consultez l'[API vidéo compatible](/fr/api/Video-Gen).
7. Interroger et télécharger la vidéo de la nouvelle API
L'exemple Python suivant poursuit uniquement l'étape de création de la nouvelle API ci-dessus, lit `VIDEO_ID` dans les variables d'environnement et ne recrée pas de tâche. Il nécessite l'installation de `requests`.
```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")
```
Les 30 minutes constituent la limite d'attente locale de cet exemple et ne correspondent pas à un délai d'expiration de la tâche côté serveur. Une consultation HTTP `200` ne signifie pas que la génération a réussi : vérifiez impérativement `status`. L'interrogation périodique utilise `/ai/v1/videos/{id}` ; l'API de tâches unifiée `/ai/v1/tasks/{id}` fournit un instantané en lecture seule.
La consultation et le téléchargement de la vidéo utilisent la même clé API que la création de la tâche. Téléchargez rapidement le résultat une fois terminé et conservez-le vous-même ; sa période de conservation est définie par `expires_at`, et une requête après expiration peut renvoyer `410 artifact_expired`.
Validation de ce processus
La validation en production du 2026-09-07 a utilisé un lien direct HTTPS public vers une image JPEG, une confirmation sur le Web effectuée par la personne concernée et les paramètres Seedance 2.5 ci-dessus. Les résultats suivants ont été observés :
| Étape | Résultat de cette validation |
| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Création du groupe de ressources | HTTP `201`, `status=pending_auth` |
| Création de la session de confirmation | HTTP `201`, `status=pending` |
| Consultation après la confirmation personnelle | Session HTTP `200`, `status=verified`, groupe de ressources `active` |
| Création et consultation de la ressource image | Création HTTP `201`, `status=processing`, puis consultation HTTP `200`, `status=active` |
| Création et consultation de la vidéo avec la nouvelle API | Création HTTP `200`, `status=in_progress`, puis consultation HTTP `200`, `status=completed`, `error=null` |
| Téléchargement de la vidéo | HTTP `200`, `Content-Type: video/mp4`, décodage complet du fichier réussi avec ffmpeg |
Le fichier obtenu comptait 1,558,358 octets ; ffprobe a détecté H.264, 24 fps, 560 × 752 pixels, 4.041667 secondes et aucune piste audio. Ces valeurs décrivent le résultat de cette génération et ne garantissent pas des dimensions, une durée ou une taille de fichier identiques pour chaque requête.
La première ouverture de la page de confirmation a affiché `internal error`, puis la consultation par API indiquait toujours `pending` ; la cause de l'erreur de la page n'a pas été confirmée. Le test a ensuite utilisé une nouvelle page associée à un groupe de test indépendant ; après les opérations effectuées par la personne concernée, la session était `verified` et le groupe `active`. Le nouveau groupe correspond uniquement à la démarche suivie lors de ce test ; il ne constitue pas une recommandation générale de recréer les groupes à répétition et ne signifie pas que la session initiale était terminée.
La génération vidéo avec Seedance 2.0, la création via l'API compatible, les ressources audio et vidéo, les images de début et de fin, la suppression et les autres combinaisons d'erreurs n'ont pas été testées lors de cette validation. Les indications correspondantes restent fondées sur les conventions des API et la documentation officielle ; cette validation ne couvre pas tous les scénarios du guide.
Nouvelles tentatives idempotentes
* Si la création d'une ressource dépasse le délai d'attente ou si sa réponse est perdue, conservez les valeurs d'origine de `Idempotency-Key`, `client_reference_id`, l'URL et `asset_type`, puis renvoyez la même requête. Si l'un des deux identifiants correspond à une ressource existante du même compte et du même groupe, cette ressource est réutilisée.
* Si l'URL ou `asset_type` associé au même identifiant change, la réponse est `409 asset_idempotency_conflict`. Le renouvellement d'une URL d'image signée constitue également un changement d'URL.
* Si aucun des deux identifiants n'est fourni, la déduplication entre les requêtes n'est pas garantie. Utilisez un nouvel identifiant uniquement lorsque vous confirmez vouloir créer une autre ressource.
* Une fois l'ID de ressource obtenu, privilégiez la consultation par `GET /ai/v1/assets/{id}`. `reconciling` ne signifie pas un échec et ne justifie pas une nouvelle création avec un nouvel identifiant.
* Après la suppression complète d'une ressource, les identifiants d'idempotence d'origine ne sont plus conservés. Ne comptez pas sur eux pour retrouver une ressource supprimée et ne rejouez pas une ancienne requête de création.
* Les conventions d'idempotence de cette section s'appliquent uniquement à la création de ressources. Elles ne s'appliquent pas à la création de groupes de ressources, de sessions de confirmation ou de vidéos. Si la réponse de création vidéo de la nouvelle API est perdue, recherchez d'abord la tâche d'origine avec `GET /ai/v1/videos?limit=20&order=desc` pour éviter une génération en double.
Supprimer les ressources et les groupes de ressources
Avant toute suppression, assurez-vous que toutes les vidéos référençant la ressource sont terminées, y compris les tâches soumises via l'API compatible. La suppression est irréversible ; vous devez gérer vous-même les fichiers vidéo déjà téléchargés.
Supprimer une ressource individuelle :
```bash theme={null}
curl --fail-with-body -sS -X DELETE "$BASE_URL/ai/v1/assets/$ASSET_ID" \
-H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq .
```
Une réponse `202` indique que la suppression est encore en cours. Continuez à consulter `GET /ai/v1/assets/{id}` jusqu'à `status=deleted`. Une suppression répétée renvoie le statut courant ; s'il est `reconciling`, poursuivez la vérification du résultat et contactez le support si l'opération reste inachevée.
La suppression d'un groupe entier supprime également les ressources qu'il contient et exige de passer explicitement `cascade=true` :
```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 .
```
Après acceptation, la réponse est `202`. Consultez `GET /ai/v1/asset-groups/{id}` pour suivre l'opération. `deleting` indique un traitement en cours, `partially_deleted` une suppression encore incomplète, et seul `deleted` indique sa fin. La liste n'affiche pas les groupes supprimés par défaut.
`409 asset_group_in_use` indique que des opérations ou tâches vidéo ne sont pas encore terminées. Attendez et consultez les statuts concernés avant de réessayer. Vérifiez vous-même que les tâches vidéo compatibles sont terminées ; ne comptez pas sur la requête de suppression pour détecter automatiquement l'utilisation par toutes les tâches compatibles.
Questions fréquentes
Pourquoi ne puis-je pas ajouter de ressources après avoir terminé les opérations sur le Web ?
Consultez d'abord la session de confirmation et le groupe de ressources, en vous fiant aux statuts `verified` et `active`. Effectuez les mêmes vérifications si la page Web affiche `internal error` ; ne créez pas de sessions répétées pour le même groupe tant que le statut est `pending`. Si le résultat reste à confirmer, consultez à nouveau plus tard ; si le processus reste inachevé, contactez le support en fournissant les ID, sans transmettre le lien de confirmation ni la photo de la personne.
Pourquoi la génération vidéo échoue-t-elle alors que la ressource est disponible ?
Vérifiez que les références utilisent les ID de ressources renvoyés par AIHubMix, que toutes les ressources appartiennent au même groupe, que les types de médias correspondent et que le modèle actuel accepte les entrées concernées. Le statut `active` d'une ressource indique sa disponibilité ; le statut de fin et les erreurs de la tâche vidéo doivent être vérifiés séparément.
Comment traiter les erreurs courantes de l'API ?
| HTTP | `error.code` | Action |
| ---- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| 400 | `invalid_request` | Vérifiez les champs, la structure de la requête et le protocole vidéo utilisé |
| 400 | `asset_group_invalid` | Vérifiez le nom du groupe de ressources |
| 400 | `asset_invalid` | Vérifiez l'URL, le type de ressource et les identifiants de requête |
| 400 | `asset_binding_mismatch` | Référencez uniquement les ressources d'un même groupe dans une requête vidéo |
| 400 | `cascade_confirmation_required` | Passez `cascade=true` après avoir confirmé la volonté de supprimer le groupe entier |
| 401 | `authentication_failed` | Vérifiez la variable d'environnement de la clé API et les en-têtes d'authentification |
| 403 | `async_not_enabled` | Activez les tâches asynchrones avant d'utiliser la nouvelle API vidéo |
| 404 | `asset_group_not_found`, `asset_not_found`, `verification_session_not_found` | Vérifiez les ID des ressources et le compte auquel elles appartiennent |
| 409 | `asset_group_not_verified` | Consultez le résultat de la confirmation personnelle et attendez la disponibilité du groupe |
| 409 | `verification_session_active` | Consultez la session ou le groupe existant pour éviter les demandes répétées |
| 409 | `asset_not_ready` | Consultez le statut de la ressource et attendez `active` avant de générer une vidéo |
| 409 | `asset_idempotency_conflict` | Vérifiez l'URL et le type d'origine associés à l'identifiant |
| 409 | `asset_group_in_use` | Attendez la fin des opérations et tâches vidéo concernées avant de supprimer |
| 503 | `asset_group_unavailable`, `verification_unavailable`, `asset_unavailable` | Réessayez plus tard ; contactez le support si l'indisponibilité persiste |
Pour les autres erreurs vidéo, consultez les [codes d'erreur des tâches asynchrones](/fr/api/async-tasks#error-codes). Lors d'un signalement, fournissez l'heure de l'incident, le statut HTTP, `error.code`, la valeur renvoyée de `error.tid` si elle existe et les ID des ressources concernées ; ne transmettez pas la clé API, le lien de confirmation ni une adresse d'image signée.
Références
* [BytePlus : ajouter des ressources de personnes réelles](https://docs.byteplus.com/en/docs/ModelArk/2315856)
* [BytePlus : générer des vidéos de portrait avec Seedance](https://docs.byteplus.com/en/docs/ModelArk/2608626)
* [Génération vidéo native AIHubMix](/fr/api/aihubmix-video-generation)
* [API vidéo compatible OpenAI](/fr/api/Video-Gen)
* [Tâches asynchrones](/fr/api/async-tasks)
Dernière mise à jour : 2026-09-07