Руководство по API

Обновлено

Те же замены и апскейлы, что запускает приложение, только из вашего кода. Ключ тратит swapz своей команды и видит её лица, генерации и апскейлы. Больше ему ничего не доступно.

Обзор

Все маршруты находятся под https://faceswap.ing/api/v1. Запросы и успешные ответы передаются в JSON. Любая ошибка приходит документом application/problem+json, подробности в разделе «Ошибки». Ключ передаётся в заголовке x-api-key в каждом запросе. Другого способа аутентификации нет, и сессию открывать не нужно.

Ключи создаются в настройках, в разделе «Разработчикам». Личный ключ начинается с fsper_ и принадлежит тому, кто его создал. Ключ организации начинается с fsorg_, его создаёт владелец, и он принадлежит рабочему пространству, поэтому отозвать его может любой владелец. При создании ключ любого вида привязывается к одной команде: он тратит её swapz и видит её лица, генерации и апскейлы. Когда аккаунт, создавший ключ, удаляют, ключ перестаёт работать.

Полный ключ показывается один раз, при создании. Мы храним только хеш и первые символы, поэтому потерянный ключ не восстановить. Его заменяют новым.

Владелец аккаунта один раз подтверждает в приложении, что ему есть 18 лет и что все, чьи лица он загружает, на это согласились. Пока подтверждения нет, любой запуск получает отказ с declaration_required, каким бы ключом он ни был сделан. Достаточно открыть приложение и начать замену, после этого сразу работают все ключи аккаунта.

Время приходит в формате метки времени Postgres с часовым поясом, например 2026-09-08 09:43:07.375+00. Идентификаторы имеют формат uuid. Работа оплачивается в swapz, а сколько стоит вызов, сказано ниже, в разделе «Цены».

Все маршруты ниже описаны документом OpenAPI 3.1 по адресу https://faceswap.ing/api/v1/openapi.json. Он строится из моделей, по которым маршруты проверяют запросы, поэтому генератор клиента стоит направлять именно на него. Ключ для его чтения не нужен.

Ошибки

Любая ошибка приходит документом application/problem+json (RFC 9457): { "type": "about:blank", "title": "Payment Required", "status": 402, "code": "insufficient_swapz", "detail": "..." }. В code лежит устойчивый код в snake_case, и ветвиться нужно именно по нему. В detail лежит наша английская фраза об этом случае, для человека или для лога: формулировка может измениться, у некоторых отказов её нет, и это никогда не сообщение конвейера обработки. title содержит стандартную фразу статуса, а status повторяет HTTP-статус. Если отказ касается чисел или файла, добавляется shortfall, processing или sourceUrl. Со временем могут появиться и новые поля, поэтому незнакомые просто пропускайте.

401 означает, что с этим ключом запрос выполнить нельзя: code равен api_key_missing, если заголовка x-api-key нет, и api_key_invalid, если ключ не проходит проверку. api_key_invalid получают и ключ, чей аккаунт удалён, и ключ без записанной команды, и отозванный ключ.

403 с code organization_suspended: рабочее пространство, которому принадлежит ключ, приостановлено, и ни один вызов не пройдёт, пока ограничение не снимут.

На id задачи или апскейла, которыми команда ключа не владеет, приходит 404 с code not_found. Чужую запись из другого рабочего пространства нельзя отличить от несуществующей.

429 с code rate_limited и заголовком Retry-After: ключ сделал слишком много запросов в текущем окне. Сколько это, сказано в разделе «Лимиты запросов».

422 с code validation означает, что запрос не совпадает с моделью маршрута: { "type": "validation", "code": "validation", "title": "Validation Error", "status": 422, "on": "body", "property": "/name" }. Поле "on" говорит, какая часть запроса не прошла проверку: body, query или params. Поле "property" содержит JSON pointer на первое поле, которое не совпало со схемой. Что именно не так, тело не объясняет и присланное не повторяет. Сверьте запрос с моделью маршрута в документе OpenAPI. Тело, которое вообще не является JSON, получает 400 с code parse.

Запуск, отклонённый до того, как он что-то создал, приходит со статусом самого отказа, что у замены, что у апскейла, и ничего не удерживается. 400 означает файл или очередь, которые запуск не может взять так, как их просят, и тот же запрос получит тот же отказ. 402 означает insufficient_swapz вместе с shortfall. 403 означает declaration_required или feature_not_allowed: снять такой отказ может только тот, у кого есть доступ к аккаунту. 502 означает launch_failed или unpriced_queue, то есть сбой на нашей стороне. 503 означает moderation_unavailable, media_checking или service_busy, которые проходят сами, и приходит с Retry-After: 30. Отправьте тот же запрос снова через столько секунд.

Запуск замены может получить отказ и на полпути, когда часть задач уже создана. Тогда приходит 200: в "data" лежат задачи, созданные до остановки, они выполняются и оплачиваются как обычно, а в "refusal" лежит документ ошибки с причиной, по которой остальное не запустилось. У запуска, который прошёл целиком, "refusal" равен null. Проверяйте refusal в каждом ответе 200 и не рассчитывайте, что запустилась вся очередь.

code равен declaration_required, если владелец аккаунта не сделал подтверждение, описанное выше. Запрос менять не нужно, достаточно один раз подтвердить.

code равен moderation_unavailable, если указанный файл не удалось проверить: сервис проверки не ответил вовремя или не смог прочитать URL. Ничего не оценено, не удержано и не запущено, а сам файл не получил вердикта. Такой отказ стоит повторить. Отправьте тот же запрос, когда пройдут секунды из Retry-After, и увеличивайте паузу, если отказ повторится.

code равен moderation_refused, если проверка посмотрела файл и отклонила его. Этот файл будет отклонён снова, повторять его не нужно.

code равен media_not_in_library, если указанный URL лежит на нашем файловом хосте и не принадлежит вашей команде: это не файл из библиотеки команды, не outputUrl готовой замены или апскейла команды и не образец, указанный как целевой файл. Образец означает одно из фото и видео, которые сайт предлагает любому аккаунту, чтобы попробовать замену; его можно указать только как целевой файл. Ничего не удержано, и тот же запрос получит тот же отказ. Если файл из библиотеки команды ещё проверяется, приходит media_checking: он проходит сам, отправьте тот же запрос, когда пройдут секунды из Retry-After. Если файл отложен без проверки, приходит media_held, а если его так и не проверили, media_unjudged: загрузите его в приложении заново.

shortfall имеет вид { "available": 12, "needed": 40 } и приходит вместе с detail, где названы оба числа. Очередь оценена, но у команды не хватает swapz. Купите swapz и отправьте тот же запрос снова.

code равен file_over_processing_cap, если одному файлу нужно больше времени обработки, чем разрешено на файл. Вместе с ним приходит processing, { "capMinutes": 90, "estimatedMinutes": 112 }, и ничего не удержано. Тот же запрос получит тот же отказ. Обрежьте файл, отправьте его с меньшим maxMegapixels или отключите какую-нибудь опцию.

