Tutorial de la API de sincronización labial de PixVerse: carga, generación, sondeo y revisión

AI Overview

¿Qué requiere la API de sincronización labial PixVerse?

Proporcione un video de referencia y una fuente de voz. El video puede ser un source_video_id generado por PixVerse o un video_media_id cargado; la voz puede ser un archivo de audio cargado o un altavoz TTS más un guion.

¿Qué punto final crea una tarea de sincronización labial?

Envíe una solicitud POST /openapi/v2/video/lip_sync/generate con su clave de API, un nuevo identificador de seguimiento (trace ID) y una combinación válida de video y audio. Una respuesta exitosa devuelve un video_id, no un archivo finalizado.

¿Cómo sé cuándo está listo el resultado?

Realice sondeos mediante GET /openapi/v2/video/result/{id} usando el video_id devuelto. PixVerse documenta el estado 5 como «en generación» y el estado 1 como «correcto»; solo entonces utilice la URL del video devuelta.

¿Puedo usar texto en lugar de un archivo de audio?

Sí. Seleccione un altavoz TTS integrado o personalizado y envíe lip_sync_tts_speaker_id junto con lip_sync_tts_content. No combine esta vía con un audio_media_id no relacionado en el mismo ejemplo.

Elija el video y la voz antes de llamar a la API

Este tutorial de la API de sincronización labial PixVerse trata una tarea específica: aplicar una línea de voz elegida sobre un rostro en movimiento existente, recuperar el resultado asíncrono y decidir si el movimiento bucal es utilizable. Si necesita crear primero el clip base, una toma corta del orador es más fácil de evaluar que un corte rápido, un giro de perfil a frente o un rostro oculto por las manos. Puede generar ese clip base mediante un flujo de trabajo de imagen a video, una generación de PixVerse o material para el que tenga derechos de uso.

La guía oficial de voz de PixVerse identifica dos formas de proporcionar la imagen. Un clip creado mediante su API ya tiene un video_id, que se pasa como source_video_id. Un clip externo se carga mediante el punto final de medios y genera un media_id, que se pasa como video_media_id. Estos identificadores no son intercambiables. Registre el origen junto a cada identificador en su propio registro de tareas, para evitar enviar, en un reintento posterior, un número de medio cargado en el campo destinado a videos generados.

Para la voz, elija entre una grabación finalizada con audio_media_id o una ruta de conversión de texto a voz con lip_sync_tts_speaker_id y lip_sync_tts_content. Las cuatro combinaciones forman una matriz de dos por dos: video generado o cargado, cruzado con audio grabado o TTS. Una muestra de voz usada para crear un altavoz personalizado desempeña un papel distinto del audio final cargado para una tarea de sincronización labial, aunque ambos pasen por un paso de carga de medios.

Las imágenes fijas son ilustraciones editoriales de una presentadora adulta ficticia, no resultados de PixVerse ni prueba de precisión labial. Ilustran por qué es importante elegir un clip fuente con el rostro claro y la boca sin obstrucciones.

Imagen fija editorial original, no salida de PixVerse. Un rostro frontal y estable es una entrada práctica inicial para verificar la alineación de la voz.

Mantenga la primera prueba modesta: un único orador visible, una oración corta, voz nítida y poca movilidad de cámara. La guía narrativa de voz y la referencia de carga de medios indican actualmente límites de características distintos para las cargas de sincronización labial, por lo que no trate un tamaño o duración copiada como una regla universal permanente. Consulte la documentación específica del punto final vigente y mantenga la muestra inicial cómodamente corta. Los créditos de la API de PixVerse son independientes de su membresía en la aplicación web; confirme su saldo antes de iniciar un lote.

Cargue medios externos sin mezclar los identificadores

Si ya dispone de un video_id generado por PixVerse, omita la carga del video. De lo contrario, cargue un video externo compatible mediante POST /openapi/v2/media/upload, y guarde el Resp.media_id devuelto como video_media_id. Cargue una pista de voz grabada mediante el mismo punto final de medios y guarde su Resp.media_id devuelto como audio_media_id. PixVerse documenta tipos comunes de video como MP4, MOV y WebM, y de audio como MP3, WAV, M4A y AAC; verifique los formatos y límites de funciones vigentes antes de la transferencia.

