API для разработчиков

Платформа Lipsync API

Создавайте видео с синхронизацией губ через мощный REST API

API-ключи

Управляйте ключами аутентификации

Создать новый API-ключ

Дайте ключу запоминающееся имя (необязательно)

Требуется вход

Войдите, чтобы создавать и управлять API-ключами.

Подходящие для вас цены

Начните с гибких и конкурентных тарифов

Цены API

Оплата по мере использования

Примечание: кредиты API и пользователя независимы и не взаимозаменяемы.

Примечания:

Минимальное списание: 5 секунд за генерацию

480p: 2 кредита/сек

720p: 4 кредита/сек

lipsync-image/video/multi 1080p: 6 кредитов в секунду, минимум 30 кредитов

lipsync-image/video/multi 2k: 7 кредитов в секунду, минимум 35 кредитов

lipsync-image/video/multi 4k: 8 кредитов в секунду, минимум 40 кредитов

talking-avatar: 720p/1080p/2k/4k стоят 4/6/8/9 кредитов за округленную вверх секунду аудио

lipsync-video: Если видео длиннее аудио — обрезается; если аудио длиннее — автоматически удлиняется. Биллинг: при обрезке по длительности аудио, при удлинении — по длительности видео.

lipsync-image-multi: Если order = "meanwhile", берётся максимальная длительность аудио; иначе — сумма "left_audio" + "right_audio".

Пример 1:

3-сек. аудио при 720p = 5 сек × 4 = 20 кредитов

(применяется минимальное списание)

Пример 2:

10-сек. аудио при 480p = 10 × 2 = 20 кредитов

Аутентификация

Защитите свои API-запросы

Всегда передавайте API-ключ в заголовке Authorization:

Authorization: Bearer sk_XXXX_YYYY

Доступные эндпоинты

RESTful эндпоинты

POST/api/v1/lipsync-video

Видео-видео с заменой аудио (сохранение синхронизации губ)

POST/api/v1/lipsync-image

Изображение + аудио → говорящий аватар (один спикер)

POST/api/v1/talking-avatar

Изображение + аудио + prompt -> говорящий аватар с управляемой мимикой и движением

POST/api/v1/lipsync-image-multi

Изображение + два аудио → многоспикерный аватар (беседа/диалог)

GET/api/v1/jobs/{requestId}

Запрос статуса задания и получение результата

Текущий объем API

Входные данные, приватность, покрытие моделей и заметки для продакшена

Входные данные основаны на URL

Публичный API сейчас принимает URL медиа в JSON. Прямая multipart-загрузка файлов и endpoints для загрузки assets пока недоступны. Подписанные или временные URL поддерживаются, если наши worker и провайдер генерации могут получить их во время выполнения задачи.

Вывод API приватный

API-задачи сохраняются с приватной видимостью. Веб-переключатель Public не применяется к API-запросам, и сейчас нет API-параметра для публикации генерации.

Выбор модели

Выберите workflow по endpoint: lipsync-image, lipsync-video или lipsync-image-multi. Используйте talking-avatar для модели изображения с управлением выражением и движением.

Файла OpenAPI пока нет

Эта страница является текущей справкой API. Машиночитаемая спецификация OpenAPI/Swagger пока не опубликована.

Неподдерживаемые настройки

Aspect ratio, guidance scale и audio guidance не доступны как API-параметры для текущих lip-sync endpoints.

Пакетные задачи

Отправляйте один API-запрос на одну генерацию. Для больших продакшен-пакетов сохраняйте входные URL действительными до завершения и свяжитесь с поддержкой перед очень высокой конкуррентностью.

Подробные параметры

Полные спецификации эндпоинтов

Все эндпоинты имеют общую структуру: необязательный webhook и параметры formState, зависящие от модели.

POST /api/v1/lipsync-video

Заменяет аудиодорожку в существующем видео с сохранением синхронизации губ

Параметры верхнего уровня:

webhookнеобязательно

Ваш URL обратного вызова (HTTPS). По завершении отправим результат методом POST.

formStateобязательно

Объект со всеми параметрами генерации (см. ниже).

Параметры formState:

videoобязательно

Публичный URL исходного видео (MP4, MOV и т. д.)

audioобязательно

Публичный URL аудио (MP3, WAV и т. д.)

resolutionобязательно

"360p", "480p", "720p", "1080p", "2k" или "4k"

mask_imageнеобязательно

Публичный URL маски (ограничивает область синхронизации губ)

promptнеобязательно

Текст для стилистических подсказок

seedнеобязательно

Целочисленное зерно для воспроизводимости

Асинхронный рабочий процесс

Выберите, как получать результаты

Все API-вызовы асинхронны. Есть два способа получить результаты:

Для задач 1080p, 2k и 4k ответы webhook и polling возвращают только итоговое видео после upscale.

Вариант 1: Webhook (Рекомендуется)

Укажите URL вебхука в JSON. По завершении отправим результат методом POST.

Webhook URL должны быть публичными HTTPS URL. Если доставка не удалась, мы повторяем попытку до 5 раз с экспоненциальной задержкой.

Преимущества:

Нет необходимости в постоянном опросе
Мгновенное уведомление по завершении
Эффективнее для длительных задач (обычно 30–120 с)

Вариант 2: Опрос (Polling)

Пропустите webhook и используйте возвращённый requestId для опроса GET /api/v1/jobs/{requestId} каждые 5–10 с до статуса "completed".

Используйте, когда:

Невозможно опубликовать публичный endpoint вебхука
Тестирование или отладка

Пример с 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
}

Пример запроса 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
}

Пример без 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
}

Полные примеры кода

Готовые примеры интеграции

01Node.js с Webhook (Рекомендуется)

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