Genjutsu API: отправка одного видео для замены объекта
Используйте Genjutsu API для одного запроса Object Swap: подготовьте исходный клип, отправьте задачу и получите отредактированное видео.

Функция редактирования видео может вернуть успешно завершённое задание, а у команды всё равно останется непригодный ресурс: обработан не тот фрагмент клипа, замена «плывёт» от кадра к кадру или никто не сохранил результат. При интеграции Genjutsu API я бы сделал так, чтобы каждую правку можно было проследить от входных данных до утверждённого файла. В кратком руководстве по API Higgsfield описан процесс «отправить — опросить — получить»; это руководство применяет его к одному запросу Object Swap.
Higgsfield предоставляет модель и эндпоинт. Если ваш продукт использует WaveSpeedAI, проверьте в его каталоге моделей именно эту операцию и её собственную схему запроса. Не считайте, что другая модель замены объектов в видео примет запрос Higgsfield.

Что нужно для одного запроса Genjutsu Object Swap?
Для одного запроса нужны URL исходного видео и от одного до восьми URL референсных изображений. Промпт необязателен. Параметр resolution по умолчанию равен 720p; также указаны 480p и 1080p. В справочнике по API Object Swap модель обозначена как higgsfield/genjutsu/object-swap/v1.0. Для неё требуется видео длительностью не менее четырёх секунд и не менее 409 600 пикселей на кадр.
Проверяйте клип до отправки. Видео длиннее 30 секунд обрезается до 30 секунд, и длительность результата соответствует подготовленной длительности. Если нужная правка приходится на 34-ю секунду, успешный запрос всё равно не сможет её выполнить. Сначала выберите сегмент, затем зафиксируйте, какой именно сегмент вы отправили.
Серверный запрос может выглядеть так. URL и переменные окружения приведены для примера:
curl -X POST \
"https://api.higgsfield.ai/higgsfield/genjutsu/object-swap/v1.0" \
-H "Authorization: Key ${HF_KEY}" \
-H "Idempotency-Key: ${EDIT_ID}" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://example.com/approved-source.mp4",
"image_urls": ["https://example.com/approved-object.png"],
"prompt": "Replace the featured cup with the reference cup.",
"resolution": "720p"
}'
Храните учётные данные на сервере. Задайте каждой логической правке собственный стабильный ключ идемпотентности, чтобы неоднозначную отправку можно было повторить, не создавая второе задание намеренно. Если на исходном видео изображён узнаваемый человек или используются защищённые материалы или произведения искусства, получите необходимые права и согласия до загрузки. Это напоминание для продакшена, а не юридическая консультация.
Отправьте правку и отслеживайте её статус
Успешный POST означает, что работа принята, но не возвращает готовое видео. Сохраните request_id, status_url и cancel_url из ответа в записи о правке в вашем продукте. Используйте возвращённые URL, а не составляйте их самостоятельно.
В документации по жизненному циклу запроса Higgsfield queued и in_progress указаны как нетерминальные состояния. Прекращайте ожидание, когда статус становится completed, failed, nsfw или canceled. Показывайте эти исходы в интерфейсе по отдельности. «Всё ещё обрабатывается» — плохая обратная связь, если провайдер уже отклонил задание.

Начните опрос примерно с двухсекундным интервалом, а при более долгом ожидании увеличивайте его. Если при проверке статуса произошла временная сетевая ошибка, повторите проверку статуса. Не отправляйте новый POST для правки только потому, что один опрос не удался. Сохраните итоговый статус и возвращённую ошибку вместе с идентификатором запроса, чтобы поддержка могла отличить неудавшуюся генерацию от браузерной сессии, завершившейся раньше времени.
Получите готовое видео и проверьте его
Когда статус completed, прочитайте video.url из результата. Скачайте файл в хранилище, которое контролирует ваш продукт, затем проверьте, что он воспроизводится и соответствует задуманной правке. Завершённое API-задание — это кандидат на поставку, а не решение об утверждении.
Проверяйте не только миниатюру. Посмотрите замену в начале, середине и конце клипа, особенно там, где объект уходит за другой объект или пересекает кадр. Сравните длительность обработанного видео с сегментом, который вы отправили. Если для функции важен звук, проверьте и звуковую дорожку результата: в справочнике Object Swap нет обещания сохранения аудио источника.
Один удачный результат не означает, что рабочий процесс готов к продакшену. Завершение задания у провайдера говорит лишь о том, что файл существует. Допустим ли этот файл в продукте, решает ваша приёмочная проверка.
Сделайте Object Swap воспроизводимым в продакшене
Сохраняйте манифест правки для повторного запуска
Храните вместе версию исходного ресурса, выбранный временной диапазон, версии референсных изображений, промпт, разрешение, идентификатор модели, ключ идемпотентности, идентификатор запроса и итоговый статус. Добавьте место хранения утверждённого результата. Один человек может помнить параметры. Команда — нет.
Такая запись выручает, когда редактор просит «ту же замену, но с синим продуктом». Команда сможет сознательно изменить один входной параметр, а не восстанавливать прежний запрос по файлу с именем final-v3.mp4.
Архивируйте оригинал и утверждённый результат
Сохраняйте исходный клип для отката, а утверждённый результат копируйте за пределы временного хранилища провайдера. В условиях API о хранении и согласии Higgsfield сказано, что сгенерированные медиа доступны как минимум семь дней, но после этого могут быть удалены. Это не гарантия постоянного URL. Фиксируйте, был ли результат принят, отклонён или отправлен на доработку, и почему.
FAQ

Сохраняет ли Object Swap звук исходного клипа?
В опубликованном справочнике Object Swap об этом не сказано. Не обещайте в продукте передачу аудио. Протестируйте на клипе, использование которого разрешено и в котором есть узнаваемая звуковая дорожка, затем проверьте возвращённый файл, прежде чем заявлять о такой возможности.
Можно ли отменить запрос Genjutsu, стоящий в очереди?
Да, пока он остаётся в очереди и отмена возможна. Отправьте запрос на отмену на возвращённый cancel_url; простая остановка вашего опроса задание не отменяет. После начала обработки отмена, согласно документированному жизненному циклу, недоступна.
Что произойдёт, если срок действия URL источника истечёт во время подготовки?
В документации не указана единая точка сбоя для истекающего входного URL Object Swap. Держите источник доступным всё время, пока Higgsfield может его запрашивать. Если подготовка не удалась, записывайте фактический статус запроса и ошибку. Принятый POST не доказывает, что файл уже был скачан.
Списываются ли расчётные единицы при сбое подготовки входных данных?
Зависит от сообщённого сбоя. В руководстве по оплате и хранению Higgsfield сказано, что запросы, завершившиеся статусом failed или nsfw, не тарифицируются, а зарезервированные кредиты возвращаются. «Сбой подготовки входных данных» сам по себе не является платёжным статусом, поэтому проверяйте ответ и запись о списаниях, а не применяйте одно правило ко всем таким ошибкам.
Как долго остаётся доступным URL готового видео?
Сгенерированные медиа доступны не менее семи дней и после этого могут быть удалены. Скачивайте утверждённое видео сразу. Если пользователи могут вернуться к функции Genjutsu API через несколько недель, отдавайте сохранённую копию из собственного хранилища.
Предыдущие статьи:
/filters:quality(82)/media/images/1773962750383987480_n3hqzHRZ.webp)
/filters:quality(82)/media/images/3439779b-d7cf-42fd-958d-8711fe2abdf4.webp)