Asigne nombres a los artefactos según su propósito: speaker-base-v1.mp4, line-01-clean-v1.wav y un registro de tarea con sus identificadores de medios. Asegúrese de que el rostro sea visible al inicio de la voz, recorte silencios innecesarios y compruebe si el clip fuente ofrece suficiente movimiento bucal para la nueva línea.

Imagen fija editorial original. El encuadre de tres cuartos brinda al revisor más pistas de profundidad, pero dificulta ocultar dientes, mandíbula y bordes labiales si hay desfase temporal.

Para TTS, omita la carga del audio finalizado. Consulte la lista de voces, seleccione un identificador de altavoz integrado o cree una voz personalizada a partir de una muestra cargada previamente con permiso. No asuma que auto funciona para todos los idiomas; registre el identificador real del altavoz seleccionado. Para múltiples oradores, cree clips separados y ensámbelos después.

La guía de video con audio nativo explica por qué la voz, el ambiente y el movimiento requieren una revisión conjunta. Obtenga consentimiento para usar el rostro o la voz de una persona real y divulgue el uso de voz sintética cuando corresponda.

Envíe una solicitud de generación válida

La ruta oficial de generación es https://app-api.pixverse.ai/openapi/v2/video/lip_sync/generate. PixVerse espera un API-KEY y un Ai-trace-id nuevo para cada solicitud de API. Almacene la clave en el servidor, no en JavaScript del navegador ni en ejemplos de artículos. Reutilizar un identificador de seguimiento puede devolver un resultado anterior en lugar de iniciar la nueva tarea deseada, por lo que debe registrar cada identificador junto con sus identificadores de entrada, versión del guion y respuesta.Esta solicitud de marcador de posición utiliza un video fuente generado por PixVerse más un audio final cargado. Reemplace los números de ejemplo con los identificadores devueltos por su propia cuenta; esta solicitud no se ha ejecutado para este artículo.

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}'

Para un video externo, reemplace source_video_id por video_media_id. Para la síntesis de voz a texto, reemplace audio_media_id por lip_sync_tts_speaker_id y lip_sync_tts_content. Estas son vías alternativas, no cuatro campos que deban completarse indiscriminadamente. El contenedor de la respuesta usa ErrCode, ErrMsg y Resp; al crearse correctamente una tarea, Resp.video_id es el identificador que debe guardarse. Esto no constituye una prueba de que ya se haya generado un archivo reproducible.

Valide un tipo de identificador de video y un modo de habla antes de la llamada; rechace un guion TTS vacío. Registre los créditos devueltos sin codificar de forma rígida un precio. Vincule cada línea y cada respuesta de tarea a un identificador estable de plano, como una entrega entre primer y último fotograma para garantizar la continuidad visual.

Consulte el trabajo y mantenga trazabilidad del resultado

Tras la creación de la tarea, use GET /openapi/v2/video/result/{id} con el video_id devuelto. PixVerse documenta el estado 5 como «en generación» y el estado 1 como «correcto». Una respuesta HTTP correcta o ErrCode: 0 desde la llamada de creación indica que la tarea fue aceptada, no que el resultado en movimiento haya superado su revisión. Cuando el estado sea 1, recupere la URL de salida del resultado y guarde una copia bajo su política habitual de activos antes de que expire dicha URL o cambien sus reglas de acceso.

El estado 7 está documentado como fallo por moderación de contenido y el estado 8 como fallo de generación. Trate cada uno como una tarea detenida, en lugar de seguir consultando indefinidamente. Un consultor de producción debe implementar un tiempo de espera acotado, retroceso exponencial y un registro persistente del último estado observado. Si su proceso se reinicia, reanude desde el video_id almacenado, en vez de crear nuevamente la misma tarea de pago. Use un nuevo identificador de seguimiento para una solicitud deliberadamente nueva, pero no genere reintetos automáticos cuando una tarea lenta simplemente esté procesándose.

Fotograma editorial original. Un plano más amplio permite comprobar si el sincronismo facial sigue siendo legible mientras el intérprete se mueve, aunque ningún fotograma fijo puede confirmar realmente la sincronización labial.

Mantenga un registro legible del identificador del plano, los identificadores de video y de habla, el identificador de seguimiento, el video_id generado, la URL final y el veredicto de revisión. Nunca almacene credenciales en ese registro de revisión. La guía de flujo de trabajo del agente PixVerse abarca el proceso completo desde la consigna hasta el plano.