code равен gif_unavailable, если целевой файл в формате GIF, а работающее развёртывание GIF не обрабатывает. gif_too_long означает GIF длиннее, чем разрешено GIF такого размера, а gif_too_large означает GIF со слишком большим кадром. Во всех трёх случаях ничего не удержано, и тот же запрос получит тот же отказ.

code равен video_unmeasured, если целевой файл является видео из библиотеки рабочего пространства без записанной длительности, и оценить его нельзя. durationSeconds в запросе её не заменяет. Загрузите файл заново или передайте trim. Ничего не удержано.

code равен insufficient_swapz, если у команды нет суммы, которую стоит очередь. feature_unavailable означает, что запрос просит то, чего нет в работающем развёртывании, feature_not_allowed означает опцию, которой этому рабочему пространству пользоваться нельзя, а face_unavailable означает сохранённое лицо из состава без пригодного фото. Опцию или числа называет detail.

code равен service_busy, если очередь заполнена. Ничего не удержано, и тот же запрос можно отправить снова, когда пройдут секунды из Retry-After. launch_failed означает сбой на нашей стороне. Ничего не удержано, сбой записан в лог.

Файл или очередь, которые нарушают ограничение, получают отказ с кодом этого ограничения, и ничего не удерживается: file_too_large, image_too_large, video_too_large, video_too_long, output_too_large, task_too_large, task_too_long, frame_too_large, requested_size_too_large, enhancer_input_too_large, face_position_out_of_range, missing_face_source, trim_on_image, unsupported_media_type или feature_disabled. quote_refused означает очередь, которая не может запуститься в таком виде по причине, для которой нет более точного кода. Код, которого нет в этом списке, считайте отказом, который повторится.

Задача, которая запустилась и потом завершилась ошибкой, отказом не считается. Это видно в самой задаче. У файла с ошибкой есть errorCode и error, и у задачи, которая завершилась ошибкой или была закрыта, тоже. errorCode является стабильным полем: download_failed, unreadable_input, file_too_large, video_too_long, video_too_large, image_too_large, output_too_large, gif_too_long, gif_too_large, gif_not_animated, task_too_large, task_too_long, task_timeout, not_processed, gpu_failure, no_face_in_source, trim_out_of_range, frame_out_of_range, content_rejected, interrupted, no_output, processing_failed, watermark_unavailable, upload_failed, partial_failure, all_files_failed, cancelled, worker_inactive, scheduling_failed, stalled. error содержит одну постоянную английскую фразу на код, а у кода без своей фразы там "Something went wrong. The error code, if any, says what.". У файла или задачи без ошибки оба поля равны null. До 2026-10-06 в error попадало собственное сообщение конвейера обработки. Теперь это не так, поэтому не сравнивайте его текст.

Отказ в запуске апскейла устроен так же, через статус. Его собственные коды, а также случаи, когда sourceUrl называет фото, перечислены ниже, в разделе «Апскейл».

У запуска с заголовком Idempotency-Key есть два собственных отказа, и оба приходят до того, как что-либо запущено. 409 с code idempotency_key_in_progress и заголовком Retry-After означает, что первый запрос с этим значением заголовка ещё не ответил. Подождите и отправьте тот же запрос снова. 422 с code idempotency_key_reused означает, что это значение уже присылали с другим телом. Для другого запуска нужно новое значение. Значение заголовка, которое не укладывается в 255 печатаемых символов ASCII или пустое, считается обычной ошибкой валидации с "on": "headers".

Отказ в запуске

json
HTTP/1.1 402 Payment Required
content-type: application/problem+json

{
  "type": "about:blank",
  "title": "Payment Required",
  "status": 402,
  "code": "insufficient_swapz",
  "detail": "This queue costs 40 swapz and the team has 12.",
  "shortfall": { "available": 12, "needed": 40 }
}

Лимиты запросов

Лимиты считаются для каждого ключа, и чтение считается отдельно от запусков. Ключ может сделать 120 запросов на чтение за 60 секунд по маршрутам GET и 30 запусков за 60 секунд на POST /faceswap/tasks и POST /upscales вместе. Один запуск замены несёт до 200 файлов, а один апскейл до 50 фото, поэтому лимит на запуски ограничивает запросы, а не файлы.

Окна фиксированные и выровнены по часам: каждые 60 секунд счёт начинается заново. Запрос сверх лимита получает 429 с code rate_limited и заголовком Retry-After, в котором указано, сколько секунд осталось до конца окна. Подождите столько и отправьте тот же запрос снова. Отклонённый запрос ничего не стоит и в счёт не идёт.

Ключ, который исчерпал запуски, может читать, и наоборот. Два ключа никогда не делят счётчик, даже в одной команде. Запрос без ключа или с неверным ключом отклоняется раньше, чем что-либо посчитано.

Чтобы держаться далеко от лимита на чтение, используйте вебхук. Зарегистрируйте его на ключе, и результат задачи придёт к вам сам, когда она завершится, без опроса.

Пагинация

Все списки постраничные, с курсором. Страница содержит data, pageSize и nextCursor, который на последней странице равен null.

Чтобы получить следующую страницу, передайте полученный курсор в параметре cursor. Номеров страниц и общего количества нет. Курсор указывает на последнюю строку, которую вы видели, поэтому строки, записанные во время обхода, не сдвигают следующую страницу.

Строки идут от новых к старым, по времени создания, а затем по id. Поэтому у двух строк, записанных в один момент, порядок всё равно определён.

Лица

Лицо состоит из имени и до 5 фото одного человека и сохраняется в приложении. API лица читает, но не создаёт: лицо собирается из фото, которые уже лежат в библиотеке команды, а маршрута загрузки у ключей нет.

imageUrl содержит первое фото, оно основное. В imageUrls лежат все фото по порядку. Лицо, у которого удалили все фото, приходит с пустым списком и imageUrl, равным null. Для таких случаев и нужен фильтр with_image.

Список лиц

GET /faces

Сохранённые лица команды, от новых к старым. userId указывает, кто сохранил лицо. Владельцем считается команда, поэтому ключ видит все лица своей команды, а не только те, что сохранил его создатель.

Параметры запроса

ИмяТипОбязательныйОписание
cursorstringНетГде закончилась предыдущая страница: значение nextCursor из её ответа. Для первой страницы не передавайте. Значение непрозрачное, и его формат мы можем поменять, поэтому храните его как есть и не разбирайте.
pageSizeintegerНетСколько строк вернуть, от 1 до 100. По умолчанию 20. Если значение не число, используется значение по умолчанию, и запрос не падает.
searchstringНетПоиск по имени лица без учёта регистра, в любом месте имени. Пробелы по краям обрезаются, длина до 255 символов.
status"with_image"НетЕдинственный фильтр списка. Передайте with_image, чтобы получить только лица, у которых осталось хотя бы одно фото. Любое другое значение игнорируется, ошибки не будет.

Запрос

curl "https://faceswap.ing/api/v1/faces?pageSize=2&search=ada" \
  -H "x-api-key: fsper_YOUR_KEY"
const response = await fetch("https://faceswap.ing/api/v1/faces?pageSize=2&search=ada", {
  headers: { "x-api-key": "fsper_YOUR_KEY" },
});

console.log(await response.json());
import requests

