Documentação da API do FreeLipSync

Antes de começar

Use a API REST do FreeLipSync para gerar vídeos com sincronização labial, fotos falantes e vídeos musicais a partir do seu áudio. Você precisa de uma conta registrada, uma API Key do console Agent e créditos da API. Todas as contas, inclusive as existentes, recebem 30 créditos de boas-vindas uma única vez ao carregar o saldo no console Agent pela primeira vez ou enviar uma solicitação de geração válida. Você pode comprar mais créditos; a assinatura não inclui créditos recorrentes da API. Seu plano determina os modelos disponíveis, a duração e os limites compartilhados de tarefas.

Este guia usa https://freelipsync.com/api/v1. Ao testar em staging, configure FLS_BASE_URL para a origem desse ambiente e crie sua chave no mesmo ambiente. O acesso à API deve estar habilitado nessa implantação. Os exemplos usam um speech.mp3 curto e um face.jpg de face única.

Abra a referência OpenAPI para esquemas de solicitação e resposta legíveis por máquina. Prefere um agente? Consulte o guia de configuração MCP.

Autenticação e sua primeira solicitação

Crie uma chave no console Agent e copie-a da caixa de diálogo de criação. O segredo completo é mostrado uma vez. Armazene-o em uma variável de ambiente, não no código do navegador ou em um repositório público. Se perdido, revogue-o e crie outro. Todas as chaves usam o mesmo saldo e limites da conta; criar outra chave não aumenta a simultaneidade.

export FLS_BASE_URL='https://freelipsync.com'
export FLS_API_KEY='YOUR_API_KEY'
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $FLS_API_KEY" \
  "$FLS_BASE_URL/api/v1/capabilities"

REST aceita seu API Key. Um token de acesso OAuth emitido para MCP é válido apenas para /mcp, não para REST. Uma resposta bem-sucedida envolve seu resultado em data e inclui request_id; os erros têm error e request_id. IDs são strings opacas e os valores de crédito são strings decimais.

{"data":{"id":"YOUR_ASSET_ID","kind":"image","status":"processing","poll_after_seconds":5,"expires_at":"2026-10-21T00:00:00.000Z"},"request_id":"REQUEST_ID"}

Esta é uma resposta de recurso ilustrativa, não a resposta à solicitação de recursos. Leia os recursos retornados para verificar os modelos da conta atual, max_audio_seconds, limites de bytes de upload/MIME e limites de tarefas antes de preparar os arquivos.

O fluxo de trabalho de geração

1. Busque recursos e carregue uma imagem ou vídeo junto com o áudio de referência.
2. Confirme cada upload direto e espere que ambos os ativos se tornem ready.
3. Crie uma cotação usando os IDs dos ativos e um modo de geração. Revise total_points e expires_at.
4. Envie essa cotação com uma chave de idempotência estável. Isso aceita a tarefa e retém os créditos.
5. Pesquise o ID do trabalho retornado usando poll_after_seconds ou receba um webhook.
6. Quando concluído, baixe do URL assinado. Uma tarefa com falha retorna sua retenção original.

A criação de ativos e cotações não gasta créditos nem cria trabalhos de vídeo. Depois que uma geração for aceita, ela não poderá ser cancelada. Somente falha no processamento retorna créditos; o tempo limite do cliente não é prova de que a tarefa falhou.

Faça upload de arquivos locais ou importe URLs

Para um arquivo local, POST /assets retorna um PUT URL assinado. Envie bytes de arquivo brutos com o upload.headers retornado, sem o API Key. Em seguida, ligue para POST /assets/{id}/confirm com {} e pesquise GET /assets/{id}. awaiting_upload e processing não estão prontos; failed é terminal. Use o conselho de pesquisa do servidor.

{
  "kind":"image",
  "source":{
    "type":"upload",
    "filename":"face.jpg",
    "content_type":"image/jpeg",
    "size_bytes":123456
  }
}

size_bytes deve ser a contagem real de bytes, não este número de exemplo. As entradas de imagem, vídeo e áudio possuem MIME e limites de tamanho diferentes; use GET /capabilities como fonte da verdade. As extensões de arquivo por si só não determinam a validade.

