Документация API FreeLipSync

Прежде чем начать

Используйте REST API FreeLipSync для создания видео с синхронизацией губ, говорящих фотографий и музыкальных клипов из ваших аудиофайлов. Нужны зарегистрированный аккаунт, API Key из консоли Agent и кредиты API. Каждый аккаунт, в том числе существующий, однократно получает 30 приветственных кредитов при первой загрузке баланса в консоли Agent или отправке корректного запроса на генерацию. Дополнительные кредиты можно купить; членство не включает регулярное начисление кредитов API. Тариф определяет доступные модели, длительность и общие ограничения заданий.

В этом руководстве используется https://freelipsync.com/api/v1. При тестировании на staging установите для FLS_BASE_URL источник этой среды и создайте свой ключ в той же среде. Доступ к API должен быть включен в этом развертывании. В примерах используются короткий speech.mp3 и односторонний face.jpg.

Откройте справочник OpenAPI для получения машиночитаемых схем запросов и ответов. Предпочитаете агента? См. Руководство по установке MCP.

Аутентификация и ваш первый запрос

Создайте ключ в консоли Agent и скопируйте его из диалога создания. Полный секрет раскрывается один раз. Храните его в переменной среды, а не в коде браузера или общедоступном репозитории. В случае потери отзовите его и создайте новый. Все ключи используют одинаковый баланс счета и лимиты; создание еще одного ключа не увеличивает параллелизм.

export FLS_BASE_URL='https://freelipsync.com'
export FLS_API_KEY='YOUR_API_KEY'
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $FLS_API_KEY" \
  "$FLS_BASE_URL/api/v1/capabilities"

REST принимает ваш API Key. Токен доступа OAuth, выданный для MCP, действителен только для /mcp, но не для REST. Успешный ответ оборачивает свой результат в data и включает request_id; Вместо этого ошибки имеют error и request_id. Идентификаторы представляют собой непрозрачные строки, а суммы кредитов — десятичные строки.

{"data":{"id":"YOUR_ASSET_ID","kind":"image","status":"processing","poll_after_seconds":5,"expires_at":"2026-10-21T00:00:00.000Z"},"request_id":"REQUEST_ID"}

Это иллюстративный ответ актива, а не ответ на запрос возможностей. Прочтите возвращенные возможности, чтобы проверить модели текущей учетной записи, max_audio_seconds, ограничения на загрузку байтов/MIME и ограничения задач перед подготовкой файлов.

Рабочий процесс генерации

1. Получите возможности и загрузите изображение или видео, а также входное аудио.
2. Подтвердите каждую прямую загрузку и дождитесь, пока оба ресурса примут вид ready.
3. Создайте предложение, используя идентификаторы активов и режим генерации. Обзор total_points и expires_at.
4. Отправьте эту цитату с ключом стабильной идемпотентности. Это принимает задание и сохраняет кредиты.
5. Опросите возвращенный идентификатор задания с помощью poll_after_seconds или получите веб-перехватчик.
6. По завершении загрузите с подписанного URL. Невыполненная задача возвращает исходное удержание.

Создание ресурсов и котировок не требует траты кредитов и создания видеозаданий. После того как генерация было принято, его нельзя отменить. Кредиты возвращаются только при ошибке обработки; тайм-аут клиента не является доказательством того, что задача не выполнена.

Загрузите локальные файлы или импортируйте URL-адреса.

Для локального файла POST /assets возвращает подписанный PUT URL. Отправьте необработанные байты файла с возвращенным upload.headers без вашего API Key. Затем вызовите POST /assets/{id}/confirm с помощью {} и опросите GET /assets/{id}. awaiting_upload и processing не готовы; failed — терминал. Используйте рекомендации по опросу сервера.

{
  "kind":"image",
  "source":{
    "type":"upload",
    "filename":"face.jpg",
    "content_type":"image/jpeg",
    "size_bytes":123456
  }
}

size_bytes должно быть фактическим количеством байт, а не номером этого примера. Входы изображения, видео и аудио имеют разные ограничения MIME и размера; используйте GET /capabilities как источник истины. Расширения файлов сами по себе не определяют действительность.