response = requests.get(
    "https://faceswap.ing/api/v1/faces?pageSize=2&search=ada",
    headers={"x-api-key": "fsper_YOUR_KEY"},
)

print(response.json())

Ответ

json
{
  "data": [
    {
      "createdAt": "2026-09-08 09:43:07.379+00",
      "id": "01a08066-5d73-7000-add1-fb5a632aede1",
      "imageUrl": "https://cdn.faceswap.ing/permanent/faces/ada-1.jpg",
      "imageUrls": [
        "https://cdn.faceswap.ing/permanent/faces/ada-1.jpg",
        "https://cdn.faceswap.ing/permanent/faces/ada-2.jpg"
      ],
      "name": "Ada",
      "updatedAt": "2026-09-08 09:43:07.379+00",
      "userId": "01a08066-5d66-7000-9a86-605f95602406"
    }
  ],
  "nextCursor": null,
  "pageSize": 2
}

Замены

Один запуск может превратиться в несколько задач. Очередь делится по тому, что сервис принимает на одну задачу, то есть по дорожке для синхронизации губ и размеру кадра, а затем по бюджету обработки. Длинная очередь возвращается несколькими задачами, которые выполняются параллельно. Читайте весь массив data, а не только первый элемент.

targetFiles[].url указывает фото или видео, на которое ставится лицо. Это единственное обязательное поле файла. targetFiles[].facePosition выбирает, какое лицо в целевом файле заменить, считая с нуля слева направо. Без него заменяется первое лицо. targetFiles[].faceSelection принимает reference, one или many: reference заменяет лицо в позиции facePosition, one заменяет первое лицо слева, many заменяет все лица в файле. По умолчанию reference. targetFiles[].referenceFrameNumber указывает кадр, по которому определены эти позиции.

targetFiles[].swaps ставит в один целевой файл нескольких людей, каждого отдельным проходом, до 4 на файл. Каждый элемент принимает faceId из списка лиц, facePosition с лицом, которое он заменяет, и необязательный faceSelection. Два элемента не могут занять одну позицию. many работает, только если в составе один человек. Файл со swaps не должен указывать свой facePosition.

targetFiles[].trim принимает startSeconds и endSeconds и обрабатывает только этот отрезок. Сильнее всего на цену видео влияет именно он. Конец отрезка должен быть позже начала, и обрезать можно только видео. targetFiles[].lipSync принимает audioUrl и необязательный weight от 0 до 1 и двигает губы по этой дорожке. Синхронизация губ работает только на видео, а очередь с двумя дорожками становится двумя задачами.

targetFiles[].maxMegapixels обрабатывает файл с разрешением не выше заданного числа мегапикселей, один раз уменьшая его перед заменой. Благодаря этому загрузка в 4K оплачивается по тарифу 1080p. Предел 8.9 МП. targetFiles[].durationSeconds передаёт длительность видео, как вы её измерили, и используется, только если проба не смогла её определить. targetFiles[].thumbnailUrl задаёт кадр для превью файла и никогда не обрабатывается.

processors.ageModifier принимает ageShift, целое число от -100 до 100. У этой опции одной нет значения по умолчанию, потому что нулевой сдвиг возраст не меняет. processors.expressionRestorer принимает strength от 0 до 1 и переносит на новое лицо мимику из целевого файла. processors.backgroundRemover принимает fillColor из четырёх каналов от 0 до 255: красный, зелёный, синий и альфа. По умолчанию фон прозрачный, а прозрачность сохранится, только если целевой файл в PNG.

processors.frameEnhancer принимает scale, 2 или 4, и blend от 0 до 1. processors.frameColorizer принимает blend от 0 до 1. processors.faceEditor меняет само лицо по четырнадцати осям, каждая от -1 до 1, а 0 оставляет ось как есть: eyebrowDirection, eyeGazeHorizontal, eyeGazeVertical, eyeOpenRatio, headPitch, headRoll, headYaw, lipOpenRatio, mouthGrim, mouthPositionHorizontal, mouthPositionVertical, mouthPout, mouthPurse и mouthSmile. processors.watermark принимает boolean.

Все процессоры, кроме watermark, передаются объектами, и процессор включается самим присутствием. Пустой объект запускает его с настройками сервиса по умолчанию. Для простой замены не передавайте поле processors совсем.

Задача сначала стоит в статусе queued, затем переходит в processing, а затем в один из четырёх конечных статусов. completed означает, что готовы все файлы, partially_completed означает, что готова только часть, а ещё есть failed и cancelled. cancelling конечным не является: отмена принята, и обработчик доделывает текущий файл. Статусы меняются по таблице переходов, поэтому событие, пришедшее поздно или дважды, не откатит задачу назад, а конечный статус уже не меняется.

У каждого файла задачи свой статус: pending, processing, completed, failed, insufficient_coins для файла, за который никто не смог заплатить, и system_cancelled, system_maintenance или user_cancelled для трёх видов отмены. cost показывает, сколько swapz списано за эту генерацию, и заполняется, когда файл готов.

За файл с ошибкой swapz возвращаются. То, что удержано за задачу, один раз сверяется с фактической стоимостью файлов, и разница возвращается на постоянный баланс команды.

Запустить замену

POST /faceswap/tasks

Оценивает очередь, удерживает swapz и отправляет её в работу. В ответе приходят созданные задачи, у каждой уже есть её файлы. Запуск, отклонённый до создания задач, получает статус отказа и документ ошибки, а отклонённый на полпути получает 200, где отказ лежит рядом с созданными задачами. Подробности в разделе «Ошибки». Отправляйте Idempotency-Key с каждым запуском, чтобы повтор после потерянного ответа не запустил замену дважды.

Заголовки

ИмяТипОбязательныйОписание
Idempotency-KeystringНетВаше значение для этого запуска, например UUID. Оно без изменений отправляется с каждым повтором запуска. В течение 24 часов после первого запроса повтор с тем же значением и тем же телом от того же API-ключа получает ответ первого запуска с заголовком Idempotent-Replayed: true и ничего не запускает и не удерживает. Сохраняется только запуск, который создал задачи. Запуск, отклонённый до удержания, освобождает значение, и тот же запрос с ним выполнится, когда его отправят снова. От 1 до 255 печатаемых символов ASCII.

Тело

