Рабочий процесс API Face Swap на базе ИИ: авторизованные загрузки, асинхронные задачи и надёжная доставка

Сравнить референсные фото и цвет перед заменой.

Face Swap в SpicyAPI — это семейство endpoint'ов без цензуры, которые принимают два изображения (или одно изображение и клип), без промпта и без маски. Это руководство охватывает, какой endpoint вызвать, как проверить его сначала в Playground, а затем из кода или через агента, что проверять в результате и как сохранить результат после того, как платформа его удалит.

Выбрать endpoint под задачу

Начните с Face Swap по $0.013. Переходите на Pro, когда заменённое лицо выглядит глаже или резче остальной части кадра, и на Plus, когда на двух фото заметно различаются тон кожи или цвет освещения. 200 вариантов аватара стоят $2.60 на Face Swap и $32 на Pro, поэтому проверьте самую сложную пару на обоих. У Plus есть поле prompt, которое ни на что не влияет, поэтому не задавайте его, а очки или выражение лица добавьте в исходное фото.

Video Face Swap считает исходный клип целыми 10-секундными блоками, поэтому 12-секундный клип оплачивается как 20 секунд ($0.52), а 40-секундный как $1.04. При отправке удерживается оценка на 40 секунд ($1.04), а разница освобождается после расчёта задачи. Обрежьте по границе блока перед отправкой.

Что эти endpoint'ы делают с настоящими лицами

Эти endpoint'ы указаны как без цензуры: SpicyAPI не добавляет сканирование лица по каждому запросу и не проверяет, реальный ли человек. Сбои обычно связаны с входными данными (лицо не обнаружено, файл недоступен), хотя отдельная модель всё же может отклонить запрос. Политика допустимого использования запрещает выдачу себя за другого, использование сходства реального человека в интимных или сексуализированных целях без его согласия и всё, что связано с несовершеннолетними; после жалобы SpicyAPI может удалить сохранённые материалы и приостановить доступ. Публичное фото или прежние отношения не являются согласием. Запись о согласии храните вы, и она должна быть перед кнопкой загрузки:

• Вошедший пользователь подтверждает, что имеет разрешение изображённого лица и на оба изображения, и на такое использование; сохраните подтверждение вместе с проектом (кто, какой материал, какое использование, когда).
• Никаких изображений несовершеннолетних и никакого использования, которое выдаёт себя за реального человека, чтобы обмануть.

Храните это как продуктовые записи, а не в промптах, аналитических событиях или логах.

Подготовьте входные данные, которые не подведут

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

• Фронтальные, крупные, резкие лица. Сильные ракурсы сбоку, размытие от движения, плотное перекрытие (руки, маски, большие солнечные очки) и слишком мелкие лица ухудшают перенос или приводят к отказу. Крупное, резкое фронтальное референсное лицо даёт лучший результат.
• Одинаковое направление света. Замена не пересвечивает оригинал, поэтому референс, освещённый с другой стороны, даёт шов по линии челюсти. Совместите направление и примерный тон кожи или возьмите другой референс. Plus согласует только тон кожи; расхождение направления света он не исправляет.
• Одно лицо на изображении. Для групповых фото Face Swap и Video Face Swap принимают face_mapping: до 10 записей, каждая связывает референсное лицо с целевым, нумерация с 0 в порядке обнаружения. Перепроверяйте нумерацию при каждом изменении изображения. Plus и Pro рассчитаны на одно лицо; сначала обрежьте.

``json "face_mapping": [{ "reference_face_index": 0, "target_face_index": 1 }] ``

Это переносит референсное лицо 0 на второе лицо, найденное в оригинале. Не указывайте поле, чтобы заменить одно лицо.

• Прямые ссылки на файлы. URL изображения должны открывать файл без входа. Для видео страница, которая проигрывает клип, возвращает HTML, а не клип, и вызов завершается сбоем с возвратом оплаты; загрузите сам файл.
• Роли не взаимозаменяемы. image_url — изображение, которое изменяют; reference_image_url задаёт лицо. Их перестановка даёт корректный запрос с другим результатом и без ошибки, поэтому замена в не ту сторону выглядит как баг модели.