Вы также можете импортировать общедоступный HTTPS URL. Это асинхронно: опрашивайте возвращаемый ресурс до тех пор, пока он не будет готов. Локальный путь file:// URL, частная сеть URL или URL, требующий файлов cookie вашего веб-сайта, не является пригодным для использования источником. Если вы используете подписанный источник URL, дайте ему достаточно времени для получения.

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $FLS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: image-import-UNIQUE-REQUEST-ID' \
  --data '{"kind":"image","source":{"type":"url","url":"https://YOUR-PUBLIC-HOST/face.jpg"}}' \
  "$FLS_BASE_URL/api/v1/assets"

Третий маршрут — POST /asset-upload-sessions с {"kind":"image"}: верните browser_upload_url пользователю, сохраните asset_id и опросите его после загрузки в браузер. Это полезно для клиентов, которые не могут читать локальные файлы. Билеты загрузки и подписанные URL-адреса являются временными учетными данными; не публикуйте их в журналах или стенограммах чатов.

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

Выберите cURL, Python или JavaScript ниже. В каждом примере выполняется один и тот же рабочий процесс загрузки → цитаты → отправки → опроса → загрузки, распечатки цитаты и запроса перед тратой кредитов. Длинные примеры свернуты; кнопка «Копировать» всегда копирует всю программу.

• cURL: Bash, cURL, jq и Python 3 (для UUID). Сохраните как скрипт Bash и запустите его.
• Python: Python 3 и библиотека requests; установите её командой python -m pip install requests.
• JavaScript: Node.js 20+ и только встроенные модули. Сохраните как quickstart.mjs и запустите node quickstart.mjs.

Экспортируйте указанные выше переменные среды и поместите face.jpg и speech.mp3 в рабочий каталог. Запускайте на своем сервере или компьютере разработки, а не на общедоступной веб-странице. Подписанные запросы на загрузку/выгрузку никогда не включают ваш API Key. Скрипты останавливаются при ошибках HTTP; перед повторной попыткой проверьте правила восстановления ниже, а не перезапускайте возможно принятую отправку с новым ключом.