ИмяТипОбязательныйОписание
faceEnhancerbooleanНетВключает или выключает улучшение лица. Сервис включает его по умолчанию, поэтому для выключения передайте false. Если поле не передано, улучшение остаётся включённым.
faceIdstringНетСохранённое лицо, из которого взяты фото. Оно записывается в задачу, чтобы генерацию можно было связать с библиотекой. Фото по нему не загружаются, для этого есть faceImageUrl.
faceImageUrlstring (url)ДаЛицо, которое нужно поставить. Публичный HTTPS URL фото одного человека. Фото, которое хостите вы, загружается и проверяется при запуске замены; URL на нашем файловом хосте должен указывать на файл вашей команды.
faceImageUrlsstring[] (url)НетДополнительные фото того же человека. Их эмбеддинги усредняются в одну внешность. До 4 помимо faceImageUrl, всего 5. Несколько ракурсов одного человека улучшают результат дешевле всего остального.
metadataobjectНетВаш собственный набор ключей и значений. Он хранится в задаче и передаётся сервису обработки как есть. Мы его не читаем, и в ответе на чтение задачи его нет.
preset"balanced" | "best" | "fast"НетПрофиль качества и цены: balanced, best или fast. По умолчанию balanced. best добавляет к базовой цене 60%, fast стоит как balanced. Полный прайс находится на https://faceswap.ing/ru/pricing.
processorsobjectНетОпции, которые выполняются вместе с заменой, в виде объектов. Присутствие опции включает её, пустой объект включает её с настройками сервиса по умолчанию, и каждая оплачивается сверх базовой цены. Поля каждой опции описаны выше.
targetFilesobject[]ДаФото и видео, на которые ставится лицо, от 1 до 200. Каждому элементу нужен url, остальные поля файла описаны выше.

Запрос

curl -X POST "https://faceswap.ing/api/v1/faceswap/tasks" \
  -H "x-api-key: fsper_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "faceImageUrl": "https://cdn.faceswap.ing/permanent/faces/ada-1.jpg",
    "preset": "balanced",
    "processors": {
      "faceEditor": {
        "mouthSmile": 0.2
      }
    },
    "targetFiles": [
      {
        "url": "https://cdn.faceswap.ing/permanent/uploads/scene.jpg"
      }
    ]
  }'
const response = await fetch("https://faceswap.ing/api/v1/faceswap/tasks", {
  method: "POST",
  headers: {
    "x-api-key": "fsper_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "faceImageUrl": "https://cdn.faceswap.ing/permanent/faces/ada-1.jpg",
    "preset": "balanced",
    "processors": {
      "faceEditor": {
        "mouthSmile": 0.2
      }
    },
    "targetFiles": [
      {
        "url": "https://cdn.faceswap.ing/permanent/uploads/scene.jpg"
      }
    ]
  }),
});

console.log(await response.json());
import requests

response = requests.post(
    "https://faceswap.ing/api/v1/faceswap/tasks",
    headers={"x-api-key": "fsper_YOUR_KEY"},
    json={
        "faceImageUrl": "https://cdn.faceswap.ing/permanent/faces/ada-1.jpg",
        "preset": "balanced",
        "processors": {
            "faceEditor": {
                "mouthSmile": 0.2,
            },
        },
        "targetFiles": [
            {
                "url": "https://cdn.faceswap.ing/permanent/uploads/scene.jpg",
            },
        ],
    },
)

print(response.json())

Ответ

json
{
  "data": [
    {
      "taskId": "01a08066-5d70-7000-a3db-ff3ef6b651ca",
      "userId": "01a08066-5d66-7000-9a86-605f95602406",
      "status": "queued",
      "queuePosition": 2,
      "faceImageUrl": "https://cdn.faceswap.ing/permanent/faces/ada-1.jpg",
      "faceId": null,
      "progress": { "current": 0, "total": 1, "percentage": 0, "stage": "queued" },
      "startedAt": null,
      "completedAt": null,
      "createdAt": "2026-09-08 09:43:07.375+00",
      "updatedAt": "2026-09-08 09:43:07.375+00",
      "purgedAt": null,
      "error": null,
      "errorCode": null,
      "files": [
        {
          "id": "01a08066-5d70-7fff-9e92-493cc98e0da6",
          "status": "pending",
          "fileType": "image",
          "targetUrl": "https://cdn.faceswap.ing/permanent/uploads/scene.jpg",
          "targetThumbnailUrl": null,
          "outputUrl": null,
          "outputThumbnailUrl": null,
          "lipSyncAudioUrl": null,
          "progress": { "current": 0, "total": 100, "percentage": 0, "stage": "pending" },
          "startedAt": null,
          "completedAt": null,
          "createdAt": "2026-09-08 09:43:07.377+00",
          "updatedAt": "2026-09-08 09:43:07.377+00",
          "processingTime": null,
          "cost": null,
          "error": null,
          "errorCode": null
        }
      ]
    }
  ],
  "refusal": null
}

Список замен

GET /faceswap/tasks

Замены команды, от новых к старым, каждая со своими файлами. Прогресс выполняющейся задачи обновляется перед чтением страницы, поэтому проценты приходят актуальными. Строка содержит все поля, которые возвращает запуск. Пример ниже сокращён до полей, которые читает клиент при опросе.

Параметры запроса

ИмяТипОбязательныйОписание
cursorstringНетГде закончилась предыдущая страница: значение nextCursor из её ответа. Для первой страницы не передавайте. Значение непрозрачное, и его формат мы можем поменять, поэтому храните его как есть и не разбирайте.
pageSizeintegerНетСколько строк вернуть, от 1 до 100. По умолчанию 10. Если значение не число, используется значение по умолчанию, и запрос не падает.
statusстатус задачи, один или несколькоНетОставляет только задачи в этих статусах. Повторите параметр или перечислите значения через запятую. Неизвестные значения отбрасываются, а если допустимых не осталось, возвращается всё.

Запрос

curl "https://faceswap.ing/api/v1/faceswap/tasks?pageSize=10&status=completed" \
  -H "x-api-key: fsper_YOUR_KEY"
const response = await fetch("https://faceswap.ing/api/v1/faceswap/tasks?pageSize=10&status=completed", {
  headers: { "x-api-key": "fsper_YOUR_KEY" },
});

console.log(await response.json());
import requests

response = requests.get(
    "https://faceswap.ing/api/v1/faceswap/tasks?pageSize=10&status=completed",
    headers={"x-api-key": "fsper_YOUR_KEY"},
)

print(response.json())

Ответ

json
{
  "data": [
    {
      "taskId": "01a08066-5d70-7000-a3db-ff3ef6b651ca",
      "status": "completed",
      "progress": { "current": 1, "total": 1, "percentage": 100, "stage": "completed" },
      "files": [
        {
          "id": "01a08066-5d70-7fff-9e92-493cc98e0da6",
          "status": "completed",
          "outputUrl": "https://cdn.faceswap.ing/permanent/generations/scene-swapped.jpg",
          "cost": 5
        }
      ]
    }
  ],
  "nextCursor": "MjAyNi0wOS0wOCAwOTo0MzowNy4zNzkrMDB8MDFhMDgwNjY",
  "pageSize": 10
}

Прочитать одну замену

GET /faceswap/tasks/:taskId

Одна задача и её файлы, для опроса. Маршрут читает сохранённую строку и ничего не вызывает по пути, поэтому спрашивать его часто дёшево. Он возвращает одну задачу, а не страницу. На задачу, которой команда ключа не владеет, приходит 404. Пример ниже сокращён так же, как пример списка.

Параметры пути

ИмяТипОбязательныйОписание
taskIdstring (uuid)Даid задачи, которой владеет команда ключа, из ответа на запуск или из списка.

Запрос

curl "https://faceswap.ing/api/v1/faceswap/tasks/01a08066-5d70-7000-a3db-ff3ef6b651ca" \
  -H "x-api-key: fsper_YOUR_KEY"