Você também pode importar um HTTPS URL acessível publicamente. Isso é assíncrono: pesquise o ativo retornado até que esteja pronto. Um caminho local, file:// URL, rede privada URL ou URL que exige cookies do seu site não é uma fonte utilizável. Se estiver usando uma fonte assinada URL, aguarde tempo suficiente para ser buscada.

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $FLS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: image-import-UNIQUE-REQUEST-ID' \
  --data '{"kind":"image","source":{"type":"url","url":"https://YOUR-PUBLIC-HOST/face.jpg"}}' \
  "$FLS_BASE_URL/api/v1/assets"

Uma terceira rota é POST /asset-upload-sessions com {"kind":"image"}: retornar o browser_upload_url ao usuário, reter asset_id e pesquisá-lo após o upload no navegador. Isto é útil para clientes que não conseguem ler arquivos locais. Os tickets de upload e URLs assinados são credenciais temporárias; não os publique em registros ou transcrições de bate-papo.

Exemplos completos de código

Escolha cURL, Python ou JavaScript abaixo. Cada exemplo executa o mesmo fluxo de trabalho de upload → cotação → envio → enquete → download, imprimindo a cotação e perguntando antes de gastar os créditos. Exemplos longos são resumidos; o botão Copiar sempre copia o programa completo.

• cURL: Bash, cURL, jq e Python 3 (para UUIDs). Salve como um script Bash e execute-o.
• Python: Python 3 com a biblioteca requests; instale com python -m pip install requests.
• JavaScript: Node.js 20+ e apenas módulos integrados. Salve como quickstart.mjs e execute node quickstart.mjs.

Exporte as variáveis de ambiente acima e coloque face.jpg e speech.mp3 no diretório de trabalho. Execute em seu servidor ou máquina de desenvolvimento, não em uma página pública. Solicitações de upload/download assinadas nunca incluem seu API Key. Os scripts param em erros HTTP; verifique as regras de recuperação abaixo antes de tentar novamente, em vez de reiniciar um envio possivelmente aceito com uma nova chave.

