Referencia de la API de VideoRetalk - Alibaba Cloud Model Studio - Centro de documentación de Alibaba Cloud

Utilice la API de VideoRetalk para generar videos con movimientos labiales sincronizados reemplazando el habla de una persona con una pista de audio proporcionada.

ImportanteEste documento se aplica únicamente a la región China (Beijing). Para utilizar el modelo, use una clave de API de la región China (Beijing).

HTTP

VideoRetalk solo admite llamadas HTTP y utiliza un proceso asíncrono: envíe una tarea y luego consulte los resultados (dos solicitudes separadas). Esto reduce los tiempos de espera y evita que se agote el tiempo de espera.

Enviar una tarea: Envíe una solicitud para crear una tarea de generación de video. La API devuelve un ID de tarea.
Consultar el estado de la tarea y recuperar resultados: Utilice el ID de tarea devuelto para consultar el estado de la tarea y recuperar el video generado.

Requisitos previos

Usted ha creado una clave de API y ha configurado la clave de API como variable de entorno.

Limitaciones de entrada

Requisitos de video:
- Archivo: MP4, AVI o MOV. Máximo 300 MB. Duración: 2-120 segundos.
- Propiedades: Tasa de fotogramas: 15-60 fps. Codificación: Se requiere H.264 o H.265. Longitud del lado: 640-2,048 píxeles.
- Contenido: Persona en primer plano y de frente. Evite ángulos extremos o rostros muy pequeños. Si el video no contiene ningún rostro, consulte las Preguntas frecuentes.
Requisitos de audio:
- Archivo: WAV, MP3 o AAC. Máximo 30 MB. Duración: 2-120 segundos. Si las duraciones de audio y video difieren, consulte las Preguntas frecuentes.
- Contenido: Voz humana clara y fuerte. Elimine el ruido ambiental y la música de fondo.
Requisitos de la imagen de referencia del personaje:
- Archivo: JPEG, JPG, PNG, BMP o WebP. Máximo 10 MB. Relación de aspecto: 2 o menos; lado más largo: 4,096 píxeles o menos.
- Contenido: Vista frontal clara del rostro. La persona debe aparecer en el video. Puede utilizar una captura de pantalla del video.
Requisitos de URL de archivo:
- Los archivos deben ser accesibles mediante enlaces HTTP (no se admiten rutas locales). Utilice el espacio de almacenamiento temporal de la plataforma para subir archivos locales y crear enlaces.

Enviar una tarea

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis/

Parámetros de solicitud

Campo	Tipo	Ubicación	Obligatorio	Descripción	Ejemplo
Content-Type	String	Header	Sí	application/json	application/json
Authorization	String	Header	Sí	Clave de API (formato: Bearer YOUR_KEY)	Bearer d1**2a
X-DashScope-Async	String	Header	Sí	Establezca en `enable` para la creación asíncrona de tareas.	enable
model	String	Cuerpo	Sí	Modelo a invocar.	videoretalk
input.video_url	String	Cuerpo	Sí	URL del archivo de video que subió. Consulte Limitaciones de entrada para conocer los requisitos de los archivos.	http://aaa/bbb.mp4
input.audio_url	String	Cuerpo	Sí	URL del archivo de audio que subió. Consulte Limitaciones de entrada para conocer los requisitos de los archivos.	http://aaa/bbb.wav
input.ref_image_url	String	Cuerpo	No	URL de la imagen de rostro de referencia. Utilícela para especificar qué rostro sincronizar cuando haya múltiples rostros presentes. Si se omite, el sistema utiliza el rostro más grande del primer fotograma. Consulte Limitaciones de entrada para conocer los requisitos de los archivos.	http://aaa/bbb.jpg
parameters.video_extension	Boolean	Cuerpo	No	Especifica si se debe extender el video cuando el audio es más largo. Valor predeterminado: `false`. `true`: Extiende el video para igualar la duración del audio mediante un bucle en patrón de "reproducción inversa, reproducción hacia adelante". `false`: No extiende el video. El video generado coincide con la duración original y el audio se trunca.	false
parameters.query_face_threshold	Integer	Cuerpo	No	Especifica el nivel de confianza para la coincidencia de rostros cuando se proporciona una imagen de referencia. Rango: 120-200 (menor = coincidencia más flexible, mayor = coincidencia más estricta). Valor predeterminado: 170. Se ignora si input.ref_image_url está vacío.	170

Parámetros de respuesta

Campo	Tipo	Descripción	Ejemplo
output.task_id	String	ID de la tarea enviada. Utilícelo para consultar el estado de la tarea y recuperar los resultados.	a8532587-fa8c-4ef8-82be-0c46b17950d1
output.task_status	String	Estado de la tarea después del envío.	"PENDING"
request_id	String	ID de solicitud.	7574ee8f-38a3-4b1e-9280-11c33ab46e51

Solicitud de ejemplo

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis/' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "videoretalk",
    "input": {
        "video_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250717/pvegot/input_video_01.mp4",
        "audio_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250717/aumwir/stella2-%E6%9C%89%E5%A3%B0%E4%B9%A67.wav",
        "ref_image_url": ""
     },
    "parameters": {
        "video_extension": false
    }
  }'

Respuesta de ejemplo

{
    "output": {
	"task_id": "a8532587-fa8c-4ef8-82be-0c46b17950d1",
        "task_status": "PENDING"
    },
    "request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51"
}

Consultar el estado de la tarea y recuperar resultados

GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

Parámetros de solicitud

Campo	Tipo	Ubicación	Obligatorio	Descripción	Ejemplo
Authorization	String	Header	Sí	Clave de API (formato: Bearer YOUR_KEY)	Bearer d1**2a
task_id	String	Ruta de URL	Sí	ID de tarea a consultar (devuelto por la API de envío de tareas).	a8532587-fa8c-4ef8-82be-0c46b17950d1