const response = await fetch("https://faceswap.ing/api/v1/faceswap/tasks/01a08066-5d70-7000-a3db-ff3ef6b651ca", {
  headers: { "x-api-key": "fsper_YOUR_KEY" },
});

console.log(await response.json());
import requests

response = requests.get(
    "https://faceswap.ing/api/v1/faceswap/tasks/01a08066-5d70-7000-a3db-ff3ef6b651ca",
    headers={"x-api-key": "fsper_YOUR_KEY"},
)

print(response.json())

Ответ

json
{
  "taskId": "01a08066-5d70-7000-a3db-ff3ef6b651ca",
  "status": "completed",
  "progress": { "current": 1, "total": 1, "percentage": 100, "stage": "completed" },
  "startedAt": "2026-09-08 09:43:07.375+00",
  "completedAt": "2026-09-08 09:45:11.002+00",
  "purgedAt": null,
  "files": [
    {
      "id": "01a08066-5d70-7fff-9e92-493cc98e0da6",
      "status": "completed",
      "outputUrl": "https://cdn.faceswap.ing/permanent/generations/scene-swapped.jpg",
      "processingTime": 3,
      "cost": 5
    }
  ]
}

Апскейл

Апскейл увеличивает фото до 2K, 4K или 8K и восстанавливает детали, которых не хватает маленькому или мягкому снимку. Пропорции каждого фото сохраняются. Один запуск принимает от 1 до 50 фото, у каждого свой размер, и всегда даёт один апскейл: в отличие от замены, он не делится. У апскейла свои маршруты и своё событие вебхука, поэтому для клиента, который им не пользуется, в заменах ничего не меняется.

files[].sourceUrl указывает фото, и это может быть одно из трёх. Публичный HTTPS URL фото, которое хостите вы, проверяется при запуске, как файлы замены. outputUrl готовой замены, сделанной командой этого ключа, берётся как есть, без новой проверки: он сделан из файлов, которые проверку уже прошли. Фото из библиотеки команды, загруженное через приложение, берётся после того, как прошло собственную проверку, а до этого получает отказ media_checking. Любой другой URL нашего хранилища отклоняется с media_not_in_library, чей бы он ни был.

files[].tier принимает 2k, 4k или 8k. files[].outputFormat принимает jpg, png или webp, а без него результат пишется в jpg. Одно фото можно запросить в одном запуске в двух размерах, но не дважды в одном. Фото может быть в формате JPG, PNG, WEBP, BMP, HEIC или HEIF, весить до 50 МБ и иметь до 50 МП. Видео, GIF и замена, сделанная из них, отклоняются с unsupported_media, а фото больше 50 МП отклоняется с image_too_large.

Размер задаёт итог, а не множитель. Результат получается самым большим, какой помещается в границы размера из таблицы ниже, и его длинная сторона не бывает больше 8192 пикселей. Если размер не удлиняет каждую сторону хотя бы в 1,25 раза, запуск отклоняется с tier_not_larger ещё до удержания: фото, которое уже почти 4K, апскейлом до 4K не продаётся. Если размер фото нам неизвестен, сервис измеряет его при запуске и отклоняет с теми же кодами, а удержанное возвращается.

Каждое фото стоит цену своего размера из таблицы ниже, или меньше, если у команды свой тариф: он применяется к каждому фото и округляется вверх до целого swapz. Итог удерживается при запуске апскейла. Когда он завершается, готовые фото сохраняют свою цену, а остальное возвращается, так что фото с ошибкой ничего не стоит.

Апскейл проходит те же статусы, что задача замены: queued, processing, затем completed, partially_completed, failed или cancelled. Каждое фото проходит те же статусы, что файл замены. У готового фото результат лежит в outputUrl, а размер в outputWidth и outputHeight. outputUrl равен null, пока результат не скопирован в наше хранилище.

У фото с ошибкой есть errorCode и error, как у файла замены с ошибкой, с кодами из раздела «Ошибки» и одним своим: tier_not_larger, если фото оказалось слишком большим, чтобы выбранный размер его увеличил.

Результаты удаляются через 30 дней после завершения апскейла, как и у замены, а deletedAt показывает, когда это случилось. Это верно и для результата, который потом стал входом для чего-то ещё. Фото, из которых сделан апскейл, вместе с ним не удаляются.

Отказ в запуске апскейла приходит со статусом самого отказа, никогда не с 200, и ничего не удерживает. Тело является документом ошибки, как описано в разделе «Ошибки». Ветвитесь по code. В detail лежит наша английская фраза, и формулировка может измениться.

sourceUrl называет фото всякий раз, когда мы отказываем ему до отправки апскейла: tier_not_larger, image_too_large и unsupported_media, если нам известны размер или тип, moderation_refused, moderation_unavailable, media_checking, а также media_not_in_library или другой код библиотеки. Если несколько фото получили отказ по одной причине, назван первый. Фото, размера которого у нас нет, измеряет сервис апскейла при создании задачи, и если он отказывает там, с tier_not_larger или image_too_large, отказ получает весь запуск без sourceUrl: сервис не сообщает, какое это фото. insufficient_swapz приходит с shortfall, а 502 и service_busy фото не называют.

400 означает фото, которое апскейл не может взять так, как его просят: tier_not_larger, image_too_large, unsupported_media, moderation_refused, media_not_in_library, другой код библиотеки или другое ограничение сервиса. Тот же запрос получит тот же отказ. 402 означает insufficient_swapz вместе с shortfall. 403 означает declaration_required или feature_not_allowed. 502 означает сбой на нашей стороне: launch_failed или unpriced_queue, если фото не удалось оценить.

503 проходит сам: moderation_unavailable, если ваше фото сейчас не удалось проверить, media_checking, если фото из библиотеки ещё проверяется, и service_busy, если очередь заполнена. 503 приходит с Retry-After: 30. Отправьте тот же запрос снова через столько секунд. Idempotency-Key работает так же, как при запуске замены, с теми же 409 и 422.

Когда апскейл завершается, вебхук ключа получает upscale.completed, подробности в разделе «Вебхуки».

РазмерМП, не большеКороткая сторона, не большеSwapz за фотоUSD
2k4,21440 px8$0.08
4k8,32160 px15$0.15
8k33,24320 px30$0.30

Запустить апскейл

POST /upscales

Находит и проверяет каждое фото, оценивает каждое по тарифу команды, удерживает итог и отправляет в работу. В ответе приходит созданный апскейл в той же форме, что у GET /upscales/:upscaleId, все фото в статусе pending, а cost равен цене фото. Отказ приходит HTTP-ошибкой, как описано выше.

Заголовки

ИмяТипОбязательныйОписание
Idempotency-KeystringНетВаше значение для этого запуска, например UUID. Оно без изменений отправляется с каждым повтором запуска. В течение 24 часов после первого запроса повтор с тем же значением и тем же телом от того же API-ключа получает ответ первого запуска с заголовком Idempotent-Replayed: true и ничего не запускает и не удерживает. Сохраняется только запуск, который создал апскейл, а отклонённый освобождает значение. От 1 до 255 печатаемых символов ASCII.

Тело

