Video Character Swap: референсы, выбор цели и проверка

Используйте Character Swap, когда замена должна изменить весь облик человека, включая телосложение и одежду, а сцена, движение камеры и исходный звук остаются. Character Swap позволяет выбрать, кто именно в клипе будет заменён: проанализируйте финальный клип, изучите пронумерованные превью и затем отправьте выбранный индекс превью вместе с одним-тремя изображениями замены. Если исходная одежда должна остаться, используйте воркфлоу head swap или face swap.

В SpicyAPI анализ и редактирование — это две отдельные платные задачи. Семисекундный исходник стоит в сумме $0.72 в 480p или $1.28 в 720p: один анализ плюс редактирование с округлением до десяти секунд. Playground выполняет оба шага прямо в браузере, а API принимает те же входные данные. Вам нужно разрешение и на исходный материал, и на сходство с человеком в референсных изображениях.

Подготовьте семисекундную сцену и замену в полный рост

Наш пример — семь секунд, в которых кто-то несёт закрытый ящик для инструментов к верстаку, пока рядом стоит другой взрослый. Несущего меняют на вымышленную взрослую женщину в тёмно-синей рабочей куртке и угольно-серых брюках: это внешность с иллюстраций ниже. Верстак, ящик для инструментов, второй человек и исходное исполнение остаются.

Экспортируйте ровно тот семисекундный исходник, который собираетесь редактировать. Сохраните начальный захват, действие переноса и отпускание, когда ящик для инструментов достигает верстака. На вход принимается MP4 длиной 5–30 секунд размером до 90 MB. Загрузка файла — самый надёжный путь; прямая ссылка должна указывать на сам MP4-файл, потому что страница с плеером не сработает (списание вернут). Обрезка или перекодирование после анализа требуют нового анализа.

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

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

Рабочий бриф для генерации изображения выглядит так:

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

При необходимости сгенерируйте или снимите второй ракурс того же уже утверждённого дизайна. У редактирования character swap нет поля текстового промпта, выбора одежды и маски тела, поэтому нужная одежда должна быть в референсных изображениях.

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

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

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

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

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

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

Установите Python SDK (pip install spicyapi), задайте SPICY_API_KEY и выполните следующее. Код загружает клип и два референса, запускает анализ, печатает ссылки на превью, спрашивает, какой индекс заменить, затем отправляет редактирование. Обе задачи оплачиваются.

import uuid

from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment
RESOLUTION = "720p"     # must be identical in both calls

clip = client.upload_file("./workshop-seven-seconds.mp4")
front = client.upload_file("./replacement-front.png")
angled = client.upload_file("./replacement-three-quarter.png")

analysis_task = client.create_task(
    model="spicyapi/character-swap-v1/video-analyze",
    input_data={"video_url": clip["uri"], "resolution": RESOLUTION},
    idempotency_key=str(uuid.uuid4()),  # new key per new request; reuse only to retry the same one
)
print("Resume analysis:", analysis_task["taskId"], flush=True)
analysis = client.wait_for_terminal(analysis_task["taskId"])
if analysis["state"] != "succeeded":
    raise RuntimeError(f"Analysis {analysis_task['taskId']} ended as {analysis['state']}")

previews = output_assets(analysis)
if not previews or any(p.get("pending") or p.get("unavailable") or not p.get("url") for p in previews):
    raise RuntimeError(f"Analysis {analysis_task['taskId']} has no ready previews; retrieve it before editing")
for index, preview in enumerate(previews):  # keep the returned order
    print(index, preview["url"])
chosen = int(input("Index of the person to replace: "))
if not 0 <= chosen < len(previews):
    raise ValueError("Choose one of the returned preview indices before creating an edit")

edit_task = client.create_task(
    model="spicyapi/character-swap-v1/video-edit",
    input_data={
        "analysis_task_id": analysis["taskId"],  # video_url is inherited from the analysis
        "resolution": RESOLUTION,
        "swap_targets": [{"object_index": chosen,
                          "image_urls": [front["uri"], angled["uri"]]}],
        "seed": 42,
    },
    idempotency_key=str(uuid.uuid4()),  # new key per new request; reuse only to retry the same one
)
print("Resume edit:", edit_task["taskId"], flush=True)
edit = client.wait_for_terminal(edit_task["taskId"])
if edit["state"] != "succeeded":
    raise RuntimeError(f"Edit {edit_task['taskId']} ended as {edit['state']}")
assets = output_assets(edit)
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 {edit_task['taskId']} has no ready output; check this task before a new run")
print(assets[0]["url"])  # copy it to your own storage now

Загрузка, ожидание, ошибки и повторы описаны в руководстве по subject swap, документации по задачам и справочнике Python SDK. Используйте один и тот же API-ключ для обоих шагов и запускайте редактирование в течение 24 часов после анализа (загруженный клип тоже истекает через сутки); один анализ может обслуживать несколько отдельно оплачиваемых редактирований. Люди, которых вы не указали, остаются нетронутыми, а индекс принадлежит этому анализу, поэтому не используйте его как ID персонажа в другом кадре.

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

Или пусть всё сделает агент

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

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

``bash spicyapi files upload ./workshop-seven-seconds.mp4 # prints a spicy:// URI spicyapi tasks create --model spicyapi/character-swap-v1/video-analyze \ --input-file analysis.json --idempotency-key workshop-analysis-v1 --wait ``

В analysis.json хранится {"video_url": "spicy://...", "resolution": "720p"}. Посмотрите на превью, затем выполните команду с video-edit, его собственным ключом workshop-edit-v1 и файлом input.json, содержащим analysis_task_id, resolution и swap_targets. Используйте ключ повторно только для неизменного запроса; новый исходник, новая цель или новый набор референсов требует нового ключа.

• MCP-сервер. Добавьте MCP-сервер (его фрагмент конфигурации есть на той странице) вашему ассистенту, а затем спросите: «Проанализируй ./workshop-seven-seconds.mp4 в 720p с помощью Character Swap и покажи превью». После того как вы выбрали человека, скажите: «Замени индекс 1, используя ./replacement-front.png и ./replacement-three-quarter.png». Он вызывает spicyapi_upload_file, затем spicyapi_task_create (который останавливается для подтверждения цены), затем spicyapi_task_wait.
• Skill. npx skills add spicyapi-ai/spicy-skill устанавливает Agent Skill, который учит ассистента для кода читать актуальную схему и переиспользовать ключи идемпотентности. Сам он задачи не выполняет, поэтому используйте его вместе с CLI или MCP. Какое именно превью заменять — по-прежнему ваше решение.

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

Цены взяты из публичного каталога (октябрь 2026).

Длительность редактирования округляется до целых блоков по пять секунд, с минимумом в пять секунд и максимумом в тридцать. Исходник в 5 секунд занимает один блок; 5,1 секунды — два. Перед отправкой смета редактирования резервирует максимум в тридцать секунд, $1.92 в 480p или $3.60 в 720p, и разница возвращается после завершения задачи. Поэтому проверка бюджета должна учитывать резерв, а не только ожидаемую итоговую сумму. Запрос, отклонённый при создании (несовпадение разрешения, неверный ID анализа, повторяющийся индекс), ничего не создаёт и не списывает.

Два редактирования в 720p семисекундного исходника с повторным использованием одного анализа обходятся в $2.48: $0.08 плюс дважды по $1.20. Смена референсов или seed — это новое платное редактирование, а не бесплатная правка.

Исправьте нужную проблему

Иллюстрация: проверка отпечатанного кадра.

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

Скопируйте принятый клип в собственное хранилище до истечения срока: результаты хранятся около 14 дней (см. хранение и доставку медиа).