Ограничения для видео: MP4 до 90 MB и от 3 до 40 секунд, референсное изображение JPG, PNG или WEBP до 10 MB. Держите лицо крупным в кадре и не отвёрнутым надолго. Endpoint лучше всего работает с одним человеком в кадре; для клипа с несколькими людьми добавьте face_mapping (та же форма, что выше, нумерация в порядке обнаружения) или обрежьте до нужного человека.

Сначала попробуйте в Playground

Откройте страницу задачи Face Swap и используйте вкладку Playground (настроить, оценить, запустить). Введите целевое изображение и изображение референсного лица, проверьте оценку цены для ваших настроек и запустите. Самую сложную пару проверьте здесь, до написания кода: если результат в Playground неверный, он будет неверным и через API, а исправление — другая пара входных данных. У Head Swap есть такая же вкладка для замены всей головы.

Затем вызовите из кода

Установите Python SDK (pip install spicyapi), задайте SPICY_API_KEY в окружении и выполните:

import json
import uuid
from pathlib import Path
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment
job_file = Path("avatar-8841-layout-02-v1.json")  # keep this file to resume this job

if job_file.exists():
    job = json.loads(job_file.read_text())
else:
    target = client.upload_file("./layout-02.png")
    face = client.upload_file("./approved-portrait.png")
    job = {
        "key": str(uuid.uuid4()),
        "input": {"image_url": target["uri"], "reference_image_url": face["uri"],
                  "style": "realistic", "seed": 4242},
    }
    job_file.write_text(json.dumps(job))  # persist the exact key and payload BEFORE submit

if "taskId" not in job:
    task = client.create_task(
        model="spicyapi/face-swap-v1/edit", input_data=job["input"],
        idempotency_key=job["key"],
    )
    job["taskId"] = task["taskId"]
    job_file.write_text(json.dumps(job))

print("Resume task:", job["taskId"], flush=True)
final = client.wait_for_terminal(job["taskId"])
if final["state"] != "succeeded":
    raise RuntimeError(f"Task {job['taskId']} ended as {final['state']}")
assets = output_assets(final)
if not assets or any(a.get("pending") or a.get("unavailable") or not a.get("url") for a in assets):
    raise RuntimeError(f"Task {job['taskId']} has no ready output; check this task, not a new run")
print(assets[0]["url"])  # copy it to your own storage now

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

Загрузка, ожидание, ошибки и повторы описаны в руководстве по Subject Swap и справочнике Python SDK. Video Face Swap использует spicyapi/face-swap-video-v1/video-edit с video_url и reference_image_url.

Или поручите задачу агенту

Если ассистент должен выполнить замены за вас, дайте ему CLI или MCP-сервер. Оба показывают цену и запрашивают подтверждение перед платным вызовом. Skill добавляет инструкции поверх любого из них.

• CLI. spicyapi выполняет одну задачу из терминала или скрипта (npx @spicyapi/cli работает без установки):

``bash spicyapi files upload ./layout-02.png # prints a spicy:// URI SWAP_REQUEST_KEY="$(python3 -c 'import uuid; print(uuid.uuid4())')" printf 'Save this request key: %s\n' "$SWAP_REQUEST_KEY" spicyapi tasks create --model spicyapi/face-swap-v1/edit \ --input-file input.json --idempotency-key "$SWAP_REQUEST_KEY" --wait ``

input.json содержит тот же объект input, что выше, с URI вида spicy://. Этот блок запускает новую задачу. Сохраните напечатанные ключ и ID задачи; после тайм-аута продолжите ту задачу, а не перезапускайте блок с новым ключом.

• MCP-сервер. Добавьте MCP-сервер в ассистент, затем спросите: "Swap the face in ./layout-02.png for the one in ./approved-portrait.png with Face Swap." Он вызывает spicyapi_upload_file, затем spicyapi_task_create (который останавливается для подтверждения цены), затем spicyapi_task_wait.