Revise el movimiento bucal, el audio y los límites de corte

Observe el archivo final en movimiento a velocidad normal con sonido, y luego a velocidad reducida alrededor de sílabas seleccionadas. Elija una oración que contenga sonidos bilabiales visibles, como p, b y m, junto con una vocal abierta más larga. Busque un cierre bucal previo a esos fonemas consonánticos, una apertura plausible durante la vocal y una emisión verbal que comience y termine sin retrasos distractores. Este es un método de inspección editorial, no un indicador de referencia reportado ni una afirmación sobre una tasa de éxito medida de PixVerse.

Compare la salida con la fuente: la mirada, la identidad, la mandíbula, la iluminación y los dientes no deben cambiar bruscamente. Verifique tanto el primer plano como el clip completo. Estos fotogramas no representan un resultado comparativo «antes/después» de PixVerse.

Fotograma editorial original. Los ángulos de perfil revelan errores en el contorno de la mandíbula y los labios que una miniatura frontal podría ocultar.

El clip reproducible a continuación es un ejemplo real existente de diálogo Seedance en movimiento. Es independiente de la API PixVerse y del presentador ilustrado; se incluye únicamente para hacer tangible la inspección simultánea de voz y movimiento bucal en tiempo real. No demuestra un resultado de sincronización labial generado por PixVerse ni un rendimiento comparativo.

Muestra independiente de diálogo Seedance para revisión completa de labios y voz en movimiento

Reproduzca toda la frase y evalúe los labios, la voz, el movimiento de la cabeza y la coherencia del corte; esto no es una salida de PixVerse.

Use una tarjeta sencilla de aceptación: apruebe si la frase es inteligible, comienza en el compás previsto, mantiene la identidad del hablante y resiste una revisión a velocidad normal; corrija si solo falla el límite de edición o el recorte de audio; rechace si fallan sistemáticamente la forma bucal, el rostro o la sincronización temporal. La aprobación debe basarse en el archivo en movimiento, no en la imagen fija. Un ejemplo separado de flujo de trabajo de sincronización labial puede ayudar a comparar hábitos generales de revisión, pero sus controles de proveedor no son intercambiables con los campos de la API PixVerse.

Solucione problemas en la capa adecuada y organice la entrega

Si la API rechaza una solicitud, examine la respuesta y el par de parámetros. Verifique si se han intercambiado los tipos de identificadores de video, si se ha usado un identificador de muestra de voz como audio final, si faltan campos TTS, o si se ha reutilizado un identificador de seguimiento. Confirme la autorización, los créditos disponibles, el tipo de medio, los límites y la concurrencia. Nunca pegue una clave API en una captura de pantalla destinada al soporte técnico.Si el trabajo se completa correctamente pero la salida parece incorrecta, cambiar el punto de conexión probablemente no solucionará problemas de geometría deficiente en la fuente. Pruebe con un clip más estable, una voz más clara, menos oclusión, una emisión más breve y un rostro que permanezca dentro del encuadre. Si el sincronizado falla únicamente en la primera palabra, revise el audio previo (lead-in) y el fotograma inicial del video; si falla únicamente en un corte, ajuste el límite de edición y el tono ambiental (room tone). Mantenga la mejor toma aprobada mientras vuelve a ejecutar únicamente la línea débil.

Seedance Agent se aplica tras la existencia del resultado de la API: conserve juntos el clip base aprobado, la versión de voz, la salida generada, las notas de aceptación y la decisión de ensamblaje; planifique o reemplace una sola toma sin reconstruir toda la pieza. Puede coordinar la organización y revisión de referencias, pero no realiza una llamada no probada a la API PixVerse ni certifica un resultado PixVerse. Mantenga una procedencia clara al combinar salidas de distintos proveedores.

Conclusión

Un flujo de trabajo fiable de la API de sincronización labial PixVerse elige un único tipo de identificador de video y un único modo de habla, carga únicamente los medios necesarios, envía una única solicitud bien formada con un nuevo identificador de traza (trace ID), espera a que finalice el video_id devuelto y evalúa el resultado real en movimiento. Mantenga la documentación actual de PixVerse como referencia autorizada para límites y facturación, y mantenga la aceptación editorial separada de la creación de tareas. Cuando varias líneas aprobadas deban convertirse en un único entregable coherente, organice las referencias, revisiones y ensamblaje final en Seedance Agent.