API para desenvolvedores

Plataforma de API Lipsync

Gere vídeos de lipsync programaticamente com nossa poderosa API REST

Chaves de API

Gerencie suas chaves de autenticação

Criar nova chave de API

Dê um nome fácil de lembrar (opcional)

Faça login para criar e gerenciar chaves de API.

Preços que funcionam para você

Comece com planos flexíveis e competitivos

Preços da API

Pague conforme o uso

Nota: Créditos de API e de usuário são independentes e não intercambiáveis.

Notas:

Cobrança mínima: 5 segundos por geração

480p: 2 créditos por segundo

720p: 4 créditos por segundo

lipsync-image/video/multi 1080p: 6 créditos por segundo, mínimo de 30 créditos

lipsync-image/video/multi 2k: 7 créditos por segundo, mínimo de 35 créditos

lipsync-image/video/multi 4k: 8 créditos por segundo, mínimo de 40 créditos

talking-avatar: 720p/1080p/2k/4k custa 4/6/8/9 créditos por segundo de áudio arredondado para cima

lipsync-video: Se o vídeo for maior que o áudio, será cortado; se o áudio for maior, será estendido automaticamente. A cobrança usa a duração do áudio no corte e a do vídeo na extensão.

lipsync-image-multi: Se order for "meanwhile", usa a duração máxima do áudio; caso contrário, a soma de "left_audio" e "right_audio".

Exemplo 1:

Áudio de 3 s em 720p = 5 s × 4 = 20 créditos

(aplica cobrança mínima)

Exemplo 2:

Áudio de 10 s em 480p = 10 × 2 = 20 créditos

Autenticação

Proteja suas requisições à API

Inclua sua chave de API no cabeçalho Authorization:

Authorization: Bearer sk_XXXX_YYYY

Endpoints disponíveis

Endpoints RESTful

POST/api/v1/lipsync-video

Vídeo para vídeo com substituição de áudio (lipsync)

POST/api/v1/lipsync-image

Imagem + áudio → avatar de um único falante

POST/api/v1/talking-avatar

Imagem + áudio + prompt -> avatar falante com expressão e movimento controlados

POST/api/v1/lipsync-image-multi

Imagem + dois áudios → avatar multi-falantes (conversa/diálogo)

GET/api/v1/jobs/{requestId}

Consultar status do job e obter resultado

Escopo atual da API

Entradas, privacidade, cobertura de modelos e notas de produção

As entradas são baseadas em URL

A API pública atualmente aceita URLs de mídia em JSON. Upload direto multipart e endpoints de upload de assets ainda não estão disponíveis. URLs assinadas ou temporárias são suportadas desde que nossos workers e o provedor de geração possam acessá-las enquanto o job estiver em execução.

As saídas da API são privadas

Jobs da API são armazenados com visibilidade privada. O botão Public da web não se aplica a solicitações de API, e atualmente não há parâmetro de API para publicar uma geração.

Seleção de modelo

Selecione o fluxo pelo endpoint: lipsync-image, lipsync-video ou lipsync-image-multi. Use talking-avatar para o modelo de imagem com controle de expressão e movimento.

Ainda não há arquivo OpenAPI

Esta página é a referência atual da API. Uma especificação OpenAPI/Swagger legível por máquina ainda não foi publicada.

Controles não suportados

Proporção, guidance scale e audio guidance não estão expostos como parâmetros de API para os endpoints atuais de lip-sync.

Jobs em lote

Envie uma solicitação de API por geração. Para grandes lotes de produção, mantenha as URLs de entrada válidas até a conclusão e fale com o suporte antes de executar concorrência muito alta.

Parâmetros detalhados

Especificações completas do endpoint

Todos os endpoints compartilham uma estrutura comum: parâmetro opcional webhook e parâmetros específicos em formState.

POST /api/v1/lipsync-video

Substitui o áudio de um vídeo existente mantendo a sincronização labial

Parâmetros de alto nível:

webhookopcional

Sua URL de callback (HTTPS). Enviaremos o resultado via POST ao finalizar.

formStateobrigatório

Objeto contendo todos os parâmetros de geração (veja abaixo).

Parâmetros de formState:

videoobrigatório

URL pública do vídeo de origem (MP4, MOV, etc.)

audioobrigatório

URL pública do áudio (MP3, WAV, etc.)

resolutionobrigatório

"360p", "480p", "720p", "1080p", "2k" ou "4k"

mask_imageopcional

URL pública da imagem de máscara (restringe a área de lipsync)

promptopcional

Texto de orientação de estilo

seedopcional

Semente inteira para reprodutibilidade

Fluxo assíncrono

Escolha como receber os resultados

Todas as chamadas de API são assíncronas. Você tem duas opções para recuperar resultados:

Para jobs em 1080p, 2k e 4k, respostas de webhook e polling retornam apenas o vídeo final ampliado.

