API per sviluppatori

Piattaforma API Lipsync

Genera video lipsync con la nostra potente API REST

Chiavi API

Gestisci le tue chiavi di autenticazione

Crea nuova chiave API

Assegna un nome facile da ricordare (opzionale)

Accesso richiesto

Accedi per creare e gestire le chiavi API.

Prezzi su misura per te

Inizia con piani flessibili e competitivi

Prezzi API

A consumo

Nota: I crediti API e utente sono indipendenti e non intercambiabili.

Note:

Addebito minimo: 5 secondi per generazione

480p: 2 crediti al secondo

720p: 4 crediti al secondo

lipsync-video: Se il video è più lungo dell'audio viene tagliato; se l'audio è più lungo, si estende automaticamente. La fatturazione usa la durata dell'audio nel taglio e del video nell'estensione.

lipsync-image-multi: Se order è "meanwhile", si usa la durata massima; altrimenti la somma di "left_audio" e "right_audio".

Esempio 1:

Audio di 3 s a 720p = 5 s × 4 = 20 crediti

(si applica l'addebito minimo)

Esempio 2:

Audio di 10 s a 480p = 10 × 2 = 20 crediti

Autenticazione

Proteggi le tue richieste API

Includi la chiave API nell'header Authorization:

Authorization: Bearer sk_XXXX_YYYY

Endpoint disponibili

Endpoint RESTful

POST/api/v1/lipsync-video

Video a video con sostituzione dell'audio (lipsync)

POST/api/v1/lipsync-image

Immagine + audio → avatar con un solo parlante

POST/api/v1/lipsync-image-multi

Immagine + doppio audio → avatar multi-parlante (conversazione/dialogo)

GET/api/v1/jobs/{requestId}

Consulta lo stato del job e recupera il risultato

Parametri dettagliati

Specifiche complete dell'endpoint

Tutti gli endpoint condividono una struttura comune: webhook opzionale e parametri specifici del modello in formState.

POST /api/v1/lipsync-video

Sostituisce l'audio di un video mantenendo la sincronizzazione labiale

Parametri di alto livello:

webhookopzionale

La tua URL di callback (HTTPS). Inviamo il risultato via POST al termine.

formStateobbligatorio

Oggetto con tutti i parametri di generazione (vedi sotto).

Parametri di formState:

videoobbligatorio

URL pubblica del video sorgente (MP4, MOV, ecc.)

audioobbligatorio

URL pubblica dell'audio (MP3, WAV, ecc.)

resolutionopzionale

"480p" o "720p" (predefinito: 480p)

mask_imageopzionale

URL pubblica della maschera (limita l'area di lipsync)

promptopzionale

Testo guida per lo stile

seedopzionale

Seed intero per la riproducibilità

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();