ИмяТипОбязательныйОписание
filesobject[]ДаФото, от 1 до 50. Каждое принимает sourceUrl и tier и необязательный outputFormat, как описано выше.
metadataobjectНетВаши собственные ключи и значения. Хранятся в апскейле как есть и возвращаются с ним при каждом чтении и в его событии вебхука. Мы их не читаем.

Запрос

curl -X POST "https://faceswap.ing/api/v1/upscales" \
  -H "x-api-key: fsper_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "sourceUrl": "https://cdn.faceswap.ing/permanent/generations/scene-swapped.jpg",
        "tier": "4k"
      },
      {
        "outputFormat": "png",
        "sourceUrl": "https://example.com/photos/portrait.jpg",
        "tier": "2k"
      }
    ],
    "metadata": {
      "order": "A-1042"
    }
  }'
const response = await fetch("https://faceswap.ing/api/v1/upscales", {
  method: "POST",
  headers: {
    "x-api-key": "fsper_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "files": [
      {
        "sourceUrl": "https://cdn.faceswap.ing/permanent/generations/scene-swapped.jpg",
        "tier": "4k"
      },
      {
        "outputFormat": "png",
        "sourceUrl": "https://example.com/photos/portrait.jpg",
        "tier": "2k"
      }
    ],
    "metadata": {
      "order": "A-1042"
    }
  }),
});

console.log(await response.json());
import requests

response = requests.post(
    "https://faceswap.ing/api/v1/upscales",
    headers={"x-api-key": "fsper_YOUR_KEY"},
    json={
        "files": [
            {
                "sourceUrl": "https://cdn.faceswap.ing/permanent/generations/scene-swapped.jpg",
                "tier": "4k",
            },
            {
                "outputFormat": "png",
                "sourceUrl": "https://example.com/photos/portrait.jpg",
                "tier": "2k",
            },
        ],
        "metadata": {
            "order": "A-1042",
        },
    },
)

print(response.json())

Ответ

json
{
  "completedAt": null,
  "createdAt": "2026-11-10 09:43:07.375+00",
  "deletedAt": null,
  "errorCode": null,
  "files": [
    {
      "cost": 15,
      "errorCode": null,
      "id": "01a6c2f4-3b12-7000-8d55-1c9e0f4a7b21",
      "outputFormat": "jpg",
      "outputHeight": 2160,
      "outputUrl": null,
      "outputWidth": 2880,
      "sourceUrl": "https://cdn.faceswap.ing/permanent/generations/scene-swapped.jpg",
      "status": "pending",
      "tier": "4k"
    },
    {
      "cost": 8,
      "errorCode": null,
      "id": "01a6c2f4-3b12-7001-a0e3-5f7d2c8b9e44",
      "outputFormat": "png",
      "outputHeight": null,
      "outputUrl": null,
      "outputWidth": null,
      "sourceUrl": "https://example.com/photos/portrait.jpg",
      "status": "pending",
      "tier": "2k"
    }
  ],
  "id": "01a6c2f4-3b10-7000-9c41-7d2e8a5b6f03",
  "metadata": { "order": "A-1042" },
  "reservedSwapz": 23,
  "settledAt": null,
  "status": "queued"
}

Список апскейлов

GET /upscales

Апскейлы команды, от новых к старым, каждый со своими фото. Апскейл, результаты которого удалены, всё равно есть в списке, с заполненным deletedAt. Пример ниже сокращён до полей, которые читает клиент при опросе.

Параметры запроса

ИмяТипОбязательныйОписание
cursorstringНетГде закончилась предыдущая страница: значение nextCursor из её ответа. Для первой страницы не передавайте. Значение непрозрачное, и его формат мы можем поменять, поэтому храните его как есть и не разбирайте.
pageSizeintegerНетСколько строк вернуть, от 1 до 50. По умолчанию 10. Если значение не число, используется значение по умолчанию, и запрос не падает.

Запрос

curl "https://faceswap.ing/api/v1/upscales?pageSize=10" \
  -H "x-api-key: fsper_YOUR_KEY"
const response = await fetch("https://faceswap.ing/api/v1/upscales?pageSize=10", {
  headers: { "x-api-key": "fsper_YOUR_KEY" },
});

console.log(await response.json());
import requests

response = requests.get(
    "https://faceswap.ing/api/v1/upscales?pageSize=10",
    headers={"x-api-key": "fsper_YOUR_KEY"},
)

print(response.json())

Ответ

json
{
  "data": [
    {
      "id": "01a6c2f4-3b10-7000-9c41-7d2e8a5b6f03",
      "status": "completed",
      "files": [
        {
          "id": "01a6c2f4-3b12-7000-8d55-1c9e0f4a7b21",
          "status": "completed",
          "tier": "4k",
          "outputUrl": "https://cdn.faceswap.ing/permanent/upscales/scene-swapped-4k.jpg",
          "cost": 15
        }
      ]
    }
  ],
  "nextCursor": null,
  "pageSize": 10
}

Прочитать один апскейл

GET /upscales/:upscaleId

Один апскейл и его фото, для опроса, пока статус не станет конечным. На апскейл, которым команда ключа не владеет, приходит 404. Пример ниже сокращён так же, как пример списка.

Параметры пути

ИмяТипОбязательныйОписание
upscaleIdstring (uuid)Даid апскейла, которым владеет команда ключа, из ответа на запуск или из списка.

Запрос

curl "https://faceswap.ing/api/v1/upscales/01a6c2f4-3b10-7000-9c41-7d2e8a5b6f03" \
  -H "x-api-key: fsper_YOUR_KEY"
const response = await fetch("https://faceswap.ing/api/v1/upscales/01a6c2f4-3b10-7000-9c41-7d2e8a5b6f03", {
  headers: { "x-api-key": "fsper_YOUR_KEY" },
});

console.log(await response.json());
import requests

response = requests.get(
    "https://faceswap.ing/api/v1/upscales/01a6c2f4-3b10-7000-9c41-7d2e8a5b6f03",
    headers={"x-api-key": "fsper_YOUR_KEY"},
)

print(response.json())

Ответ

json
{
  "id": "01a6c2f4-3b10-7000-9c41-7d2e8a5b6f03",
  "status": "completed",
  "completedAt": "2026-11-10 09:43:41.902+00",
  "settledAt": "2026-11-10 09:43:42.118+00",
  "deletedAt": null,
  "reservedSwapz": 15,
  "files": [
    {
      "id": "01a6c2f4-3b12-7000-8d55-1c9e0f4a7b21",
      "status": "completed",
      "tier": "4k",
      "outputUrl": "https://cdn.faceswap.ing/permanent/upscales/scene-swapped-4k.jpg",
      "outputWidth": 2880,
      "outputHeight": 2160,
      "cost": 15
    }
  ]
}

Вебхуки

У ключа может быть один вебхук: HTTPS URL, на который мы отправляем POST, когда завершается задача или апскейл, запущенные этим ключом. Зарегистрируйте его в настройках, в разделе «Разработчикам», в меню ключа. URL принадлежит ключу, и задаёт его человек, вошедший в аккаунт. Запуск указать его не может, и поля для обратного вызова у задачи нет.

