API para desarrolladores

Plataforma de API de Lipsync

Genera videos de sincronización labial mediante nuestra potente API REST

Claves de API

Administra tus claves de autenticación

Crear nueva clave de API

Ponle un nombre fácil de recordar (opcional)

Inicio de sesión requerido

Inicia sesión para crear y administrar claves de API.

Precios a tu medida

Empieza con planes flexibles y competitivos

Precios de la API

Pago por uso

Nota: Los créditos de API y de usuario son independientes y no intercambiables.

Notas:

Cargo mínimo: 5 segundos por generación

Resolución 480p: 2 créditos por segundo

Resolución 720p: 4 créditos por segundo

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

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

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

talking-avatar: 720p/1080p/2k/4k cuesta 4/6/8/9 créditos por cada segundo de audio redondeado hacia arriba

lipsync-video: Si el video es más largo que el audio, se recorta; si el audio es más largo, se extiende automáticamente. La facturación usa la duración del audio en recorte y la del video en extensión.

lipsync-image-multi: Si order es "meanwhile", se usa la duración máxima de los audios; de lo contrario, la suma de "left_audio" y "right_audio".

Ejemplo 1:

Audio de 3 s a 720p = 5 s × 4 = 20 créditos

(aplica cargo mínimo)

Ejemplo 2:

Audio de 10 s a 480p = 10 × 2 = 20 créditos

Autenticación

Asegura tus solicitudes a la API

Incluye tu clave de API en el encabezado Authorization:

Authorization: Bearer sk_XXXX_YYYY

Endpoints disponibles

Endpoints RESTful

POST/api/v1/lipsync-video

Video a video con sustitución de audio (labios sincronizados)

POST/api/v1/lipsync-image

Imagen + audio → avatar de un hablante

POST/api/v1/talking-avatar

Imagen + audio + prompt -> avatar parlante con expresión y movimiento controlados

POST/api/v1/lipsync-image-multi

Imagen + doble audio → avatar multi-hablante (conversación/diálogo)

GET/api/v1/jobs/{requestId}

Consulta el estado del trabajo y recupera el resultado

Alcance actual de la API

Entradas, privacidad, cobertura de modelos y notas de producción

Las entradas se basan en URL

La API pública acepta actualmente URL de medios en JSON. La subida directa de archivos multipart y los endpoints de carga de recursos aún no están disponibles. Se admiten URL firmadas o temporales siempre que nuestros workers y el proveedor de generación puedan acceder a ellas mientras el trabajo se ejecuta.

Las salidas de la API son privadas

Los trabajos de API se almacenan con visibilidad privada. El interruptor Public de la web no se aplica a las solicitudes de API y actualmente no existe un parámetro de API para publicar una generación.

Selección de modelo

Selecciona el flujo por endpoint: lipsync-image, lipsync-video o lipsync-image-multi. Usa talking-avatar para el modelo de imagen con control de expresión y movimiento.

Aún no hay archivo OpenAPI

Esta página es la referencia actual de la API. Actualmente no se publica una especificación OpenAPI/Swagger legible por máquina.

Controles no compatibles

La relación de aspecto, guidance scale y audio guidance no están expuestos como parámetros de API para los endpoints actuales de lip-sync.

Trabajos por lotes

Envía una solicitud de API por generación. Para lotes grandes de producción, mantén válidas las URL de entrada hasta finalizar y contacta con soporte antes de ejecutar concurrencias muy altas.

Parámetros detallados

Especificaciones completas del endpoint

Todos los endpoints comparten una estructura común: parámetro opcional webhook y parámetros específicos en formState.

POST /api/v1/lipsync-video

Sustituye el audio de un video existente manteniendo la sincronía labial

Parámetros de nivel superior:

webhookopcional

Tu URL de callback (HTTPS). Enviamos el resultado por POST al completar.

formStaterequerido

Objeto con todos los parámetros de generación (ver abajo).

Parámetros de formState:

videorequerido

URL pública del video fuente (MP4, MOV, etc.)

audiorequerido

URL pública del audio (MP3, WAV, etc.)

resolutionrequerido

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

mask_imageopcional

URL pública de la imagen máscara (limita el área de sincronización labial)

promptopcional

Texto de guía de estilo

seedopcional

Semilla entera para reproducibilidad

Flujo asíncrono

Elige cómo recibir los resultados

Todas las llamadas a la API son asíncronas. Tienes dos opciones para recuperar los resultados:

Para trabajos 1080p, 2k y 4k, las respuestas de webhook y polling devuelven solo el resultado final de video reescalado.

Opción 1: Webhook (Recomendado)

Proporciona una URL de webhook en el JSON. Enviaremos el resultado por POST al completar.

Las URL de webhook deben ser URL HTTPS públicas. Si la entrega falla, reintentamos hasta 5 veces con retroceso exponencial.

Beneficios:

Sin necesidad de sondear repetidamente
Notificación instantánea al completar
Más eficiente para trabajos largos (30–120 s típicos)

Opción 2: Sondeo

Omite el webhook y usa el requestId devuelto para sondear GET /api/v1/jobs/{requestId} cada 5–10 s hasta que el estado sea "completed".

Úsalo cuando:

No puedes exponer un endpoint público de webhook
Pruebas o depuración

Ejemplo con 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
}

Ejemplo de solicitud 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
}

Ejemplo sin Webhook (Sondeo):

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

Ejemplos completos de código

Ejemplos de integración listos para usar

01Node.js con 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();