Tutoriel sur l’API PixVerse de synchronisation labiale : téléchargement, génération, interrogation et révision

AI Overview

De quels éléments l’API de synchronisation labiale PixVerse a-t-elle besoin ?

Fournissez une vidéo de référence et une source vocale. La vidéo peut être un source_video_id généré par PixVerse ou un video_media_id téléchargé ; la voix peut provenir d’un fichier audio téléchargé ou d’un locuteur TTS combiné à un script.

Quel point de terminaison crée une tâche de synchronisation labiale ?

Envoyez une requête POST /openapi/v2/video/lip_sync/generate avec votre clé API, un nouvel identifiant de trace (trace ID) et une combinaison valide vidéo/audio. Une réponse réussie fournit un video_id, mais pas encore un fichier finalisé.

Comment savoir quand le résultat est prêt ?

Interrogez périodiquement (poll) le point de terminaison GET /openapi/v2/video/result/{id} en utilisant le video_id retourné. PixVerse documente le statut 5 comme « en cours de génération » et le statut 1 comme « réussi » ; utilisez alors uniquement l’URL vidéo fournie dans la réponse.

Puis-je utiliser du texte au lieu d’un fichier audio ?

Oui. Sélectionnez un locuteur TTS intégré ou personnalisé, puis envoyez lip_sync_tts_speaker_id accompagné de lip_sync_tts_content. Ne combinez pas cette méthode avec un audio_media_id non lié dans le même exemple.

Choisissez la vidéo et la voix avant d’appeler l’API

Ce tutoriel sur l’API de synchronisation labiale PixVerse concerne une tâche précise : appliquer une phrase donnée sur un visage animé existant, récupérer le résultat asynchrone, puis évaluer si le mouvement des lèvres est exploitable. Si vous devez d’abord créer la séquence de base, un plan rapproché du locuteur est plus facile à évaluer qu’un plan serré, un virage rapide de profil vers face frontale ou un visage masqué par les mains. Vous pouvez produire ce plan de base via un flux de travail image-vers-vidéo, une génération PixVerse ou des images dont vous détenez les droits d’utilisation.

Le guide officiel de la parole de PixVerse distingue deux façons de fournir l’image. Une séquence créée par son API possède déjà un video_id, transmis comme source_video_id. Une séquence externe est téléchargée via le point de terminaison média et renvoie un media_id, transmis comme video_media_id. Ces identifiants ne sont pas interchangeables. Notez soigneusement l’origine de chaque identifiant dans votre propre journal de tâches afin qu’une nouvelle tentative n’envoie pas, par erreur, un media_id téléchargé dans le champ dédié aux vidéos générées.

Pour la voix, choisissez soit un enregistrement finalisé avec audio_media_id, soit une synthèse vocale (TTS) avec lip_sync_tts_speaker_id et lip_sync_tts_content. Les quatre combinaisons forment une matrice 2 × 2 : vidéo générée ou téléchargée, croisée avec voix enregistrée ou TTS. Un échantillon vocal utilisé pour créer un locuteur personnalisé remplit une fonction différente de l’audio final téléchargé pour une tâche de synchronisation labiale, bien que les deux passent tous deux par une étape de téléchargement média.

Les illustrations fixes représentent une présentatrice adulte fictive, à titre éditorial uniquement — elles ne constituent ni une sortie PixVerse ni une preuve de précision labiale. Elles illustrent pourquoi un visage net et une bouche non occultée sont essentielles lors du choix de la séquence source.

Image éditoriale originale, non issue de PixVerse. Un visage frontal et stable constitue une entrée pratique initiale pour vérifier l’alignement vocal.

Commencez par un premier test modeste : un seul locuteur visible, une phrase courte, une prononciation claire et peu de mouvement caméra. Le guide narratif « Speech » et la documentation de téléchargement média indiquent actuellement des limites fonctionnelles différentes pour les téléchargements de synchronisation labiale ; ne considérez donc pas une taille ou une durée copiée comme une règle universelle définitive. Consultez la documentation spécifique au point de terminaison concerné et maintenez l’échantillon initial confortablement court. Les crédits API PixVerse sont distincts de l’abonnement à son application web ; vérifiez votre solde avant de lancer un lot.

Téléchargez des médias externes sans mélanger les identifiants

Si vous disposez déjà d’un video_id généré par PixVerse, passez le téléchargement vidéo. Sinon, téléchargez une vidéo externe compatible via POST /openapi/v2/media/upload, puis stockez le Resp.media_id renvoyé sous forme de video_media_id. Téléchargez également la piste vocale enregistrée via le même point de terminaison média et stockez son Resp.media_id renvoyé sous forme de audio_media_id. PixVerse documente les formats vidéo courants (MP4, MOV, WebM) et audio (MP3, WAV, M4A, AAC) ; vérifiez les formats et limites fonctionnelles en vigueur avant tout transfert.