``json { "mcpServers": { "spicyapi": { "command": "npx", "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"], "env": { "SPICY_API_KEY": "YOUR_SPICY_API_KEY" } } } } ``

• Skill. npx skills add spicyapi-ai/spicy-skill устанавливает Agent Skill, который учит ассистента программиста читать актуальную схему, переиспользовать ключи идемпотентности и сохранять результаты вместо догадок. Сам он задачи не выполняет, поэтому используйте его вместе с CLI или MCP.

Запись о согласии и копирование результатов в собственное хранилище относятся к вызовам агента ровно так же, как к вашим.

Проверьте, прежде чем считать готовым

succeeded означает, что генерация завершена. Перед скачиванием убедитесь, что у результата есть пригодный URL и что ни pending, ни unavailable не равны true; пока pending равен true или URL отсутствует, продолжайте опрашивать ту же задачу. Готовность к выдаче всё же не означает, что изображение одобрено. Для видео проверьте склейки и быстрые движения, а не только первый кадр. Оценка схожести — это диагностический сигнал, а не согласие и не разрешение на публикацию.

Две проверки, которые меняют ваши дальнейшие действия:

• Волосы часть дизайна (игровой персонаж, маскот). Face Swap сохраняет причёску оригинала, поэтому новое лицо оказывается под старыми волосами. Используйте вместо этого Head Swap с фиксированным изображением карточки персонажа как референсом и сравнивайте каждый результат с карточкой: плывущее лицо на стабильной композиции — это проблема идентичности, обратное — проблема кадрирования, а повтор исправляет только одно из двух.
• Один портрет в нескольких макетах. Запустите Face Swap один раз на макет с тем же референсом и тем же seed. Принимайте результат, когда лицо узнаваемо относительно портрета в том кадрировании, которое вы опубликуете, очки и линия волос не уплыли и не появились лишние люди; сохраните вместе с ним ревизию референса, ревизию оригинала и ID задачи.

Доставка: скопируйте результат сами

Загруженные исходники удаляются через день, а результаты — не позже чем через 14 дней (retention.outputsExpireAt содержит точное время). Скачайте результат и сохраните его сами; ссылка на результат живёт около 20 минут. Смотрите руководство по хранению.

Когда что-то идёт не так

FAQ

Откажется ли API работать с лицом реального человека?

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

Можно ли отправить видео и изображение одним вызовом?

Да, в Video Face Swap: один MP4 и одно референсное фото. Для нескольких людей в одном клипе используйте там face_mapping или двухшаговый сценарий Video Head Swap, когда нужны целые головы.

Хостинговый API или самостоятельно развёрнутый open-source обмен?

Хостинговый endpoint стоит $0.013 за изображение и снимает с вас provisioning GPU и обслуживание моделей. Самостоятельное развёртывание заменяет оплату за изображение на расходы на GPU и эксплуатацию; дешевле ли это, зависит от пропускной способности и загрузки. Большой стабильный объём распределяет эти расходы на большее число изображений, но согласие и правила хранения вы всё равно поддерживаете сами.

Это то же самое, что общий API для редактирования изображений?

Нет. Endpoint замены принимает два изображения (или одно изображение и клип), без промпта и без маски, и каждый endpoint решает, что остаётся от оригинала: Face Swap сохраняет волосы, Head Swap заменяет их. Одна и та же пара входов может по-разному провалить проверку в каждом из них, поэтому сначала выберите endpoint.

Стоит ли хранить исходные портреты вместе с результатом?

Только если у вас есть ясная причина и раскрытая политика хранения. Загруженные исходники в SpicyAPI и так удаляются через день, поэтому сохраните ID ревизии референса и оригинала, а также ID задачи как родословную, вместо постоянной копии каждого портрета.

Нужны ли webhooks или достаточно опроса?

Сам по себе опрос работает и служит путём восстановления: считывайте раз в несколько секунд или добавьте wait (до 60 с) в createTask для коротких замен изображений. Добавьте webhook для меньшей задержки, сохраняйте каждое событие один раз и считайте опрос сверкой пропущенных обратных вызовов.

Что вы должны уметь ответить

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