Замена человека в кадре

Некоторые модели не создают новую сцену, а заменяют человека: переносят лицо с одной фотографии на другую, меняют голову целиком или подставляют другую фигуру в видеоклипе. В каталоге они собраны под одной меткой — toolkit: "subject-swap" — и встречаются в двух формах: один вызов или два вызова с выбором посередине.

Больше в них ничего особенного нет. Это обычные асинхронные задачи, параметры берутся из собственного inputSchema модели, а результат приходит в output.assets[].

toolkit показывает, что модель из этого набора

toolkit — это классифицирующая метка на элементе каталога; она есть и в ответе GET /api/v1/models с аутентификацией, и в публичном каталоге. Сегодня у неё единственное значение subject-swap, а у моделей вне наборов поле отсутствует целиком, поэтому проверяйте значение, а не наличие ключа.

Поле носит справочный характер. Оно не определяет, каким ключом можно вызвать модель, как считается стоимость запроса и что модель принимает на вход. Незнакомое значение стоит воспринимать так же, как незнакомую запись в badges, — просто пропустить.

curl -s "https://api.spicyapi.ai/api/v1/models?modality=video" \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  | jq -r '.data.items[]
      | select(.toolkit == "subject-swap" and .enabled and .available)
      | [.model, (.tasks | join(",")), .family] | @tsv'

Каждая строка — один вызываемый эндпоинт. Всё остальное на этой странице определяет колонка tasks: family с эндпоинтом video-analyze — это family на два вызова, и парный к нему video-edit сам по себе не вызывается.

Какая форма передо мной

Обе формы работают в режиме async: true: вы создаёте задачу, а результат забираете опросом или через webhook.

Один вызов

Здесь нет ничего, что отличало бы такую модель от любой другой модели редактирования. Прочитайте inputSchema эндпоинта, заполните поля, создайте задачу:

const created = await fetch('https://api.spicyapi.ai/api/v1/jobs/createTask', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SPICY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-8814-swap-1',
  },
  body: JSON.stringify({
    model: swap.model, // один из элементов запроса к каталогу выше
    input: {
      image_url: 'spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3',
      reference_image_url: 'spicy://f/fil_01k3m8xb2c3d4e5f6g7h8j9k0m',
    },
  }),
});

Имена полей у эндпоинтов разные: одни принимают prompt, seed или формат вывода, другие — только две картинки. Список задаёт схема; не переносите имена полей с одного эндпоинта на другой. Референсом может быть публичный HTTPS-адрес, небольшое изображение в Base64 прямо в запросе или загруженный spicy:// URI — см. Медиа.

Два вызова

Первый вызов разбирает клип и сообщает, что он там нашёл, — упорядоченным набором кадров предпросмотра. Что из этого заменять, решаете вы. Саму работу делает второй вызов.

ваш клип ──▶ video-analyze ──▶ output.assets[0], [1], [2] …   (по кадру на каждую цель)
                                          │
                     вы выбираете позиции │ 0 и 2
                                          ▼
          video-edit (analysis_task_id + swap_targets) ──▶ готовый клип

Почему не одним вызовом? Потому что в сцене с четырьмя людьми один вызов вынужден был бы угадывать, кого вы имели в виду, а неверная догадка — это готовое оплаченное видео, в котором заменили не того человека. Разделение на два шага делает выбор явным и проверяемым.

const analysis = await createTask({
  model: analyze.model, // элемент, у которого в tasks есть "video-analyze"
  input: {
    video_url: 'spicy://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3',
    resolution: '720p',
  },
});
const analysisTaskId = analysis.taskId;

{
  "state": "succeeded",
  "output": {
    "assets": [
      { "url": "https://…", "expiresAt": "2026-09-20T09:32:11Z", "mime": "image/jpeg" },
      { "url": "https://…", "expiresAt": "2026-09-20T09:32:11Z", "mime": "image/jpeg" }
    ]
  },
  "settled": true
}

const swapped = await createTask({
  model: edit.model, // элемент "video-edit" того же family
  input: {
    analysis_task_id: analysisTaskId,
    resolution: '720p', // то же значение, с которым выполнялся разбор
    swap_targets: [
      { object_index: 0, image_urls: ['spicy://f/fil_01k3m8xb2c3d4e5f6g7h8j9k0m'] },
    ],
  },
});

Что второй вызов проверяет перед приёмом

Эти проверки выполняются при создании, поэтому отклонённый запрос ничего не создаёт и ничего не резервирует.

Когда второй вызов отклонён

Все эти случаи — HTTP 400 с бизнес-кодом code: 400. Поле msg принимает одно из значений:

Сколько стоят два вызова

Разбор и замена — это две отдельные задачи с двумя отдельными ценами, каждая со своим резервом и своим списанием. Отклонённый второй вызов не стоит ничего; успешный разбор оплачивается, даже если вы потом откажетесь что-либо заменять.

• Разбор обычно тарифицируется per_request: одно списание за вызов, независимо от длины клипа и количества найденных целей.
• Замена обычно тарифицируется per_second и считается целыми блоками, а длительность берётся из клипа, а не из поля, которое задаёте вы. Поэтому сумма, названная до отправки, рассчитана на самый длинный клип, который принимает эндпоинт: названная сумма и есть зарезервированная, итоговое списание считается по округлённой длительности и никогда не превышает резерв, а разница возвращается на баланс при закрытии задачи. Резерв, превышающий итоговое списание, здесь ожидаем. Прежде чем планировать бюджет, прочитайте Оплату.

Обе цены читайте из каталога, а не предполагайте, и, если важна точная сумма, запрашивайте расчёт стоимости для каждого вызова.

Дальше