Tutorial da API de Sincronização Labial PixVerse: Upload, Geração, Consulta e Revisão

AI Overview

O que a API de sincronização labial PixVerse exige?

Forneça um vídeo de referência e uma fonte de fala. O vídeo pode ser um source_video_id gerado pelo PixVerse ou um video_media_id enviado; a fala pode ser um áudio enviado ou um falante TTS combinado com um roteiro.

Qual endpoint cria uma tarefa de sincronização labial?

Envie POST /openapi/v2/video/lip_sync/generate com sua chave de API, um novo ID de rastreamento (trace ID) e uma combinação válida de vídeo/áudio. Uma resposta bem-sucedida retorna um video_id, não um arquivo finalizado.

Como saber quando o resultado está pronto?

Consulte periodicamente GET /openapi/v2/video/result/{id} usando o video_id retornado. A documentação do PixVerse indica que o status 5 corresponde à geração em andamento e o status 1 ao sucesso; somente então use a URL do vídeo retornada.

Posso usar texto em vez de um arquivo de áudio?

Sim. Selecione um falante TTS embutido ou personalizado e envie lip_sync_tts_speaker_id juntamente com lip_sync_tts_content. Não combine essa rota com um ID de mídia de áudio não relacionado no mesmo exemplo.

Escolha o Vídeo e a Voz Antes de Chamar a API

Este tutorial da API de sincronização labial PixVerse destina-se a uma tarefa específica: aplicar uma linha de fala escolhida a um rosto em movimento existente, recuperar o resultado assíncrono e avaliar se o movimento labial é utilizável. Caso precise criar primeiro o clipe base, uma tomada curta do falante é mais fácil de avaliar do que cortes rápidos, giros de perfil para frente ou rostos ocultos pelas mãos. Você pode gerar esse clipe base por meio de um fluxo de trabalho de imagem para vídeo, uma geração PixVerse ou gravações cujo uso você tem direito.

O guia oficial de Fala do PixVerse identifica duas formas de fornecer a imagem. Um clipe gerado pela sua API já possui um video_id, passado como source_video_id. Um clipe externo é enviado por meio do endpoint de mídia e gera um media_id, passado como video_media_id. Esses IDs não são intercambiáveis. Registre a origem ao lado de cada ID no seu próprio log de tarefas, para que uma nova tentativa posterior não envie um número de mídia enviada no campo destinado a vídeos gerados.

Para a fala, escolha entre uma gravação finalizada com audio_media_id ou uma rota de conversão texto-para-fala com lip_sync_tts_speaker_id e lip_sync_tts_content. As quatro combinações formam uma matriz dois por dois: vídeo gerado ou enviado, cruzado com áudio gravado ou TTS. Uma amostra de voz usada para criar um falante personalizado desempenha um papel distinto do áudio final enviado para uma tarefa de sincronização labial, mesmo que ambos passem por uma etapa de envio de mídia.

As imagens estáticas são ilustrações editoriais de uma apresentadora adulta fictícia, não saída do PixVerse nem comprovação de precisão labial. Elas mostram por que um rosto nítido e uma boca sem obstruções são fundamentais ao escolher um clipe-fonte.

Imagem estática editorial original, não saída do PixVerse. Um rosto frontal e estável é uma entrada prática inicial para verificar o alinhamento da fala.

Mantenha o primeiro teste modesto: um único falante visível, uma frase curta, fala limpa e pouca movimentação da câmera. O guia narrativo de Fala e a referência de envio de mídia atualmente indicam limites de recursos distintos para uploads de sincronização labial, portanto não trate um tamanho ou duração copiados como regra universal permanente. Verifique a documentação específica do endpoint vigente e mantenha a amostra inicial confortavelmente curta. Os créditos da API PixVerse são independentes da associação à sua aplicação web; confirme o saldo antes de iniciar um lote.

Envie Mídia Externa Sem Confundir os IDs

Se você já possui um video_id gerado pelo PixVerse, pule o envio do vídeo. Caso contrário, envie um vídeo externo compatível por meio de POST /openapi/v2/media/upload e armazene o Resp.media_id retornado como video_media_id. Envie uma trilha de voz gravada pelo mesmo endpoint de mídia e armazene seu Resp.media_id retornado como audio_media_id. A documentação do PixVerse lista tipos comuns de vídeo, como MP4, MOV e WebM, e de áudio, como MP3, WAV, M4A e AAC; verifique os formatos e limites de recursos vigentes antes da transferência.

