Referência da API VideoRetalk - Alibaba Cloud Model Studio: Central de Documentação do Alibaba Cloud

Use a API VideoRetalk para gerar vídeos com movimentos labiais sincronizados, substituindo a fala original por uma faixa de áudio fornecida.

Importante

Este documento aplica-se exclusivamente à região China (Beijing). Para usar o modelo, use uma chave de API da região China (Beijing).

HTTP

O VideoRetalk suporta apenas chamadas HTTP e opera de forma assíncrona: envie uma tarefa e depois consulte os resultados (duas solicitações distintas). Essa abordagem reduz o tempo de espera e evita timeouts.

Enviar uma tarefa: Envie uma solicitação para criar uma tarefa de geração de vídeo. A API retorna um ID de tarefa.
Consultar status da tarefa e obter resultados: Use o ID da tarefa retornado para consultar o status e recuperar o vídeo gerado.

Pré-requisitos

Você já criou uma chave de API e definiu a chave de API como variável de ambiente.

Limitações de entrada

Requisitos de vídeo:
- Arquivo: MP4, AVI ou MOV. Máximo de 300 MB. Duração: 2 a 120 segundos.
- Propriedades: Taxa de quadros: 15-60 fps. Codificação: H.264 ou H.265 obrigatória. Dimensão lateral: 640 a 2.048 pixels.
- Conteúdo: Close-up de pessoa voltada para a frente. Evite ângulos extremos ou rostos muito pequenos. Se o vídeo não contiver rosto, consulte as Perguntas frequentes.
Requisitos de áudio:
- Arquivo: WAV, MP3 ou AAC. Máximo de 30 MB. Duração: 2 a 120 segundos. Se as durações do áudio e do vídeo diferirem, consulte as Perguntas frequentes.
- Conteúdo: Voz humana clara e alta. Remova ruídos ambientes e música de fundo.
Requisitos da imagem de referência do personagem:
- Arquivo: JPEG, JPG, PNG, BMP ou WebP. Máximo de 10 MB. Proporção: 2 ou menos; lado mais longo: 4.096 pixels ou menos.
- Conteúdo: Visualização frontal clara do rosto. A pessoa deve aparecer no vídeo. Você pode usar uma captura de tela do vídeo.
Requisitos de URL de arquivo:
- Os arquivos devem ser acessíveis via links HTTP (caminhos locais não são suportados). Use o espaço de armazenamento temporário da plataforma para enviar arquivos locais e criar links.

Enviar uma tarefa

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

Parâmetros da solicitação

Campo	Tipo	Localização	Obrigatório	Descrição	Exemplo
Content-Type	String	Header	Sim	application/json	application/json
Authorization	String	Header	Sim	Chave de API (formato: Bearer SUA_CHAVE)	Bearer d1**2a
X-DashScope-Async	String	Header	Sim	Defina como `enable` para criação assíncrona de tarefas.	enable
model	String	Body	Sim	Modelo a ser chamado.	videoretalk
input.video_url	String	Body	Sim	URL do arquivo de vídeo enviado. Consulte Limitações de entrada para requisitos de arquivo.	http://aaa/bbb.mp4
input.audio_url	String	Body	Sim	URL do arquivo de áudio enviado. Consulte Limitações de entrada para requisitos de arquivo.	http://aaa/bbb.wav
input.ref_image_url	String	Body	Não	URL da imagem de rosto de referência. Use este campo para especificar qual rosto sincronizar quando houver múltiplos rostos. Se omitido, o sistema usa o maior rosto no primeiro quadro. Consulte Limitações de entrada para requisitos de arquivo.	http://aaa/bbb.jpg
parameters.video_extension	Boolean	Body	Não	Define se o vídeo deve ser estendido quando o áudio for mais longo. Padrão: `false`. `true`: Estende o vídeo para corresponder ao comprimento do áudio, repetindo em um padrão de "reprodução reversa, reprodução avançada". `false`: Não estende o vídeo. O vídeo gerado mantém a duração original e o áudio é truncado.	false
parameters.query_face_threshold	Integer	Body	Não	Especifica o nível de confiança para correspondência facial quando uma imagem de referência é fornecida. Intervalo: 120-200 (menor = correspondência mais flexível, maior = correspondência mais rigorosa). Padrão: 170. Ignorado se input.ref_image_url estiver vazio.	170

Parâmetros da resposta

Campo	Tipo	Descrição	Exemplo
output.task_id	String	ID da tarefa enviada. Use este valor para consultar o status da tarefa e recuperar os resultados.	a8532587-fa8c-4ef8-82be-0c46b17950d1
output.task_status	String	Status da tarefa após o envio.	"PENDING"
request_id	String	ID da solicitação.	7574ee8f-38a3-4b1e-9280-11c33ab46e51

Exemplo de solicitação

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

Exemplo de resposta

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

Consultar status da tarefa e obter resultados

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

