Введение
Video Head Swap Analysis читает ролик и возвращает по одному превью на каждую голову, которую удаётся вести, в фиксированном порядке: первое изображение — позиция 0, второе — позиция 1, и так далее. Именно эти позиции принимает вызов замены: вы смотрите изображения и возвращаете номера.
Здесь ничего не генерируется, и ролик не изменяется. Этот вызов создаёт список целей, с которым работает вызов замены, и это единственный способ узнать, сколько голов в кадре и кто из них кто.
Ключевые возможности и особенности
Выбор по изображениям, а не по координатам
Большинство эндпоинтов замены заставляют описывать, кого вы имели в виду, или догадываются сами. Здесь анализ отдаёт вам кандидатов картинками, с номерами. Неясность с тем, кого заменяют, снимается до того, как что-либо сгенерировано, — то есть в тот момент, когда ошибка ещё ничего не стоит.
Одного анализа хватает на несколько замен
Результат остаётся пригодным 24 часа. Подставьте одного человека, посмотрите на результат, а затем отправьте другой набор референсных фотографий к тому же анализу: анализ оплачивается один раз. Через 24 часа референсы перестают действовать, и ролик приходится анализировать заново.
Читает материал таким, каким он снят
Трекинг ведёт каждую голову через склейки, повороты и частичные перекрытия. Принимаются ролики от 5 до 30 секунд, и анализ сообщает о каждой голове, которую удаётся удерживать на всей длине кадра, а не только о той, что ближе всех.
Параметры запроса
| Параметр | Обязательно | Описание |
|---|---|---|
video_url | Да | Ролик для анализа, от 5 до 30 секунд. Сохраните именно этот адрес: вызов замены должен работать с тем же видео и берёт адрес отсюда автоматически, если там его опустить. Не менее 1 символов |
resolution | Нет | Разрешение трекинга. Вызов замены должен использовать то же значение, поэтому выбирайте разрешение, которое должен иметь готовый ролик. |
Стоимость
$0.08 / анализ
Анализ и замена оплачиваются отдельно.
Сценарии использования
Проверить ролик до того, как платить за замену
Вызов замены стоит дороже анализа. Запустив сначала анализ, вы узнаете, действительно ли нужные вам головы отслеживаются в этом материале: сильное размытие, долгие перекрытия и уходящие из кадра объекты проявляются как отсутствующее или неустойчивое превью.
Выбрать одного из толпы
Проанализируйте сцену, где в кадре несколько человек, прочитайте превью и верните только ту позицию, которую имели в виду. Всех остальных замена не трогает.
Держать один состав на всю серию
Сгенерируйте пачку роликов любой видеомоделью, проанализируйте каждый и по превью выровняйте одну и ту же цель в каждом кадре, чтобы серия читалась как единое целое.
Любой сюжет — с согласия исполнителя
Что бы ни было в материале, в запросе ничего не меняется. Требование авторизации из ограничений ниже тоже не меняется: это жёсткое условие, а не категория контента.
Руководство по промптам и практические советы
Используйте одно и то же разрешение в обоих вызовах
Выберите разрешение, которое должен иметь готовый ролик, и задайте его здесь же: вызов замены обязан работать с тем же значением. На то, что находит этот вызов, оно не влияет — только на кадр, в котором работает замена.
Читайте порядок превью, а не предполагайте его
Изображения приходят упорядоченными, но порядок отражает трекинг, а не положение на экране и не значимость. Самый левый человек в кадре не обязательно позиция 0. Посмотрите на изображения.
Отправляйте одно и то же видео в оба вызова
Вызову замены нужен тот же самый ролик: тот же файл, та же кодировка. Опустите video_url в запросе замены, и он будет взят из анализа, а это самый надёжный способ гарантировать совпадение.
Анализируйте заново, если материал изменился
Перекодирование, обрезка или повторный экспорт делают анализ недействительным: позиции больше не указывают на те же головы. Анализируйте тот файл, который действительно пойдёт на замену.
Быстрый старт 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-video-v1/video-analyze",
"input": {
"resolution": "720p",
"video_url": "https://example.com/reference.mp4"
}
}'
# 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.