# Requires bash, curl and jq. Set these before running:
# export FLS_API_KEY='YOUR_API_KEY'
# export FLS_BASE_URL='https://freelipsync.com'  # or your staging origin
# Place face.jpg and speech.mp3 in this directory.
set -euo pipefail
: "${FLS_API_KEY:?Set FLS_API_KEY first}"
BASE="${FLS_BASE_URL:-https://freelipsync.com}/api/v1"
RUN="$(python3 -c 'import uuid; print(uuid.uuid4())')"
request() {
  curl --fail-with-body --silent --show-error \
    -H "Authorization: Bearer $FLS_API_KEY" "$@"
}
wait_ready() {
  local id="$1" row status
  for ((i=0; i<120; i++)); do
    row="$(request "$BASE/assets/$id")"

Модели, опции и кредиты

Для всех режимов требуется загруженный входной аудиофайл. Преобразование текста в речь, клонирование и отмена голоса не являются параметрами этого API. Для Image Super/Motion Control требуется Starter или Pro; покупка кредитов сама по себе не позволяет этого сделать. Проверьте возможности доступности модели и ограничения продолжительности, включая исключения, специфичные для модели.

Проверенная длительность аудио округляется вверх до целой секунды; минимальная оплачиваемая длительность — 5 секунд. Расчёт для 5 секунд составляет 5 кредитов для Image Fast, 10 для Image Max и 15 для Image Super или Music Video. Создание расчёта не списывает кредиты. При отправке задания сумма резервируется; при успехе списывается ровно эта сумма, а при сбое обработки она возвращается. После генерации цена не меняется. Купленные кредиты отделены от членства, не сгорают и не возвращаются деньгами.

{
  "mode":"image_super",
  "face_asset_id":"READY_IMAGE_ID",
  "audio_asset_id":"READY_AUDIO_ID",
  "options":{"motion":{"action":"Smile gently","camera":"Static camera"}}
}

Для Music Video используйте mode: "music_video" и настройки MV ниже. version принимает 1.0 или 1.1; ratio принимает 21:9, 16:9, 4:3, 1:1, 3:4 или 9:16; resolution принимает 480p или 720p. По умолчанию: 1.0, 16:9 и 480p. Проверьте возможности активной схемы. Не прикрепляйте параметры движения к другому режиму и не отправляйте внутренние псевдонимы веб-модели.

{
  "mode":"music_video",
  "face_asset_id":"READY_IMAGE_ID",
  "audio_asset_id":"READY_AUDIO_ID",
  "options":{"mv":{"version":"1.0","ratio":"16:9","resolution":"480p","style":{"directorial":"A calm performance","artistic":"Warm evening light"}}}
}

Ссылка на конечную точку

Пути ниже указаны относительно /api/v1. Все деловые звонки требуют аутентификации.

По умолчанию выводится список элементов 20, максимум 50.. Передайте data.next_cursor без изменений, чтобы получить следующую страницу. Для нескольких активных заданий используйте разделенные запятыми ids в одном запросе списка вместо опроса каждого отдельно. Список предназначен для кредитных заданий API/MCP, а не общего списка ваших старых вакансий на веб-сайте.

Идемпотентность, ошибки и ограничения скорости

Используйте новый Idempotency-Key для каждой отдельной операции записи и сохраняйте тот же ключ и полезную нагрузку при повторной попытке этой операции. Ключи представляют собой видимые символы ASCII 8–128. Для нового запроса пользователя требуется новый ключ; повторная попытка не дает. В примерах перед отправкой печатается пара цитата/ключ. В рабочей среде сохраните эту пару перед отправкой и сохраните возвращенный идентификатор задания. Не перезапускайте весь пример после неуверенной отправки: это создаст новый ключ.

Срок действия котировок истекает через 10 минут. Определенный отказ до принятия позволяет исправить запрос или получить новое предложение; неопределенный ответ требует сначала восстановления исходной попытки. Повторное воспроизведение принятого задания возвращает исходное задание без повторного списания. Котировку нельзя потратить дважды под разными ключами.

REST и MCP совместно используют сегмент чтения/вспомогательный блок для каждой учетной записи: Free 30, Starter 30, Pro 60 запросов в минуту. Вспомогательные вызовы включают загрузку, подтверждение и котировки. Уважайте poll_after_seconds и Retry-After, в зависимости от того, какой из них требует более длительного ожидания. Чтение статуса веб-сайта управляется отдельно; частота генерации и производительность видео распределяются между веб-сайтом, REST и MCP. Веб-сайт и API/MCP имеют независимое вознаграждение за незавершенные задачи: Free 1, Starter 3, Pro 10 для каждого пула. REST и MCP совместно используют пул API/MCP, включая все ключи и соединения OAuth; дополнительные полномочия никогда не умножают его. Примеры рабочих процессов см. в разделе зачем использовать API/MCP.

Результаты и дополнительные веб-перехватчики

Задания имеют статус queued, processing, completed или failed. Сохраняйте идентификатор задания, когда время ожидания вашего приложения истекает; ваш тайм-аут не отменяет задачу сервера. В случае успеха используйте output.download_url, пока он действителен. Обновите задание или загрузите конечную точку, чтобы получить обновленную ссылку, пока работа сохраняется; повторные загрузки не тратят кредиты. Срок хранения соответствует обычному сроку хранения вашей учетной записи, а не отдельному периоду использования только API. Результат имеет оригинальное качество, без водяных знаков и может быть использован в коммерческих целях в соответствии с правами на источник и условиями.

Для интеграции с сервером создайте конечную точку веб-перехватчика в консоли Agent → Дополнительно, а затем передайте ее идентификатор как webhook_endpoint_id при отправке. Ваша конечная точка должна сначала ответить на POST endpoint.verification, указав запрос в виде тела ответа в виде обычного текста. В этой настройке используется консоль веб-сайта, а не общедоступный API управления учетными данными.

События Webhook содержат event_id, event_type, occurred_at, generation_id и data. Ссылки для скачивания не включаются в полезные данные веб-перехватчика; запросите работу для получения свежей ссылки. Проверьте FLS-Webhook-Signature на соответствие необработанному телу запроса: HMAC-SHA256 из timestamp + "." + body, используя секрет конечной точки, с отметкой времени из FLS-Webhook-Timestamp; сопоставить подпись v1= в постоянное время и установить недавнюю временную метку для отклонения повторов. Выполните дедупликацию с помощью event_id/FLS-Webhook-Id и незамедлительно верните 2xx. Дублирующиеся уведомления не должны вызывать новое генерация или второе бизнес-действие. Продолжайте опрос как простейшую первую интеграцию.

Нужно работать через помощника вместо HTTP? Настройте MCP с помощью своего агента или вернитесь в консоль Agent.