Video Head Swap API: анализ, выбор цели и редактирование

Video Head Swap — это двухэтапный рабочий процесс API: проанализируйте MP4 длиной 5–30 секунд, посмотрите на нумерованные превью голов, затем отправьте выбранную позицию и портреты замены в редактирование. Лицо, причёска, цвет волос и форма головы меняются; тело, костюм, движение, звук и все, кого вы не выбрали, остаются такими, как были в съёмке.

Здесь вы сначала видите каждую отслеженную голову и указываете нужную, и только потом платите за редактирование. Оно работает с уже готовым видео; оно не превращает два стоп-кадра в постановку (для этого возьмите модель изображение в видео).

Выберите подходящую замену

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

Подготовьте исходник и референсные портреты

Используйте только изображения, которые вам разрешено обрабатывать: своё, изображение исполнителя с подписанным разрешением или сгенерированную голову. Все, кто появляется в кадре, должны быть взрослыми. Оба вызова без цензуры, поэтому SpicyAPI не добавляет фильтр содержимого, и эта проверка остаётся на вас.

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

Экспортируйте окончательный исходник до анализа: MP4, до 90 МБ, от 5 до 30 секунд. video_url принимает публичную ссылку HTTPS, которая возвращает сам MP4, а не HTML-страницу плеера, либо URI spicy:// из бесплатного загрузочного сценария — это самый надёжный способ для локального файла. Если позже вы обрежете, кадрируете или перекодируете исходник, запустите анализ заново.

Подготовьте от 1 до 3 портретов того же взрослого человека, который заменит исходного. Вид спереди и вид в три четверти — полезная стартовая пара; добавьте профиль, если в исходнике есть существенный поворот головы. Держите причёску и видимый возраст согласованными по всему набору. Согласуйте портреты и с материалом: освещайте их с той стороны, с которой освещён кадр, а голову поставьте в похожем ракурсе. Именно на стыке шеи проявляется несовпадение, и ни одно поле запроса его не компенсирует. Референсы одежды в полный рост относятся к замене персонажа; для этой задачи голова и волосы должны быть чётко видны.

Для вымышленного референсного изображения используйте примерно такой бриф:

Референсный фотографический портрет одного вымышленного взрослого мужчины, около 35 лет, с короткими тёмными волосами, аккуратной бородой и нейтральным выражением лица, в простой рубашке, полностью застёгнутой. Мягкий равномерный свет, открытые лицо и волосы, простой фон. Вид спереди, без других людей, без текста.

Создавайте остальные ракурсы из этой утверждённой личности, а не запрашивайте независимо не связанных между собой людей. У редактирования нет поля prompt, поэтому весь результат несут референсы.

Иллюстрация для набора референсов: вид спереди, в три четверти и в профиль.

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

1. Откройте страницу редактирования Video Head Swap и останьтесь на вкладке Playground в режиме Form. Войдите в аккаунт с пополненным балансом, чтобы запустить выполнение.
2. Шаг 1, Find the people in your clip. Добавьте клип в поле Input video (перетащите MP4 или используйте Asset URL) и выберите Resolution, 480p или 720p. Редактирование должно использовать то же значение, поэтому выберите то, которое нужно итоговому клипу. Нажмите Find people in this clip ($0.08).
3. Шаг 2, Choose who to replace. Каждая отслеженная голова появляется как нумерованное превью. Выберите нужное и добавьте от одного до трёх референсных фото взрослого человека, который заменит исходного. Задавайте Seed только тогда, когда хотите корректно сравнить наборы референсов; иначе не задавайте.
4. Запустите редактирование, затем проверьте в результате челюсть, шею, волосы и воротник, включив звук.

Анализ остаётся пригодным для повторного использования 24 часа, поэтому вы можете попробовать другой набор референсов по тем же превью, не платя за отслеживание повторно. Каждое принятое редактирование, в том числе с новым набором референсов или новым seed, — новая платная задача. Если ни одно превью не показывает нужного человека, помогает более чёткий дубль: голову, которую никогда не видно чётко, отследить нельзя, а клип без отслеживаемой головы завершается ошибкой с освобождением удержания.

Страница анализа выполняет шаг 1 сама по себе; успешный анализ оплачивается, даже если вы на этом остановитесь.

Затем запустите из кода

Установите Python SDK (pip install spicyapi), задайте SPICY_API_KEY в окружении и сохраните это как swap.py. analyze печатает URL превью; edit принимает ID задачи анализа и выбранную вами позицию превью. Редактирование должно использовать тот же ключ API и то же разрешение, что и анализ, и не принимает video_url: оно наследует проанализированный клип.

import sys
import uuid
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment

def run(model: str, input_data: dict) -> tuple[str, list]:
    task = client.create_task(model=model, input_data=input_data,
                              idempotency_key=str(uuid.uuid4()))
    final = client.wait_for_terminal(task["taskId"])
    if final["state"] != "succeeded":
        raise RuntimeError(f"{task['taskId']} ended as {final['state']}: {final.get('errorCode')}")
    return task["taskId"], output_assets(final)

if sys.argv[1] == "analyze":
    task_id, previews = run("spicyapi/head-swap-video-v1/video-analyze", {
        "video_url": "https://your-media.example/conversation.mp4",
        "resolution": "720p",
    })
    print("analysis task:", task_id)
    for position, asset in enumerate(previews):   # position 0 is the first image returned
        print(position, asset["url"])
else:  # python swap.py edit <analysis_task_id> <position>
    _, outputs = run("spicyapi/head-swap-video-v1/video-edit", {
        "analysis_task_id": sys.argv[2],
        "resolution": "720p",
        "swap_targets": [{
            "object_index": int(sys.argv[3]),
            "image_urls": [
                "https://your-media.example/replacement-front.png",
                "https://your-media.example/replacement-three-quarter.png",
            ],
        }],
        "seed": 42,
    })
    print(outputs[0]["url"])  # copy the video to your own storage now

Выполните python swap.py analyze, откройте каждое превью и запишите номер нужного взрослого (позиция 0 — это первое возвращённое изображение, а не правило слева направо; никогда не возвращайтесь к 0, если вашего человека там нет), затем выполните python swap.py edit <analysis_task_id> 1. Редактирование принимает от 1 до 10 целей, для каждой от 1 до 3 референсных изображений одного и того же человека; полей для маски, одежды, звука и промпта нет. Создание, ожидание, повторные попытки, ключи идемпотентности и загрузка файлов описаны в руководстве по задачам и в справочнике Python SDK; локальный файл проходит через бесплатный загрузочный сценарий и возвращается как URI spicy:// для video_url.

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

Когда вызовы должен выполнить ассистент, все три официальных инструмента показывают цену и запрашивают подтверждение перед платным вызовом.

• CLI. Поместите объект input анализа (video_url, resolution) в analysis.json, затем:

``bash spicyapi tasks create --model spicyapi/head-swap-video-v1/video-analyze --input-file analysis.json --wait ``

Запустите редактирование так же с edit.json. Смотрите документацию CLI; npx @spicyapi/cli работает без установки.

• Сервер MCP. Добавьте сервер MCP, затем спросите: "Analyse conversation.mp4 with Video Head Swap at 720p and show me the numbered previews." Он загружает файл через spicyapi_upload_file, вызывает spicyapi_task_create, который останавливается для подтверждения цены, а затем spicyapi_task_wait. Выберите позицию сами, затем попросите редактирование.
• Skill. npx skills add spicyapi-ai/spicy-skill устанавливает Agent Skill, который заставляет кодового ассистента читать актуальную схему модели, а не угадывать поля.

Как выглядит готовое редактирование

Опубликованный пример модели ниже — это десятисекундный исходный клип и его редактирование в 480p с одним референсным портретом. Волосы и лицо меняются; платье, походка, контровой свет и камера остаются. Сначала проверьте челюсть и линию шеи, где проявляется несовпадение света или ракурса.

Сколько это стоит

Редактирование стоит $0.064 за оплачиваемую секунду в 480p и $0.12 в 720p. Тарификация идёт пятисекундными блоками, с минимумом в пять секунд и максимумом в тридцать секунд. Клип длиной 10 секунд в 480p стоит в сумме $0.72: $0.08 за анализ плюс $0.64 за редактирование.

До расчёта редактирование резервирует максимум в тридцать секунд, $1.92 при 480p или $3.60 при 720p. Клип длиной двенадцать секунд при 720p удерживается на $3.60, хотя стоимость его редактирования составляет $1.80; остаток освобождается, когда задача рассчитывается.

Диагностируйте выбор, идентичность и выдачу по отдельности

Иллюстрация для проверки волос, воротника и руки на переднем плане.

Просмотрите возвращённое видео со звуком. Редактирование сохраняет звук и движение тела исходника; оно не меняет голос говорящего, а окружение не гарантированно совпадает пиксель в пиксель. Осмотрите и того, кого не выбирали, особенно во время пересечений в кадре. Если рука пересекает заменённое лицо, покадрово проверьте момент касания и повторного появления, а не утверждайте только привлекательный первый кадр.

Сразу сохраните принятое видео в собственное хранилище: ссылки на результат живут около 20 минут, а сами результаты хранятся не более 14 дней, поэтому ID анализа, изображение превью и временный URL медиа не являются постоянной копией.