Nomeie os artefatos conforme sua finalidade: speaker-base-v1.mp4, line-01-clean-v1.wav e um registro de tarefa contendo seus IDs de mídia. Mantenha o rosto visível no início da fala, corte eventuais pausas indesejadas e verifique se o clipe-fonte oferece movimento labial suficiente para a nova frase.

Imagem estática editorial original. O enquadramento em três quartos fornece mais pistas de profundidade ao revisor, mas torna mais difícil ocultar dentes, mandíbula e bordas dos lábios caso haja desvio de sincronia.

Para TTS, pule o envio do áudio finalizado. Consulte a lista de vozes, selecione um ID de falante embutido ou crie uma voz personalizada a partir de uma amostra enviada separadamente, com permissão. Não assuma que auto funciona para todos os idiomas; armazene o ID real do falante selecionado. Para múltiplos falantes, crie clipes separados e monte-os posteriormente.

O guia de vídeo com áudio nativo explica por que voz, ambiente sonoro e movimento exigem avaliação conjunta. Obtenha consentimento para usar o rosto ou a voz de uma pessoa real e divulgue adequadamente o uso de fala sintética.

Envie Uma Única Solicitação de Geração Válida

A rota oficial de geração é https://app-api.pixverse.ai/openapi/v2/video/lip_sync/generate. O PixVerse exige um API-KEY e um novo Ai-trace-id para cada nova solicitação à API. Armazene a chave no lado do servidor, não em JavaScript do navegador ou em exemplos de artigos. Reutilizar um ID de rastreamento pode retornar um resultado anterior em vez de iniciar uma nova tarefa intencionada; portanto, registre cada ID juntamente com seus IDs de entrada, versão do script e resposta.Esta solicitação de espaço reservado utiliza um vídeo-fonte gerado por PixVerse mais um áudio final enviado. Substitua os números de exemplo pelos IDs retornados pela sua própria conta; esta solicitação não foi executada para este artigo.

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 um vídeo externo, substitua source_video_id por video_media_id. Para conversão texto-para-fala, substitua audio_media_id por lip_sync_tts_speaker_id e lip_sync_tts_content. Esses são caminhos alternativos, não quatro campos a serem preenchidos indiscriminadamente. O envelope da resposta usa ErrCode, ErrMsg e Resp; ao criar com sucesso uma tarefa, Resp.video_id é o identificador a ser salvo. Isso não comprova que um arquivo reproduzível tenha terminado de ser gerado.

Valide um tipo de ID de vídeo e um modo de fala antes da chamada; rejeite um script TTS vazio. Registre os créditos retornados sem codificar rigidamente um preço. Relacione cada linha e resposta de tarefa a um ID de cena estável, como uma entrega entre primeiro e último quadro para continuidade visual.

Consulte a tarefa e mantenha o resultado rastreável

Após a criação da tarefa, use GET /openapi/v2/video/result/{id} com o video_id retornado. A documentação do PixVerse indica status 5 como “em geração” e status 1 como “bem-sucedido”. Uma resposta HTTP bem-sucedida ou ErrCode: 0 da chamada de criação significa que a tarefa foi aceita, não que o resultado em movimento passou pela sua revisão. Quando o status for 1, recupere a URL de saída do resultado e salve uma cópia conforme sua política normal de ativos antes que a URL expire ou as regras de acesso mudem.

O status 7 é documentado como falha na moderação de conteúdo e o status 8 como falha na geração. Trate cada um como uma tarefa interrompida, em vez de consultar indefinidamente. Um consultor de produção deve ter um tempo de espera limitado, retrocesso (backoff) e um registro durável do último status observado. Se seu worker reiniciar, retome a partir do video_id armazenado, em vez de criar novamente a mesma tarefa paga. Use um novo ID de rastreamento para uma solicitação deliberadamente nova, mas não crie novas tentativas quando uma tarefa lenta estiver simplesmente em processamento.

Imagem editorial original. Um enquadramento mais amplo testa se o sincronismo facial permanece legível enquanto o intérprete se move, mas nenhuma imagem estática pode comprovar a sincronização labial real.

Mantenha um registro legível do ID da cena, dos IDs de vídeo e de fala, do ID de rastreamento, do video_id gerado, da URL final e do veredicto de revisão. Nunca armazene credenciais nesse log de revisão. O guia de fluxo de trabalho do Agente PixVerse abrange a tarefa mais ampla, desde a instrução até a cena.

