Use a API VideoRetalk para gerar vídeos com movimentos labiais sincronizados, substituindo a fala original por uma faixa de áudio fornecida.
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
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 |
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 |
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
Exemplo de resposta
Consultar status da tarefa e obter resultados
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:
|
output.video_url | String | URL do vídeo gerado. Válida por 24 horas após a conclusão da tarefa. | |
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
Exemplo de resposta
Exemplo de resposta de erro
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.