Nommez vos ressources selon leur usage : speaker-base-v1.mp4, line-01-clean-v1.wav, et un enregistrement de tâche contenant leurs identifiants média. Assurez la visibilité du visage dès le début de la parole, supprimez les silences inutiles et vérifiez si la séquence source offre suffisamment de mouvement labial pour la phrase à synchroniser.

Image éditoriale originale. Le cadrage trois-quarts offre davantage d’indices de profondeur au relecteur, mais rend plus difficile de masquer les dents, la mâchoire et les contours des lèvres en cas de décalage temporel.

Pour TTS, omettez le téléchargement de l’audio finalisé. Interrogez la liste des voix, sélectionnez un identifiant de locuteur intégré ou créez une voix personnalisée à partir d’un échantillon préalablement téléchargé, avec autorisation. Ne supposez pas que l’option auto convient à toutes les langues ; conservez l’identifiant réel du locuteur sélectionné. Pour plusieurs locuteurs, créez des séquences distinctes puis assemblez-les ultérieurement.

Le guide vidéo avec audio natif explique pourquoi la voix, l’ambiance et le mouvement doivent faire l’objet d’un examen conjoint. Obtenez le consentement pour utiliser le visage ou la voix d’une personne réelle, et signalez clairement l’usage de synthèse vocale lorsque cela s’applique.

Envoyez une seule requête de génération valide

Le point de terminaison officiel de génération est https://app-api.pixverse.ai/openapi/v2/video/lip_sync/generate. PixVerse exige un API-KEY et un Ai-trace-id frais pour chaque nouvelle requête API. Stockez la clé côté serveur, et non dans du JavaScript navigateur ou un exemple d’article. Réutiliser un identifiant de trace peut renvoyer un résultat antérieur au lieu de lancer la nouvelle tâche souhaitée ; enregistrez donc chaque identifiant avec ses identifiants d’entrée, la version du script et la réponse reçue.Cette demande factice utilise une vidéo source générée par PixVerse ainsi qu’un fichier audio final téléchargé. Remplacez les exemples de numéros par les identifiants renvoyés par votre propre compte ; cette requête n’a pas été exécutée pour cet article.

curl -X POST 'https://app-api.pixverse.ai/openapi/v2/video/lip_sync/generate' \
  -H "API-KEY: $PIXVERSE_API_KEY" \
  -H "Ai-trace-id: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"source_video_id":123456,"audio_media_id":234567}'

Pour une vidéo externe, remplacez source_video_id par video_media_id. Pour la synthèse vocale (text-to-speech), remplacez audio_media_id par lip_sync_tts_speaker_id et lip_sync_tts_content. Ce sont des chemins alternatifs, et non quatre champs à remplir indifféremment. L’enveloppe de réponse utilise ErrCode, ErrMsg et Resp ; lors de la création réussie d’une tâche, Resp.video_id est l’identifiant à conserver. Il ne prouve pas qu’un fichier jouable ait terminé sa génération.

Validez un seul type d’identifiant vidéo et un seul mode de parole avant l’appel ; rejetez un script TTS vide. Journalisez les crédits renvoyés sans en coder le prix en dur. Associez chaque ligne et chaque réponse de tâche à un identifiant de plan stable, comme une passation entre image initiale et image finale pour assurer la continuité visuelle.

Interroger la tâche et conserver une trace du résultat

Après la création de la tâche, utilisez GET /openapi/v2/video/result/{id} avec le video_id renvoyé. PixVerse documente le statut 5 comme « en cours de génération » et le statut 1 comme « réussi ». Une réponse HTTP réussie ou ErrCode: 0 depuis l’appel de création signifie que la tâche a été acceptée, mais pas que le résultat animé a passé votre examen. Lorsque le statut vaut 1, récupérez l’URL de sortie depuis le résultat et enregistrez-en une copie conformément à votre politique habituelle sur les ressources, avant que l’URL n’expire ou que les règles d’accès ne changent.

Le statut 7 est documenté comme un échec de modération de contenu, et le statut 8 comme un échec de génération. Traitez chacun comme une tâche arrêtée, plutôt que d’interroger indéfiniment. Un outil de sondage en production doit implémenter une attente bornée, un mécanisme de réessai progressif (backoff) et un enregistrement fiable du dernier statut observé. Si votre processus redémarre, reprenez à partir du video_id stocké au lieu de recréer la même tâche payante. Utilisez un nouvel identifiant de trace pour une nouvelle demande intentionnelle, mais n’engendrez pas de nouvelles tentatives lorsque la tâche est simplement en cours de traitement lent.

Image éditoriale originale. Un plan plus large permet de vérifier si le synchronisme facial reste lisible pendant que l’interprète bouge, mais aucune image fixe ne peut établir une synchronisation labiale réelle.