Parámetros de respuesta

Campo	Tipo	Descripción	Ejemplo
output.task_id	String	ID de tarea consultada.	a8532587-fa8c-4ef8-82be-0c46b17950d1
output.task_status	String	Estado de la tarea consultada.	Estados de la tarea: PENDING PRE-PROCESSING RUNNING POST-PROCESSING SUCCEEDED FAILED UNKNOWN: La tarea no existe o se desconoce su estado.
output.video_url	String	URL del video generado. Válida durante 24 horas después de la finalización de la tarea.	https://xxx/1.mp4"
usage.video_duration	Float	Duración del video generado (segundos).	"video_duration": 10.23
usage.video_ratio	String	Tipo de relación de aspecto del video generado. Valor: standard (la salida coincide con el original de forma predeterminada).	"video_ratio": "standard"
usage.size	String	Resolución del video generado (coincide con la entrada).	"size": "1080*1920"
usage.fps	Integer	Tasa de fotogramas del video generado (coincide con la entrada).	"fps": 25
request_id	String	ID de solicitud.	7574ee8f-38a3-4b1e-9280-11c33ab46e51

Solicitud de ejemplo

curl -X GET 'https://dashscope.aliyuncs.com/api/v1/tasks/<YOUR_TASK_ID>' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Respuesta de ejemplo

{
    "request_id": "87b9dce5-7f36-4305-a347-xxxxxx",
    "output": {
        "task_id": "3afd65eb-9604-48ea-8a91-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-09-11 20:15:29.887",
        "scheduled_time": "2025-09-11 20:15:36.741",
        "end_time": "2025-09-11 20:16:40.577",
        "video_url": "http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?Expires=xxx"
    },
    "usage": {
        "video_duration": 7.2,
        "size": "1080*1920",
        "video_ratio": "standard",
        "fps": 25
    }
}

Respuesta de error de ejemplo

{
    "request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51",
    "output": {
        "task_id": "a8532587-fa8c-4ef8-82be-0c46b17950d1",
        "task_status": "FAILED",
        "code": "xxx",
        "message": "xxxxxx"
    }
}

Códigos de error

Consulte Códigos de error para ver los códigos de estado generales.

Códigos de error específicos del modelo:

Código de retorno HTTP	Código de error	Mensaje de error	Descripción
400	InvalidParameter	Campo obligatorio: xxx	Parámetro de solicitud faltante o incorrecto.
400	InvalidURL.ConnectionRefused	Conexión a ${url} rechazada, proporcione una URL disponible	Descarga rechazada. Proporcione una URL disponible.
400	InvalidURL.Timeout	Tiempo de espera agotado al descargar ${url}, verifique la conexión de red.	Tiempo de descarga agotado (tiempo de espera: 60s).
400	InvalidFile.Size	Tamaño de archivo no válido. El tamaño del archivo de video/audio/imagen debe ser inferior a **MB.	El archivo debe ser menor a ** MB.
400	InvalidFile.Format	Formato de archivo no válido, el formato de archivo solicitado debe ser uno de los siguientes tipos: MP4, AVI, MOV, MP3, WAV, AAC, JPEG, JPG, PNG, BMP y WEBP.	Formato de archivo no válido. Compatibles: Video (MP4/AVI/MOV), Audio (MP3/WAV/AAC), Imagen (JPG/JPEG/PNG/BMP/WebP).
400	InvalidFile.Resolution	Resolución de video no válida. La altura o anchura del video debe ser de 640 a 2048.	La longitud lateral del video debe ser de 640-2048 píxeles.
400	InvalidFile.FPS	FPS de video no válido. Los FPS del video deben estar entre 15 y 60.	La tasa de fotogramas del video debe ser de 15-60 fps.
400	InvalidFile.Duration	Duración de archivo no válida. La duración del archivo de video/audio debe ser de 2s a 120s.	La duración del video/audio debe ser de 2-120 segundos.
400	InvalidFile.ImageSize	El tamaño de la imagen supera el límite.	El tamaño de la imagen excede el límite. La relación de aspecto debe ser 2 o menos; el lado más largo debe ser de 4,096 píxeles o menos.
400	InvalidFile.Openerror	Archivo no válido, no se puede abrir el archivo como video/audio/imagen.	No se puede abrir el archivo.
400	InvalidFile.Content	La imagen de entrada no contiene ningún cuerpo humano o contiene varios. Suba otra imagen con una sola persona.	La imagen no contiene ninguna persona o contiene varias personas.
400	InvalidFile.FaceNotMatch	No hay ninguna cara en el video que coincida con la imagen de referencia proporcionada.	El rostro de referencia no coincide con ningún rostro del video.

FAQ

¿Cómo manejo videos y audios de entrada con diferentes duraciones?
De forma predeterminada, el archivo más largo se trunca para coincidir con el más corto. Para repetir el video en bucle y ajustarlo a la duración del audio, configure video_extension en true (se reproduce en reversa y luego hacia adelante).
¿Cómo maneja la API los segmentos silenciosos en el audio de entrada?
El modelo genera fotogramas con la boca cerrada para los segmentos de audio silenciosos.
¿Qué sucede cuando un fotograma de video no contiene ningún rostro, pero el audio correspondiente tiene voz?
Se conserva el fotograma original; el audio continúa. La sincronización labial solo se aplica a fotogramas con rostros detectables.
¿Cómo selecciono a una persona específica para la sincronización labial en un video con varias personas?
La API sincroniza solo a una persona. Utilice input.ref_image_url para especificar el rostro objetivo. Si se omite, se sincroniza el rostro más grande del primer fotograma.