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-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/lipsync-image-multi

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

GET/api/v1/jobs/{requestId}

Consultar status do job e obter resultado

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.)

resolutionopcional

"480p" ou "720p" (padrão: 480p)

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

Async Workflow

Choose how to receive your results

All API calls are asynchronous. You have two options to retrieve results:

Option 1: Webhook (Recommended)

Provide a webhook URL in the JSON body. We will POST the result to your endpoint when the job completes.

Benefits:

No need to poll repeatedly
Instant notification when job completes
More efficient for long-running jobs (30-120 seconds typical)

Option 2: Polling

Omit the webhook parameter and use the returned requestId to poll GET /api/v1/jobs/{requestId} every 5-10 seconds until status is "completed".

Use when:

You cannot expose a public webhook endpoint
Testing or debugging

Example with 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:
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

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

Example without 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:
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

// 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",
  "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": "Invalid audio format",
  "executionTime": null,
  "timings": null
}

Complete Code Examples

Ready-to-use integration examples

✓Node.js with Webhook (Recommended)

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.id);
  console.log('Waiting for webhook callback...');
  
  // You don't need to poll! The result will be POSTed to your webhook.
}

submitJobWithWebhook();