Opção 1: Webhook (Recomendado)

Forneça uma URL de webhook no JSON. Faremos POST do resultado ao concluir.

URLs de webhook devem ser URLs HTTPS públicas. Se a entrega falhar, tentamos novamente até 5 vezes com backoff exponencial.

Benefícios:

Sem necessidade de polling repetido
Notificação instantânea ao concluir
Mais eficiente para jobs longos (típico 30–120 s)

Opção 2: Polling

Omitir webhook e usar o requestId retornado para consultar GET /api/v1/jobs/{requestId} a cada 5–10 s até o status ser "completed".

Usar quando:

Não é possível expor um endpoint público de webhook
Teste ou depuração

Exemplo com Webhook:

POST /api/v1/lipsync-image
Authorization: Bearer sk_XXXX_YYYY
Content-Type: application/json

{
  "webhook": "https://your-app.example.com/webhooks/lipsync",
  "formState": {
    "image": "https://.../face.png",
    "audio": "https://.../voice.mp3",
    "resolution": "720p",
    "seed": 42
  }
}

// Immediate Response:
{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "message": "Task submitted successfully. Use requestId to query job status."
}

// Later, when job completes, we POST to your webhook:
POST https://your-app.example.com/webhooks/lipsync
Content-Type: application/json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "lipsync-image",
  "status": "completed",
  "output": "https://.../result.mp4",
  "error": "",
  "executionTime": 12345,
  "timings": null
}

Exemplo de solicitação de Talking Avatar:

POST /api/v1/talking-avatar
Authorization: Bearer sk_XXXX_YYYY
Content-Type: application/json

{
  "webhook": "https://your-app.example.com/webhooks/lipsync",
  "formState": {
    "image": "https://.../character.png",
    "audio": "https://.../speech.mp3",
    "prompt": "Warm presentation style, natural facial expression, subtle head motion",
    "resolution": "1080p"
  }
}

// Completed webhook or polling response:
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "talking-avatar",
  "status": "completed",
  "output": "https://.../result.mp4",
  "error": "",
  "executionTime": 12345,
  "timings": null
}

Exemplo sem Webhook (Polling):

// Step 1: Submit job (no webhook parameter)
POST /api/v1/lipsync-image
Authorization: Bearer sk_XXXX_YYYY
Content-Type: application/json

{
  "formState": {
    "image": "https://.../face.png",
    "audio": "https://.../voice.mp3",
    "resolution": "720p"
  }
}

// Immediate Response:
{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "message": "Task submitted successfully. Use requestId to query job status."
}

// Step 2: Poll for status (repeat every 5-10 seconds)
GET /api/v1/jobs/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer sk_XXXX_YYYY

// Response while processing:
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "lipsync-image",
  "status": "processing",
  "output": null,
  "error": "",
  "executionTime": null,
  "timings": null
}

// Response when completed:
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "lipsync-image",
  "status": "completed",
  "output": "https://.../result.mp4",
  "error": "",
  "executionTime": 12345,
  "timings": null
}

// Response if failed:
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "model": "lipsync-image",
  "status": "failed",
  "output": null,
  "error": "Generation failed. Please try again later.",
  "executionTime": null,
  "timings": null
}

Exemplos completos de código

Exemplos de integração prontos para uso

01Node.js com Webhook (Recomendado)

import fetch from 'node-fetch';
import express from 'express';

const API_KEY = 'Bearer sk_XXXX_YYYY';
const BASE_URL = 'https://lipsync.studio/api/v1';

// Set up webhook server to receive results
const app = express();
app.use(express.json());

app.post('/webhooks/lipsync', (req, res) => {
  const { id, status, output, error, model } = req.body;
  
  console.log('Job update received.');
  console.log('Job ID:', id);
  console.log('Model:', model);
  console.log('Status:', status);
  if (status === 'completed') {
    console.log('Video URL:', output);
  } else if (status === 'failed') {
    console.error('Error:', error);
  }
  
  // TODO: Save output URL to your database, send notification, etc.
  
  res.status(200).json({ received: true });
});

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});

// Submit job with webhook
async function submitJobWithWebhook() {
  const webhookUrl = 'https://your-public-domain.com/webhooks/lipsync';
  
  const res = await fetch(`${BASE_URL}/lipsync-image`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': API_KEY
    },
    body: JSON.stringify({
      webhook: webhookUrl,
      formState: {
        image: 'https://example.com/portrait.jpg',
        audio: 'https://example.com/speech.mp3',
        resolution: '720p'
      }
    })
  });
  
  const data = await res.json();
  console.log('Job submitted:', data.requestId);
  console.log('Waiting for webhook callback...');
  
  // You don't need to poll! The result will be POSTed to your webhook.
}

submitJobWithWebhook();