Parâmetros da solicitação

Campo	Tipo	Localização	Obrigatório	Descrição	Exemplo
Authorization	String	Header	Sim	Chave de API (formato: Bearer SUA_CHAVE)	Bearer d1**2a
task_id	String	Url Path	Sim	ID da tarefa a ser consultada (retornado pela API de envio de tarefa).	a8532587-fa8c-4ef8-82be-0c46b17950d1

Parâmetros da resposta

Campo	Tipo	Descrição	Exemplo
output.task_id	String	ID da tarefa consultada.	a8532587-fa8c-4ef8-82be-0c46b17950d1
output.task_status	String	Status da tarefa consultada.	Status das tarefas: PENDING PRE-PROCESSING RUNNING POST-PROCESSING SUCCEEDED FAILED UNKNOWN: A tarefa não existe ou seu status é desconhecido.
output.video_url	String	URL do vídeo gerado. Válida por 24 horas após a conclusão da tarefa.	https://xxx/1.mp4"
usage.video_duration	Float	Duração do vídeo gerado (segundos).	"video_duration": 10.23
usage.video_ratio	String	Tipo de proporção do vídeo gerado. Valor: standard (a saída corresponde ao original por padrão).	"video_ratio": "standard"
usage.size	String	Resolução do vídeo gerado (corresponde à entrada).	"size": "1080*1920"
usage.fps	Integer	Taxa de quadros do vídeo gerado (corresponde à entrada).	"fps": 25
request_id	String	ID da solicitação.	7574ee8f-38a3-4b1e-9280-11c33ab46e51

Exemplo de solicitação

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

Exemplo de resposta

{
    "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
    }
}

Exemplo de resposta de erro

{
    "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 erro

Consulte Códigos de erro para códigos de status gerais.

Códigos de erro específicos do modelo:

Código de retorno HTTP	Código de erro	Mensagem de erro	Descrição
400	InvalidParameter	Field required: xxx	Parâmetro de solicitação ausente ou incorreto.
400	InvalidURL.ConnectionRefused	Connection to ${url} refused, please provide avaiable URL	Download rejeitado. Forneça uma URL disponível.
400	InvalidURL.Timeout	Download ${url} timeout, please check network connection.	Tempo limite de download excedido (timeout: 60s).
400	InvalidFile.Size	Invalid file size. The video/audio/image file size must be less than **MB.	O arquivo deve ser menor que ** MB.
400	InvalidFile.Format	Invalid file format，the request file format is one of the following types: MP4, AVI, MOV, MP3, WAV, AAC, JPEG, JPG, PNG, BMP, and WEBP.	Formato de arquivo inválido. Suportados: Vídeo (MP4/AVI/MOV), Áudio (MP3/WAV/AAC), Imagem (JPG/JPEG/PNG/BMP/WebP).
400	InvalidFile.Resolution	Invalid video resolution. The height or width of video must be 640 ~ 2048.	A dimensão lateral do vídeo deve ter entre 640 e 2.048 pixels.
400	InvalidFile.FPS	Invalid video FPS. The video FPS must be 15 ~ 60.	A taxa de quadros do vídeo deve estar entre 15 e 60 fps.
400	InvalidFile.Duration	Invalid file duration. The video/audio file duration must be 2s ~ 120s.	A duração do vídeo/áudio deve estar entre 2 e 120 segundos.
400	InvalidFile.ImageSize	The size of image is beyond limit.	O tamanho da imagem excede o limite. A proporção deve ser 2 ou menos; o lado mais longo deve ter 4.096 pixels ou menos.
400	InvalidFile.Openerror	Invalid file, cannot open file as video/audio/image.	Não foi possível abrir o arquivo.
400	InvalidFile.Content	The input image has no human body or multi human bodies. Please upload other image with single person.	A imagem não contém pessoas ou contém várias pessoas.
400	InvalidFile.FaceNotMatch	There are no matched face in the video with the provided reference image.	O rosto de referência não corresponde a nenhum rosto no vídeo.

Perguntas frequentes

Como lidar com vídeo e áudio de entrada com durações diferentes?

Por padrão, o arquivo mais longo é truncado para corresponder ao mais curto. Para repetir o vídeo até igualar o comprimento do áudio, defina video_extension como true (reproduz em reverso e depois avança).
Como a API lida com segmentos silenciosos no áudio de entrada?

O modelo gera quadros com a boca fechada para segmentos de áudio silenciosos.
O que acontece quando um quadro de vídeo não contém rosto, mas o áudio correspondente tem fala?

O quadro original é preservado e o áudio continua. A sincronia labial aplica-se apenas a quadros com rostos detectáveis.
Como selecionar uma pessoa específica para sincronia labial em um vídeo com várias pessoas?

A API sincroniza apenas uma pessoa. Use input.ref_image_url para especificar o rosto alvo. Se omitido, o maior rosto no primeiro quadro será sincronizado.