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

Note:

Addebito minimo: 5 secondi per generazione

480p: 2 crediti al secondo

720p: 4 crediti al secondo

lipsync-image/video/multi 1080p: 6 crediti al secondo, minimo 30 crediti

lipsync-image/video/multi 2k: 7 crediti al secondo, minimo 35 crediti

lipsync-image/video/multi 4k: 8 crediti al secondo, minimo 40 crediti

talking-avatar: 720p/1080p/2k/4k costa 4/6/8/9 crediti per secondo audio arrotondato per eccesso

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/talking-avatar

Immagine + audio + prompt -> avatar parlante con espressione e movimento controllati

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

Ambito attuale dell’API

Input, privacy, copertura dei modelli e note di produzione

Gli input sono basati su URL

L’API pubblica attualmente accetta URL multimediali in JSON. Il caricamento diretto multipart e gli endpoint di upload asset non sono ancora disponibili. URL firmati o temporanei sono supportati se i nostri worker e il provider di generazione possono recuperarli durante l’esecuzione del job.

Gli output API sono privati

I job API vengono salvati con visibilità privata. Il toggle Public del web non si applica alle richieste API e attualmente non esiste un parametro API per pubblicare una generazione.

Selezione del modello

Seleziona il workflow tramite endpoint: lipsync-image, lipsync-video o lipsync-image-multi. Usa talking-avatar per il modello immagine con controllo di espressione e movimento.

Nessun file OpenAPI per ora

Questa pagina è l’attuale riferimento API. Una specifica OpenAPI/Swagger leggibile da macchina non è attualmente pubblicata.

Controlli non supportati

Aspect ratio, guidance scale e audio guidance non sono esposti come parametri API per gli endpoint lip-sync attuali.

Job batch

Invia una richiesta API per ogni generazione. Per grandi batch di produzione, mantieni validi gli URL di input fino al completamento e contatta il supporto prima di usare concorrenza molto elevata.

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

resolutionobbligatorio

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

mask_imageopzionale

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

promptopzionale

Testo guida per lo stile

seedopzionale

Seed intero per la riproducibilità

Flusso asincrono

Scegli come ricevere i risultati

Tutte le chiamate API sono asincrone. Hai due opzioni per recuperare i risultati:

Per job 1080p, 2k e 4k, le risposte webhook e polling restituiscono solo il video finale upscalato.

Opzione 1: Webhook (Consigliato)

Fornisci una URL di webhook nel JSON. Invieremo il risultato via POST al termine.

Gli URL webhook devono essere URL HTTPS pubblici. Se la consegna fallisce, riproviamo fino a 5 volte con backoff esponenziale.

Vantaggi:

Nessun polling ripetuto
Notifica immediata al completamento
Più efficiente per job lunghi (30–120 s tipici)

Opzione 2: Polling

Ometti il webhook e usa il requestId restituito per interrogare GET /api/v1/jobs/{requestId} ogni 5–10 s finché lo stato non sia "completed".

Usare quando:

Non puoi esporre un endpoint pubblico di webhook
Test o debug

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

Esempio di richiesta 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
}

Esempio senza 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
}

Esempi di codice completi

Esempi di integrazione pronti all’uso

01Node.js con Webhook (Consigliato)

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