Conservez un enregistrement lisible comprenant l’identifiant du plan, les identifiants vidéo et vocal, l’identifiant de trace, le video_id généré, l’URL finale et le verdict d’examen. Ne stockez jamais de credentials dans ce journal d’examens. Le guide de flux de travail de l’agent PixVerse couvre le processus complet allant du brief à la réalisation du plan.

Examiner les mouvements buccaux, l’audio et les limites des coupes

Regardez le fichier final en mouvement à vitesse normale avec le son, puis ralentissez autour de syllabes sélectionnées. Choisissez une phrase contenant des sons bilabiaux visibles tels que p, b et m, ainsi qu’une voyelle ouverte plus longue. Recherchez une fermeture buccale avant ces consonnes, une ouverture plausible sur la voyelle, et une parole qui commence et se termine sans décalage gênant. Il s’agit d’une méthode d’inspection éditoriale, non d’un repère officiel ni d’une affirmation d’un taux de réussite mesuré de PixVerse.

Comparez la sortie avec la source : la direction du regard, l’identité, la mâchoire, l’éclairage et les dents ne doivent pas changer brusquement. Vérifiez à la fois le gros plan et la séquence complète. Ces images fixes ne constituent pas un résultat « avant/après » de PixVerse.

Image éditoriale originale. Les angles de profil révèlent des erreurs de contour de mâchoire et de lèvres que la miniature frontale peut masquer.

La séquence jouable ci-dessous est un exemple réel existant de dialogue Seedance en mouvement. Elle est indépendante de l’API PixVerse et du présentateur illustré ; elle est incluse uniquement pour rendre concrète l’inspection simultanée de la voix et des mouvements buccaux en temps réel. Elle ne démontre ni un résultat de synchronisation labiale généré par PixVerse, ni une comparaison de performances.

Exemple indépendant de dialogue Seedance en mouvement pour l’inspection complète des lèvres et de la voix

Regardez toute la phrase et évaluez les mouvements buccaux, la voix, les mouvements de tête et les transitions entre plans ; il ne s’agit pas d’une sortie de PixVerse.

Utilisez une fiche simple d’acceptation : approuvez si la phrase est intelligible, commence au tempo prévu, conserve l’identité de l’orateur et résiste à un visionnage à vitesse normale ; corrigez si seul le point de coupe ou le rognage audio est erroné ; rejetez si la forme buccale, le visage ou le synchronisme échouent globalement. L’approbation doit reposer sur le fichier animé, et non sur l’image fixe. Un exemple de flux de travail de synchronisation labiale peut aider à comparer les habitudes générales d’examen, mais ses paramètres propres au fournisseur ne sont pas interchangeables avec les champs de l’API PixVerse.

Diagnostiquer le bon niveau et organiser la livraison

Si l’API rejette une requête, examinez la réponse et la paire de paramètres concernés. Vérifiez la confusion entre les types d’identifiants vidéo, l’utilisation d’un identifiant d’échantillon vocal comme audio final, l’absence de champs TTS, ou la réutilisation d’un identifiant de trace. Vérifiez l’autorisation, les crédits, le type de support, les limites et la concurrence. Ne collez jamais une clé API dans une capture d’écran destinée au support.Si la tâche réussit mais que la sortie semble incorrecte, modifier le point de terminaison ne corrigera probablement pas une géométrie source médiocre. Essayez un extrait plus stable, une voix plus claire, moins d’occultation, une énonciation plus courte et un visage restant dans le cadre. Si le décalage temporel ne concerne que le premier mot, vérifiez le préambule audio et l’image de début vidéo ; s’il ne concerne qu’un raccord, ajustez la limite de montage et le ton ambiant. Conservez la meilleure prise approuvée tout en relançant uniquement la ligne faible.

Seedance Agent intervient une fois le résultat de l’API disponible : conservez ensemble la séquence de base approuvée, la version vocale, la sortie générée, les notes d’acceptation et la décision de montage ; planifiez ou remplacez une seule prise sans reconstruire l’intégralité du contenu. Il peut coordonner l’organisation des références et les relectures, mais ne lance pas d’appel non testé à l’API PixVerse ni ne certifie un résultat PixVerse. Préservez une traçabilité claire lors de la combinaison de sorties provenant de différents fournisseurs.

Conclusion

Un flux de travail fiable pour l’API de synchronisation labiale PixVerse consiste à choisir un seul type d’identifiant vidéo et un seul mode de parole, à téléverser uniquement les supports nécessaires, à envoyer une seule requête bien formée avec un nouvel identifiant de trace, à attendre la fin du video_id renvoyé, puis à évaluer le résultat animé effectif. Consultez régulièrement la documentation officielle de PixVerse pour connaître les limites et les modalités de facturation, et distinguez clairement l’acceptation éditoriale de la création de la tâche. Lorsque plusieurs lignes approuvées doivent être intégrées dans une livraison cohérente, organisez les références, les relectures et le montage final dans Seedance Agent.