URL должен быть HTTPS на стандартном порту, без имени пользователя и пароля, и вести на адрес, доступный из интернета. Это проверяется при сохранении и ещё раз перед каждой доставкой. Редиректы мы не выполняем, поэтому отвечайте на том URL, который зарегистрировали.

При сохранении URL один раз показывается секрет подписи, который начинается с whsec_. Он хранится в зашифрованном виде и больше не показывается. Если сохранить URL ещё раз, появится новый секрет, а старый сразу перестанет подписывать. Так секрет и меняют.

Событие отправляется, когда задача достигла конечного статуса и её списание окончательно. type принимает одно из значений task.completed, task.partially_completed, task.failed или task.cancelled. Расчёт по задаче проходит один раз, поэтому событие тоже одно. Апскейл по завершении отправляет upscale.completed, чем бы он ни закончился: как именно, показывает data.upscale.status. Кнопка «Отправить тестовое событие» в настройках отправляет webhook.test, подписанное так же.

Тело имеет вид { id, type, timestamp, data }. timestamp показывает, когда событие поставлено в очередь, в формате ISO 8601, например 2026-09-08T09:45:11.120Z, а не в формате меток Postgres, которыми отвечают маршруты.

data.task в точности совпадает с ответом GET /faceswap/tasks/:taskId для этой задачи, так что форма ответа одна. Это касается и ошибок: errorCode у задачи и у каждого файла с ошибкой остаётся кодом для ветвления, а error содержит нашу постоянную английскую фразу для него, а не сообщение конвейера обработки. data.chargedSwapz показывает итоговую стоимость задачи. Готовые файлы сохраняют свою цену, за остальные swapz возвращаются, и их cost равен 0. Для апскейла data.upscale совпадает с ответом GET /upscales/:upscaleId, а data.chargedSwapz читается так же.

Событие ждёт, пока результат каждого готового файла скопируется в наше хранилище, поэтому outputUrl к моменту доставки уже заполнен. Ждём мы не дольше 30 минут. После этого событие уходит всё равно, недостающий outputUrl равен null, и его нужно прочитать из задачи позже.

Доставки устроены по стандарту Standard Webhooks (standardwebhooks.com) и несут три его заголовка. webhook-id содержит id события. Он совпадает с id в теле и не меняется при повторах, поэтому дубликаты отсеивайте по нему. webhook-timestamp содержит момент подписи попытки в секундах от начала эпохи Unix. webhook-signature содержит v1, запятую и HMAC-SHA256 в base64 от id, точки, метки времени, точки и сырого тела запроса. Ключом HMAC служат байты, которые кодирует ваш секрет: base64 после whsec_, раскодированный, а не сам текст секрета. В заголовке может быть несколько подписей через пробел, и доставка подлинная, если совпала хотя бы одна.

Доставку проверит любая библиотека Standard Webhooks с секретом в том виде, в каком он показан: например, standardwebhooks для JavaScript и Python или библиотеки Svix, которые следуют той же схеме. Чтобы проверить вручную, как в примерах ниже, вычислите этот HMAC по полученным байтам до разбора JSON и сравните его за постоянное время. Отклоняйте доставку, если её метка времени расходится с вашими часами больше чем на 5 минут. Метка входит в подписанные данные, поэтому повторно отправленный запрос не может нести свежую.

Ответьте любым статусом 2xx в течение 10 секунд. Всё остальное считается неудачей, включая 3xx и отсутствие ответа вовремя. Тело ответа не читается. Неудачная доставка повторяется через 1 мин, 5 мин, 30 мин, 2 ч, 8 ч, всего 6 попыток. Очередь разбирается каждые тридцать минут, поэтому паузы указаны как минимальные. Доставка гарантируется как минимум один раз: если ответ пришёл сразу после тайм-аута, за ним последует повтор с тем же id.

После 10 неудачных попыток подряд эндпоинт отключается. Настройки показывают это на ключе и предлагают включить его снова. Пока он выключен, в очередь ничего не ставится, и события за это время потом не отправляются. Такие задачи прочитайте через API. Одна успешная доставка обнуляет счётчик.

Ключу, который сам не смог бы сделать запрос, ничего не отправляется. Это ключ отключённый, истёкший или отозванный, а также ключ приостановленного рабочего пространства. При отзыве ключа удаляется и его вебхук.

Событие

json
POST /your/webhook
webhook-id: 01a10c1e-7d2a-7000-8f4e-2b9f6f0c1a55
webhook-timestamp: 1788860711
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

{
  "id": "01a10c1e-7d2a-7000-8f4e-2b9f6f0c1a55",
  "type": "task.completed",
  "timestamp": "2026-09-08T09:45:11.120Z",
  "data": {
    "chargedSwapz": 5,
    "task": {
      "taskId": "01a08066-5d70-7000-a3db-ff3ef6b651ca",
      "status": "completed",
      "files": [
        {
          "id": "01a08066-5d70-7fff-9e92-493cc98e0da6",
          "status": "completed",
          "outputUrl": "https://cdn.faceswap.ing/permanent/generations/scene-swapped.jpg",
          "cost": 5
        }
      ]
    }
  }
}

Файл с ошибкой в событии

json
{
  "id": "01a10c1e-7d2a-7000-8f4e-2b9f6f0c1a56",
  "type": "task.failed",
  "timestamp": "2026-09-08T09:45:11.120Z",
  "data": {
    "chargedSwapz": 0,
    "task": {
      "taskId": "01a08066-5d70-7000-a3db-ff3ef6b651ca",
      "status": "failed",
      "errorCode": "all_files_failed",
      "error": "Every file in this task failed.",
      "files": [
        {
          "id": "01a08066-5d70-7fff-9e92-493cc98e0da6",
          "status": "failed",
          "outputUrl": null,
          "cost": 0,
          "errorCode": "no_face_in_source",
          "error": "No face was found in the face image."
        }
      ]
    }
  }
}

Событие апскейла

json
{
  "id": "01a6c2f4-4e01-7000-b7a2-93f0d6c1e855",
  "type": "upscale.completed",
  "timestamp": "2026-11-10T09:43:42.130Z",
  "data": {
    "chargedSwapz": 15,
    "upscale": {
      "id": "01a6c2f4-3b10-7000-9c41-7d2e8a5b6f03",
      "status": "completed",
      "metadata": { "order": "A-1042" },
      "files": [
        {
          "id": "01a6c2f4-3b12-7000-8d55-1c9e0f4a7b21",
          "status": "completed",
          "tier": "4k",
          "outputUrl": "https://cdn.faceswap.ing/permanent/upscales/scene-swapped-4k.jpg",
          "cost": 15
        }
      ]
    }
  }
}

Проверка в Node

js
import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody is the request body exactly as received, before any JSON parsing.
// secret is the signing secret as shown, whsec_...
export function verify(rawBody, headers, secret) {
  const id = headers["webhook-id"] ?? "";
  const timestamp = Number(headers["webhook-timestamp"]);
  const signatures = (headers["webhook-signature"] ?? "").split(" ");

  // Refuse a delivery older than 5 minutes: a replay carries an old timestamp.
  if (!(Math.abs(Date.now() / 1000 - timestamp) <= 300)) return false;

  // The key is the bytes the secret encodes, after its prefix.
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = Buffer.from(
    createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest("base64"),
  );

  // The header may list more than one signature, as "v1,<base64>" each.
  return signatures.some((one) => {
    const [version, value = ""] = one.split(",");
    const given = Buffer.from(value);

    return version === "v1" && given.length === expected.length && timingSafeEqual(given, expected);
  });
}

