Введение
Head Swap заменяет голову человека на целевом изображении целиком — головой с референсной фотографии. Переносятся лицо, причёска, цвет волос и силуэт черепа; тело, одежда, поза, свет и фон целевого кадра остаются прежними.
Запрос — это два URL изображений и необязательный seed: image_url — тело, которое остаётся, reference_image_url — источник головы. Нет ни промпта, ни маски, ни регулятора силы, а каждый запрос возвращает одно изображение.
Ключевые возможности и особенности
Голова персонажа целиком — в существующий кадр
Head Swap меняет больше, чем лицо: это правильный объём, когда волосы, их цвет и силуэт головы нового персонажа должны переехать вместе с ним. Поэтому он подходит для смены персонажа, концептов костюмов и работы над непрерывностью, когда причёска целевого кадра остаться не должна.
Переход к шее — главный критерий приёмки
Выбирайте исходники с совместимым ракурсом камеры и направлением света, где видна шея. Прежде чем принять результат, проверьте в полном размере линию роста волос, уши, челюсть, шов на шее и непрерывность теней: именно на этих границах видно, действительно ли два изображения сочетаются.
Начинайте с контролируемой пары изображений
На каждом изображении должен быть один чёткий человек; избегайте сильного размытия, перекрытий и крайних профилей. Когда собственные волосы и силуэт целевого кадра важны для снимка, выбирайте Face Swap, а не навязывайте замену головы целиком.
Параметры запроса
| Параметр | Обязательно | Описание |
|---|---|---|
image_url | Да | Изображение, которое меняют. Его тело, одежда, поза, свет и фон сохраняются; всё выше шеи заменяется. Не менее 1 символов |
reference_image_url | Да | Изображение, отдающее голову целиком, вместе с её формой, причёской и цветом волос. Выбирайте снимок со схожим направлением света и схожим наклоном головы. Не менее 1 символов |
seed | Нет | Переиспользуйте seed, чтобы сравнить два прогона на одной и той же паре изображений при одинаковой выборке; оставьте пустым или поставьте 0 ради случайного прогона каждый раз. |
Стоимость
$0.013 / изображение
Сценарии использования
Заменить голову целиком, а не только лицо
Используйте этот эндпоинт, когда причёска, цвет волос и силуэт головы нового человека должны прийти вместе с ним. Прежде чем принять результат, проверьте в полном размере линию роста волос, уши и шов на шее; если собственные волосы целевого кадра — часть снимка, более узкий инструмент — Face Swap.
Новая голова в кадре тела, который вам уже нравится
Когда одежда, поза и свет кадра уже работают, заменить голову дешевле и предсказуемее, чем генерировать всё изображение заново в надежде, что композиция уцелеет.
Костюмные и косплей-кадры
Поставьте собственную голову и причёску персонажа на тело в костюме, который вы сгенерировали. Форма горничной, поза и декорации кафе остаются ровно такими, какими были, так что работа над костюмом сохраняется.
Любая сцена с лицом, на которое есть согласие
Перенесите голову, которую вам разрешено использовать, в кадры, созданные вами самими, что бы в них ни было. Эндпоинт не обращается с таким материалом иначе: решает требование согласия из ограничений ниже, и это не формальность.
Руководство по промптам и практические советы
Убедитесь, что у вас есть права на обоих людей
На обоих изображениях человек, и вам нужно разрешение как на переносимую голову, так и на кадр, в который вы её переносите. Храните согласие вместе с записью о задаче ещё до начала интеграции.
Подгоните ракурсы, затем отправьте пару
image_url — тело, которое остаётся; reference_image_url — источник головы. Универсальному графическому редактору понадобилась бы инструкция вроде: «Head swap: replace the entire head of the person in the first image — face, hairstyle and hair colour — with the head from the second image, keeping the first image's body, maid outfit, pose, cafe background, lighting and colour grade unchanged. Match the neck seam, skin tone and lighting direction so the result reads as one photograph.» Здесь поля для промпта нет вовсе.
Проверьте результат, прежде чем повторять
Слабое место — шов на шее: если на целевом кадре шея закрыта высоким воротником, шарфом или волосами или голова повёрнута под сильно другим углом, чем на референсе, стык будет виден. Согласуйте направление света и тон кожи двух исходников и выбирайте похожие ракурсы головы. На обоих изображениях нужна хорошо видимая, примерно фронтальная, хорошо освещённая голова достаточного размера; на групповом снимке эндпоинт не может понять, какого человека вы имеете в виду. Если причёска целевого кадра должна остаться, используйте Face Swap — никакой параметр здесь её не сохранит. Нет ни промпта, ни маски, ни регулятора силы, поэтому неверный результат исправляется другой парой изображений.
Быстрый старт API
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "spicyapi/head-swap-v1/edit",
"input": {
"image_url": "https://example.com/reference.png",
"reference_image_url": "https://example.com/reference.png"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
Аутентификация, полная схема, опрос статуса и обработка ошибок описаны в справочнике API.
