PixVerse Swap API: JSON для замены человека, предмета и фона

Что делает именно Swap endpoint

В этом руководстве используется модель pixverse/swap с операцией video-to-video в едином API Celestria Gate. Она изменяет элемент существующего видео по изображению замены. Клиент обращается к /v1/media, а Gate автоматически выбирает совместимого поставщика. Если доступен один маршрут, модель работает через тот же контракт; отдельного клиентского подключения не требуется.

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

Выберите person, object или background

В parameters.mode значение person используют для человека, object — для предмета, background — для окружения. Опишите желаемую правку до подготовки файлов. Для замены фона фотография должна показывать окружение; для товара — внешний вид товара. Один и тот же адрес в массиве image_urls нельзя считать подходящим для всех задач без проверки содержания. Провайдерские поля клиенту подбирать не требуется.

Для первого теста выберите сцену с одной отчётливой целью и коротким действием. На сложном монтаже результат трудно оценить: ошибка может относиться к выбору объекта, фото, опорному кадру или склейке. Сначала подтвердите простое изменение. Затем расширяйте сценарий по одному усложнению — несколько объектов, перекрытия или подвижная камера.

Поля и типы: не смешивайте строки и числа

Ниже значения request.json для режима person. Укажите доступные ссылки вместо example.org. Кавычки сохраняются вокруг строк, включая person и 720p. Число кадра передаётся без кавычек, логические переключатели — true или false. Комментарии внутри JSON добавлять нельзя: пояснения следует хранить рядом с файлом. Не копируйте поле от другой модели только из-за знакомого названия.

Проверьте назначение входов: video_url содержит исходник, image_urls — массив с фотографией новой внешности. Общие operation, resolution и keep_audio находятся в input. Допустимые размеры текущей схемы — 360p, 540p и 720p. Специальные mode, keyframe_id и enable_safety_checker находятся в input.parameters. Для иного сценария меняйте режим и фото осмысленно, сохраняя соответствие типам схемы.

{
  "model": "pixverse/swap",
  "input": {
    "video_url": "https://example.org/source-5s.mp4",
    "resolution": "720p",
    "operation": "video-to-video",
    "image_urls": [
      "https://example.org/new-person.jpg"
    ],
    "keep_audio": true,
    "parameters": {
      "mode": "person",
      "keyframe_id": 1,
      "enable_safety_checker": true
    }
  }
}

Как выбрать keyframe_id без путаницы со временем

parameters.keyframe_id — номер кадра, а не миллисекунды. PixVerse нормализует видео к двадцати четырём кадрам в секунду. Начальный кадр имеет номер один; двадцать четвёртый соответствует примерно одной секунде. Выбирайте момент, когда цель хорошо видна и ещё не закрыта рукой или другим человеком. Параметр не обрезает ролик и не назначает длительность результата.

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

Проверьте схему и доступность до оплаты

Ключ нужен от Celestria Gate. Храните его на сервере или в CELESTRIA_API_KEY; не вставляйте в общий файл примеров. Запрос схемы ниже не запускает видео. Каталог /v1/media/models содержит ID моделей и описания операций. Проверьте актуальную схему выбранной задачи, а затем оценку того же JSON. Полученная карточка ещё не гарантирует готовый коммерческий запуск.

POST /v1/media/estimate проверяет совместимость и цену без платной генерации. В ответе provider сообщает поставщика, reason объясняет выбор, estimate содержит оценку или null. Неизвестную цену не считают нулевой, а неполное сравнение не доказывает самый дешёвый маршрут. Если совместимый поставщик один, он выбирается автоматически. Резерв и финальное списание всё равно проверяются отдельно после создания.

curl --fail-with-body --get \
  'https://api.celestriagate.com/v1/media/models/schema' \
  -H "Authorization: Bearer $CELESTRIA_API_KEY" \
  --data-urlencode 'model=pixverse/swap' \
  --data-urlencode 'operation=video-to-video'

Отправьте один POST и сохраните ID

После схемы и оценки сохраните тело как request.json и выполните команду создания. Подставьте свой уникальный номер в Idempotency-Key. Ответ 202 возвращает object: media_generation и id. Сохраните его: это идентификатор последующей проверки, а не ссылка на готовый ролик. Успешная постановка в очередь ещё не означает завершение обработки.

Если соединение оборвалось, повторите тот же JSON с тем же ключом. Изменённое тело с прежним ключом вызывает конфликт, а новый ключ может создать ещё одну платную задачу. Смена режима или картинки — новая творческая попытка. Проверяйте существующий ID через GET /v1/media/generations/:id с паузами. Отдельный клиентский путь по имени поставщика не требуется.

curl --fail-with-body -X POST \
  'https://api.celestriagate.com/v1/media/generations' \
  -H "Authorization: Bearer $CELESTRIA_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_UNIQUE_ORDER_001' \
  --data-binary @request.json

Прочитайте статус, файл и окончательный расход

Пока статус queued, submitting, pending или in_progress, продолжайте опрос. awaiting_billing означает ожидание подтверждённой стоимости; создание нового заказа для этого не требуется. При completed берите result.video.url либо соответствующий файл из files. Тип content_type может отсутствовать: опирайтесь также на исходную схему результата и проверяйте загруженный файл.

Окончательное списание клиента находится в billing.cost_rub, расход поставщика — в billing.upstream_cost_usd. Сохраните их рядом с ID и ссылкой. При failed читайте error.code и error.message; перед новым запуском установите причину. Художественное качество оцените отдельно: непрерывность персонажа, края, контакт с поверхностями и звук. Мы не проводили платное испытание PixVerse Swap для этой инструкции.

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

Длительность, звук и стоимость

На 20 октября 2026 года поставщик публикует цену $0,15 за короткий ролик в 360p или 540p и $0,20 в 720p. Если вход длиннее пяти секунд, цена удваивается. Для первого опыта заранее подготовьте нужную длину. Просьба использовать короткий фрагмент, написанная вне JSON, не изменяет файл, который скачает провайдер.

keep_audio сохраняет звук исходника, если выбранная операция его поддерживает; он не создаёт новую речь или музыку. Gate сам переводит общую настройку в параметры совместимого поставщика. Прослушайте весь выход, включая начало и конец. Схема и тариф могут обновляться: сохраняйте дату проверки условий. Итоговую цену подтверждайте по completed, качество — реальным просмотром.

Частые вопросы

Почему нельзя передать prompt?

Для PixVerse Swap текстовая инструкция не нужна. В общем input передаются video_url, image_urls, resolution и keep_audio, а в parameters — mode и keyframe_id. Для редактирования по тексту выберите подходящую другую модель в том же API Gate.

keyframe_id: 24 — это двадцать четыре секунды?

Нет. После нормализации к двадцати четырём кадрам в секунду это примерно одна секунда. Номер кадра помогает выбрать видимый объект; длительность ролика он не задаёт.

Можно запросить 1080p?

Текущая схема перечисляет только 360p, 540p и 720p. Упоминание старшего размера в описании цены не делает его допустимым полем API. Перечитайте схему перед запуском.

Клиенту нужен отдельный ключ fal?

Нужны только ключ Celestria Gate и доступный баланс Gate. /v1/media автоматически выбирает совместимого поставщика. Даже для модели с единственным маршрутом клиент не меняет API и не передаёт секрет провайдера.

Источники

• PixVerse Swap API
• Цена PixVerse Swap
• Единый API Gate: модели, оценка и выбор провайдера