/ai/v1/videos pour générer les vidéos. Les clients utilisant déjà /v1/videos peuvent consulter l’exemple du protocole compatible.
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 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 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.
- Créer un groupe de ressources
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 :
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.
- Obtenir le lien de confirmation personnelle
Créez une session de confirmation, sans corps de requête :
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.
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.
- Consulter le résultat de la confirmation
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 si le processus reste inachevé.
- 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, il est recommandé d’utiliser une photo nette de face respectant les exigences suivantes pour l’ajout à la bibliothèque 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
RemplacezIMAGE_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.
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.
- Attendre la disponibilité de la ressource
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.
- 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://<asset_id>. 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.
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 :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 :
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.
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.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.
- 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.
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 :
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 etasset_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_typeassocié au même identifiant change, la réponse est409 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}.reconcilingne 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=descpour é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 :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 :
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 statutsverified 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 statutactive 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 ?
Pour les autres erreurs vidéo, consultez les codes d’erreur des tâches asynchrones. 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
- BytePlus : générer des vidéos de portrait avec Seedance
- Génération vidéo native AIHubMix
- API vidéo compatible OpenAI
- Tâches asynchrones