Revise o movimento bucal, o áudio e os limites dos cortes

Assista ao arquivo final em movimento à velocidade normal com som, depois em velocidade reduzida em torno de sílabas selecionadas. Escolha uma frase contendo sons bilabiais visíveis, como p, b e m, e uma vogal aberta mais longa. Observe o fechamento da boca antes dessas consoantes, uma abertura plausível na vogal e uma fala que comece e termine sem atraso perturbador. Este é um método de inspeção editorial, não um benchmark relatado nem uma afirmação sobre uma taxa de sucesso medida do PixVerse.

Compare a saída com a fonte: direção do olhar, identidade, mandíbula, iluminação e dentes não devem mudar abruptamente. Verifique tanto o close-up quanto o clipe completo. Essas imagens estáticas não constituem um resultado “antes/depois” do PixVerse.

Imagem editorial original. Ângulos de perfil revelam erros no contorno da mandíbula e dos lábios que uma miniatura frontal pode ocultar.

O clipe reproduzível abaixo é um exemplo real existente de diálogo Seedance em movimento. É independente da API PixVerse e do apresentador ilustrado; está incluído exclusivamente para tornar concreta a inspeção completa de voz e movimento bucal. Não demonstra um resultado de sincronização labial gerado pelo PixVerse nem desempenho comparativo.

Amostra independente de diálogo Seedance para revisão completa de movimento bucal e vocal

Assista à linha inteira e avalie boca, voz, movimento da cabeça e cortes em conjunto; este não é uma saída do PixVerse.

Use um cartão simples de aceitação: aprovar se a linha for inteligível, iniciar no batimento pretendido, manter a identidade do falante e resistir à avaliação em velocidade normal; corrigir se apenas o limite do corte ou o ajuste do áudio estiverem incorretos; rejeitar se a forma da boca, o rosto ou o sincronismo falharem de forma generalizada. A aprovação deve basear-se no arquivo em movimento, não na imagem estática. Um exemplo separado de fluxo de trabalho de sincronização labial pode ajudar a comparar hábitos gerais de revisão, mas seus controles de fornecedor não são intercambiáveis com os campos da API PixVerse.

Solucione problemas na camada correta e organize a entrega

Se a API rejeitar uma solicitação, examine a resposta e o par de parâmetros. Verifique se houve troca entre tipos de ID de vídeo, uso de um ID de amostra de voz como áudio final, campos TTS ausentes ou reutilização de um ID de rastreamento. Confirme autorização, créditos, tipo de mídia, limites e concorrência. Nunca cole uma chave de API em uma captura de tela enviada ao suporte.Se o trabalho for concluído com sucesso, mas a saída parecer incorreta, alterar o endpoint provavelmente não resolverá problemas na geometria da fonte. Experimente um clipe mais estável, uma voz mais clara, menos oclusão, uma fala mais curta e um rosto que permaneça dentro do quadro. Se a sincronização falhar apenas na primeira palavra, verifique o áudio de entrada (lead-in) e o quadro inicial do vídeo; se falhar apenas em uma transição (cut), ajuste o limite da edição e o tom ambiente (room tone). Mantenha a melhor gravação aprovada enquanto executa novamente apenas a linha problemática.

Seedance Agent é aplicado após a existência do resultado da API: mantenha juntos o clipe base aprovado, a versão vocal, a saída gerada, as anotações de aceitação e a decisão de montagem; planeje ou substitua uma única tomada sem reconstruir toda a peça. Ele pode coordenar a organização de referências e revisões, mas não realiza uma chamada não testada à API PixVerse nem certifica um resultado PixVerse. Mantenha uma proveniência clara ao combinar saídas de diferentes provedores.

Conclusão

Um fluxo de trabalho confiável de API de sincronização labial PixVerse escolhe um único tipo de ID de vídeo e um único modo de fala, envia apenas os meios necessários, envia uma única solicitação bem formatada com um novo trace ID, aguarda a conclusão do video_id retornado e avalia o resultado final em movimento. Consulte sempre a documentação atual de PixVerse como referência autorizada quanto a limites e cobranças, e mantenha a aceitação editorial separada da criação da tarefa. Quando várias linhas aprovadas precisam ser transformadas em um único produto final coerente, organize as referências, revisões e montagem final em Seedance Agent.