Проверка в Python

python
import base64
import hashlib
import hmac
import time

# raw_body is the request body exactly as received, as bytes.
# secret is the signing secret as shown, whsec_...
def verify(raw_body: bytes, headers: dict, secret: str) -> bool:
    webhook_id = headers.get("webhook-id", "")
    timestamp = headers.get("webhook-timestamp", "")
    signatures = headers.get("webhook-signature", "").split(" ")

    # Refuse a delivery older than 5 minutes: a replay carries an old timestamp.
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
        return False

    # The key is the bytes the secret encodes, after its prefix.
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = webhook_id.encode() + b"." + timestamp.encode() + b"." + raw_body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()

    # The header may list more than one signature, as "v1,<base64>" each.
    return any(
        version == "v1" and hmac.compare_digest(value, expected)
        for version, _, value in (one.partition(",") for one in signatures)
    )

Цены

Вызов оплачивается по тому, что он обрабатывает, в swapz. Один swapz стоит $0.01, так что каждая цена ниже легко переводится в доллары. Маршруты GET бесплатны. Запуск стоит столько, сколько стоят его файлы, без надбавок, платы за запрос нет.

Фото стоит 5 swapz ($0.05), или 3 swapz ($0.03) за штуку, если в задаче от 20 фото. Видео оплачивается за каждую секунду после обрезки, по размеру кадра, и минимум за 10 секунд, поэтому самый короткий ролик стоит 30 swapz ($0.30).

Это базовые цены для пресетов balanced и fast. Пресет best добавляет 60%, а каждый процессор добавляет свою строку. Полный прайс со всеми опциями находится на https://faceswap.ing/ru/pricing, и приложение списывает по нему же.

Стоимость очереди удерживается с команды ключа при запуске задачи. Когда задача завершается, готовые файлы сохраняют свою цену, а остальное возвращается, так что файл с ошибкой ничего не стоит. cost у каждого файла и chargedSwapz в вебхуке показывают, что списано.

Поиск лиц на фото, который делает выбор лица в приложении, стоит там 1 swapz ($0.01). В API маршрута для него нет, поэтому ключ за него не платит.

Апскейл стоит 8 swapz ($0.08) за фото в 2K, 15 swapz ($0.15) за фото в 4K и 30 swapz ($0.30) за фото в 8K, какого бы размера ни было фото, без пресетов и опций. Удержание и возврат работают так же, по каждому фото.

Что обрабатываетсяSwapzUSD
Одно фото5$0.05
Одно фото в задаче от 20 фото3$0.03
Видео 480p, до 0.6 МП на кадр, за секунду3$0.03
Видео 720p, больше 0.6 и до 1 МП на кадр, за секунду4$0.04
Видео 1080p, больше 1 и до 2.3 МП на кадр, за секунду6$0.06
Видео 1440p, больше 2.3 и до 4 МП на кадр, за секунду9$0.09
Видео 4K, больше 4 и до 8.9 МП на кадр, за секунду15$0.15
Апскейл до 2K, за фото8$0.08
Апскейл до 4K, за фото15$0.15
Апскейл до 8K, за фото30$0.30

Медиафайлы

Маршрута загрузки в API нет. Каждый файл, который вы указываете, задаётся публичным HTTPS URL, и сервис скачивает его сам. Поэтому файл должен открываться без ваших заголовков всё время, пока идёт замена.

Каждое изображение и видео, которое хостите вы, проверяется при запуске замены, до оценки и отправки в работу: целевые файлы, фото лица и превью. Если проверка отклоняет файл, отклоняется весь запуск с code moderation_refused. Если файл проверить не удалось, весь запуск тоже отклоняется, с code moderation_unavailable. Непроверенные файлы мы не обрабатываем, поэтому сбой проверки задерживает запуск, а не пропускает его. Такой отказ ничего не удерживает, и его можно безопасно повторить. Дорожку для синхронизации губ проверка оценить не может, это аудио, поэтому она скачивается как есть.

URL на нашем файловом хосте никогда не допускается через проверку. Он берётся как есть, если принадлежит вашей команде: файл из библиотеки команды, outputUrl готовой замены или апскейла команды, превью такой замены в роли превью или, в роли целевого файла, образец (одно из фото и видео, которые сайт предлагает, чтобы попробовать замену). Любой другой наш URL, в том числе файл или результат другой команды, отклоняет весь запуск с code media_not_in_library до оценки и удержания. Дорожка для синхронизации губ и превью на нашем хосте подчиняются тому же правилу.

Фото может весить до 50 МБ и иметь до 50 МП. Видео может весить до 1 ГБ, иметь до 8.9 МП в кадре и до 60 кадров в секунду. Если включён frameEnhancer, увеличенный результат может быть не больше 8192 пикселей по длинной стороне.

Допустимая длина видео зависит от кадра и считается после обрезки: 300 с до 1440p, 270 с до 4K. Эти значения верны при частоте до 30 кадров в секунду, на пресете balanced, с одной парой и без процессоров. За ними стоит ограничение на время обработки. Файл, обработка которого по оценке займёт больше 90 минут, отклоняется при запуске с code file_over_processing_cap ещё до удержания. Поэтому более высокая частота кадров, пресет best, дополнительные пары и процессоры сокращают допустимую длину.

Целевой файл, URL которого заканчивается на .gif, обрабатывается покадрово и возвращается в виде GIF. Он оплачивается посекундно, как видео, по тарифу своего кадра и с тем же минимумом в 10 секунд. GIF может весить до 100 МБ, длиться до 30 секунд и иметь кадр до 1 МП, а все его кадры вместе не могут превышать 150 МП. GIF 480x270 длится все 30 с при 30 кадрах в секунду, а 1280x720 только 5,4 с. Более быстрый GIF возвращается с частотой 30 кадров в секунду, число повторов сохраняется, прозрачные области становятся белыми, а GIF из одного кадра отклоняется: отправьте такой файл как фото. К GIF нельзя добавить дорожку для синхронизации губ.

Один запуск может указать до 200 файлов общим объёмом до 4 ГБ, длина URL не больше 2048 символов, а каждое видео оплачивается минимум за 10 секунд. Эти значения приложение показывает и применяет, когда не может прочитать каталог самого сервиса. Работающее развёртывание публикует свои значения, и при каждом запросе цена проверяется по ним.

Генерации и загрузки, из которых они сделаны, удаляются через 30 дней после того, как задача достигла конечного статуса. Срок считается от завершения задачи, а не от запуска. Скачайте то, что хотите сохранить. Задача, генерации которой удалены, сохраняет свою строку и URL, а purgedAt показывает, когда их удалили. Только по нему можно отличить URL, который ещё отдаёт файл, от того, который уже нет.