# Requires bash, curl and jq. Set these before running:
# export FLS_API_KEY='YOUR_API_KEY'
# export FLS_BASE_URL='https://freelipsync.com'  # or your staging origin
# Place face.jpg and speech.mp3 in this directory.
set -euo pipefail
: "${FLS_API_KEY:?Set FLS_API_KEY first}"
BASE="${FLS_BASE_URL:-https://freelipsync.com}/api/v1"
RUN="$(python3 -c 'import uuid; print(uuid.uuid4())')"
request() {
  curl --fail-with-body --silent --show-error \
    -H "Authorization: Bearer $FLS_API_KEY" "$@"
}
wait_ready() {
  local id="$1" row status
  for ((i=0; i<120; i++)); do
    row="$(request "$BASE/assets/$id")"

Modelos, opções e créditos

Todos os modos exigem um recurso de áudio de referência carregado. Conversão de texto para fala, clonagem de voz e cancelamento não são parâmetros desta API. Image Super/Motion Control requer Starter ou Pro; comprar créditos por si só não permite isso. Verifique os recursos para disponibilidade do modelo e limites de duração, incluindo exceções específicas do modelo.

A cobrança arredonda a duração verificada do áudio para cima, até o próximo segundo inteiro, com mínimo de 5 segundos. Uma cotação de 5 segundos custa 5 créditos no Image Fast, 10 no Image Max e 15 no Image Super ou Music Video. Criar uma cotação não debita a carteira. O envio reserva o valor da cotação; o sucesso consome esse mesmo valor, e a falha no processamento devolve a reserva. Não há ajuste de preço após a geração. Os créditos comprados são separados da assinatura, não expiram e não são reembolsáveis em dinheiro.

{
  "mode":"image_super",
  "face_asset_id":"READY_IMAGE_ID",
  "audio_asset_id":"READY_AUDIO_ID",
  "options":{"motion":{"action":"Smile gently","camera":"Static camera"}}
}

Para Music Video, use mode: "music_video" e as configurações MV abaixo. version aceita 1.0 ou 1.1; ratio aceita 21:9, 16:9, 4:3, 1:1, 3:4 ou 9:16; resolution aceita 480p ou 720p. Os padrões são 1.0, 16:9 e 480p. Verifique os recursos do esquema ativo. Não anexe opções de movimento a outro modo nem envie aliases de modelos da web internos.

{
  "mode":"music_video",
  "face_asset_id":"READY_IMAGE_ID",
  "audio_asset_id":"READY_AUDIO_ID",
  "options":{"mv":{"version":"1.0","ratio":"16:9","resolution":"480p","style":{"directorial":"A calm performance","artistic":"Warm evening light"}}}
}

Referência de ponto final

Os caminhos abaixo são relativos a /api/v1. Todas as chamadas comerciais requerem autenticação.

As listas são padrão para itens 20, máximo 50. Passe data.next_cursor inalterado para buscar a próxima página. Para vários trabalhos ativos, use ids separados por vírgula em uma solicitação de lista em vez de pesquisar cada um separadamente. A lista é para trabalhos de crédito API/MCP, não uma lista geral de trabalhos de sites mais antigos.

Idempotência, erros e limites de requisições

Use um Idempotency-Key novo para cada operação de gravação distinta e mantenha a mesma chave e carga ao tentar novamente essa operação. As chaves são caracteres ASCII visíveis 8–128. Uma nova solicitação de usuário precisa de uma nova chave; uma nova tentativa não. Os exemplos imprimem o par cotação/chave antes do envio. Na produção, persista esse par antes de enviar e persista o ID do trabalho retornado. Não reinicie todo o exemplo após um envio incerto: isso criaria uma nova chave.

As cotações expiram em 10 minutos. Uma rejeição definitiva antes da aceitação permite corrigir o pedido ou obter um novo orçamento; uma resposta incerta requer primeiro a recuperação da tentativa original. A repetição de uma tarefa aceita retorna seu trabalho original sem um segundo débito. Uma cotação não pode ser gasta duas vezes em chaves diferentes.

REST e MCP compartilham um bucket de leitura/auxiliar por conta: Free 30, Starter 30, Pro 60 solicitações por minuto. As chamadas auxiliares incluem uploads, confirmação e cotações. Respeite poll_after_seconds e Retry-After, o que exigir maior espera. As leituras de status do site são gerenciadas separadamente; a frequência de geração e a capacidade de execução de vídeo são compartilhadas entre site, REST e MCP. O site e API/MCP têm, cada um, uma permissão independente para tarefas inacabadas: Free 1, Starter 3, Pro 10 por pool. REST e MCP compartilham o pool API/MCP, incluindo todas as chaves e conexões OAuth; credenciais extras nunca o multiplicam. Consulte por que usar API/MCP para obter exemplos de fluxo de trabalho.

Resultados e webhooks opcionais

Os trabalhos têm status queued, processing, completed ou failed. Mantenha o ID do trabalho quando seu aplicativo expirar; seu tempo limite não cancela a tarefa do servidor. Em caso de sucesso, use output.download_url enquanto for válido. Busque novamente o trabalho ou o endpoint de download para obter um link renovado enquanto o trabalho é retido; downloads repetidos não gastam créditos. A retenção segue o trabalho normal de retenção da sua conta, e não um período separado apenas de API. A saída é de qualidade original, sem marca d'água e utilizável comercialmente, sujeita aos seus direitos de fonte e aos termos.

Para integrações de servidor, crie um endpoint de webhook no console Agent → Avançado e, em seguida, passe seu ID como webhook_endpoint_id no envio. Seu endpoint deve primeiro responder ao POST endpoint.verification com o desafio como um corpo de resposta em texto simples. Esta configuração usa o console do site, não uma API pública de gerenciamento de credenciais.

Os eventos de webhook contêm event_id, event_type, occurred_at, generation_id e data. Os links para download são omitidos das cargas úteis do webhook; consulte o trabalho para obter um novo link. Verifique FLS-Webhook-Signature em relação ao corpo da solicitação raw: HMAC-SHA256 de timestamp + "." + body, usando seu segredo de endpoint, com o carimbo de data/hora de FLS-Webhook-Timestamp; combine uma assinatura v1= em tempo constante e aplique um carimbo de data/hora recente para rejeitar replays. Desduplicar por event_id / FLS-Webhook-Id e retornar 2xx imediatamente. Notificações duplicadas não devem desencadear outra geração ou uma segunda ação comercial. Continue a votação como a primeira integração mais simples.

Precisa trabalhar com um assistente em vez de HTTP? Configure MCP com seu agente ou retorne ao console Agent.