Higgsfield Genjutsu API

Higgsfield Genjutsu API

Higgsfield Genjutsu меняет готовое видео, сохраняя движение, ракурс и монтаж исходника. На входе всегда ролик от 4 до 30 секунд, дальше выбирается, что с ним сделать:

• перенести движение на своего персонажа - человек, животное или маскот с фото повторяет танец, жест или проходку из видео;
• заменить предмет в кадре - кружка вместо стакана, ваш товар вместо чужого, другая одежда на герое;
• перерисовать весь ролик в другом стиле - аниме, пластилин, вязаные игрушки, пиксель-арт и ещё 16 готовых стилей.

Платите за секунды исходного видео, ставка зависит от разрешения. Вызов создаёт асинхронную операцию: сначала приходит id, затем вы проверяете статус, пока не будет готово видео.

Создание операции

• Endpoint: POST /api/v1/operations
• Авторизация: Authorization: Bearer brth_...
• Выполнение асинхронное: запрос сразу возвращает id и стартовый статус queued.

Режим выбирается параметром genjutsu_mode:

Если genjutsu_mode не передать, будет motion_transfer. У каждого режима своё поле задания и свой набор файлов, смотрите таблицу параметров. Поля другого режима передавать не нужно, они не учитываются.

Тело запроса

{
  "tool": "higgsfield-genjutsu",
  "input": {
    "genjutsu_mode": "motion_transfer",
    "...": "..."
  }
}

• tool - slug нейросети, всегда "higgsfield-genjutsu".
• input - параметры запуска. Все поля передаются прямо внутри этого объекта, вложенных объектов нет.

Параметры

Стили для restyle

Примеры запросов

Перенос движения (motion_transfer)

Енот с фото повторяет танец девушки из 6-секундного ролика. Два фото - сам енот и его куртка. 480p, стоимость - 138 ₽.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "higgsfield-genjutsu",
  "input": {
    "genjutsu_mode": "motion_transfer",
    "video_url": "https://cdn.example.com/source-video-1.mp4",
    "image_urls": [
      "https://cdn.example.com/source-image-1.jpg",
      "https://cdn.example.com/source-image-2.jpg"
    ],
    "prompt_motion": "Енот с фото 1 в куртке с фото 2 повторяет танец из видео в той же студии.",
    "resolution": "480p"
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'higgsfield-genjutsu',
    input: {
      genjutsu_mode: 'motion_transfer',
      video_url: 'https://cdn.example.com/source-video-1.mp4',
      image_urls: [
        'https://cdn.example.com/source-image-1.jpg',
        'https://cdn.example.com/source-image-2.jpg',
      ],
      prompt_motion: 'Енот с фото 1 в куртке с фото 2 повторяет танец из видео в той же студии.',
      resolution: '480p',
    },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'higgsfield-genjutsu',
        'input': {
            'genjutsu_mode': 'motion_transfer',
            'video_url': 'https://cdn.example.com/source-video-1.mp4',
            'image_urls': [
                'https://cdn.example.com/source-image-1.jpg',
                'https://cdn.example.com/source-image-2.jpg',
            ],
            'prompt_motion': 'Енот с фото 1 в куртке с фото 2 повторяет танец из видео в той же студии.',
            'resolution': '480p',
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Замена объекта (object_swap)

В 5-секундном ролике по луже плывёт бумажный кораблик, его меняем на кружку с фото. 720p, стоимость - 240 ₽.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "higgsfield-genjutsu",
  "input": {
    "genjutsu_mode": "object_swap",
    "video_url": "https://cdn.example.com/source-video-2.mp4",
    "image_urls": [
      "https://cdn.example.com/source-image-3.png",
      "https://cdn.example.com/source-image-4.png"
    ],
    "prompt_swap": "Замени бумажный кораблик на кружку с фото 1, она так же плывёт по луже. Узор кружки - как на фото 2, остальное не меняй.",
    "resolution": "720p"
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'higgsfield-genjutsu',
    input: {
      genjutsu_mode: 'object_swap',
      video_url: 'https://cdn.example.com/source-video-2.mp4',
      image_urls: [
        'https://cdn.example.com/source-image-3.png',
        'https://cdn.example.com/source-image-4.png',
      ],
      prompt_swap: 'Замени бумажный кораблик на кружку с фото 1, она так же плывёт по луже. Узор кружки - как на фото 2, остальное не меняй.',
      resolution: '720p',
    },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'higgsfield-genjutsu',
        'input': {
            'genjutsu_mode': 'object_swap',
            'video_url': 'https://cdn.example.com/source-video-2.mp4',
            'image_urls': [
                'https://cdn.example.com/source-image-3.png',
                'https://cdn.example.com/source-image-4.png',
            ],
            'prompt_swap': 'Замени бумажный кораблик на кружку с фото 1, она так же плывёт по луже. Узор кружки - как на фото 2, остальное не меняй.',
            'resolution': '720p',
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Смена стиля без фото персонажей (restyle)

Тот же танец, перерисованный в стиле «Вязаный мир»: девушка и комната становятся связанными из пряжи. Исходник - MOV с телефона, 6 секунд, 480p, стоимость - 270 ₽.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "higgsfield-genjutsu",
  "input": {
    "genjutsu_mode": "restyle",
    "video_url": "https://cdn.example.com/source-video-3.mov",
    "preset_id": "2b5b68c4-9253-4d79-9d05-81e7718d8d7a",
    "resolution": "480p"
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'higgsfield-genjutsu',
    input: {
      genjutsu_mode: 'restyle',
      video_url: 'https://cdn.example.com/source-video-3.mov',
      preset_id: '2b5b68c4-9253-4d79-9d05-81e7718d8d7a',
      resolution: '480p',
    },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'higgsfield-genjutsu',
        'input': {
            'genjutsu_mode': 'restyle',
            'video_url': 'https://cdn.example.com/source-video-3.mov',
            'preset_id': '2b5b68c4-9253-4d79-9d05-81e7718d8d7a',
            'resolution': '480p',
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Смена стиля с фото персонажей (restyle + restyle_image_urls)

Ролик из двух героев в стиле «Аниме в 3D», внешность героев задаём фотографиями, а в задании просим держать детали. 10 секунд, 1080p, стоимость - 2290 ₽.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "higgsfield-genjutsu",
  "input": {
    "genjutsu_mode": "restyle",
    "video_url": "https://cdn.example.com/source-video-4.mp4",
    "preset_id": "c2143317-f28d-4c3c-a0b8-39bd547e08a7",
    "restyle_image_urls": [
      "https://cdn.example.com/source-image-5.jpg",
      "https://cdn.example.com/source-image-6.jpg"
    ],
    "prompt_restyle": "Девушка слева - героиня с фото 1, парень справа - герой с фото 2. Розовые волосы девушки одинаковые во всех кадрах.",
    "resolution": "1080p"
  }
}'

JavaScript / TypeScript

const response = await fetch('https://bratuha.ru/api/v1/operations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer brth_ваш_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tool: 'higgsfield-genjutsu',
    input: {
      genjutsu_mode: 'restyle',
      video_url: 'https://cdn.example.com/source-video-4.mp4',
      preset_id: 'c2143317-f28d-4c3c-a0b8-39bd547e08a7',
      restyle_image_urls: [
        'https://cdn.example.com/source-image-5.jpg',
        'https://cdn.example.com/source-image-6.jpg',
      ],
      prompt_restyle: 'Девушка слева - героиня с фото 1, парень справа - герой с фото 2. Розовые волосы девушки одинаковые во всех кадрах.',
      resolution: '1080p',
    },
  }),
})

const data = await response.json()

Python

import requests

response = requests.post(
    'https://bratuha.ru/api/v1/operations',
    headers={
        'Authorization': 'Bearer brth_ваш_ключ',
        'Content-Type': 'application/json',
    },
    json={
        'tool': 'higgsfield-genjutsu',
        'input': {
            'genjutsu_mode': 'restyle',
            'video_url': 'https://cdn.example.com/source-video-4.mp4',
            'preset_id': 'c2143317-f28d-4c3c-a0b8-39bd547e08a7',
            'restyle_image_urls': [
                'https://cdn.example.com/source-image-5.jpg',
                'https://cdn.example.com/source-image-6.jpg',
            ],
            'prompt_restyle': 'Девушка слева - героиня с фото 1, парень справа - герой с фото 2. Розовые волосы девушки одинаковые во всех кадрах.',
            'resolution': '1080p',
        },
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

Примеры ответов

Ответ после создания

{
  "id": "op_uuid-123",
  "status": "queued",
  "tool": "higgsfield-genjutsu",
  "cost": 270,
  "balance_after": 730,
  "created_at": "2026-10-20T13:45:02Z"
}

• cost - сколько списано за операцию, в рублях.
• balance_after - баланс после списания.

Ответ после завершения

{
  "id": "op_uuid-123",
  "status": "completed",
  "tool": "higgsfield-genjutsu",
  "cost": 270,
  "created_at": "2026-10-20T13:45:02Z",
  "completed_at": "2026-10-20T13:51:02Z",
  "result": {
    "type": "video",
    "urls": [
      "https://storage.bratuha.ru/results/higgsfield-genjutsu/video-1.mp4"
    ]
  },
  "error_message": null
}

Ответ при ошибке

{
  "id": "op_uuid-123",
  "status": "failed",
  "tool": "higgsfield-genjutsu",
  "cost": 270,
  "created_at": "2026-10-20T13:45:02Z",
  "completed_at": "2026-10-20T13:52:59Z",
  "result": null,
  "error_message": "Ваш запрос не прошел модерацию. Запрещено: nsfw."
}

Деньги за операцию со статусом failed возвращаются на баланс.

Проверка статуса

Сохраните id из ответа на создание и запрашивайте статус операции по нему:

GET /api/v1/operations/{id}

curl -H "Authorization: Bearer brth_ваш_ключ" \
  https://bratuha.ru/api/v1/operations/op_uuid-123

async function waitForResult(id) {
  while (true) {
    const response = await fetch(`https://bratuha.ru/api/v1/operations/${id}`, {
      headers: { Authorization: 'Bearer brth_ваш_ключ' },
    })
    const operation = await response.json()
    if (operation.status === 'completed' || operation.status === 'failed') {
      return operation
    }
    await new Promise((resolve) => setTimeout(resolve, 15000))
  }
}

Статус операции:

• queued - операция создана и ждёт запуска;
• processing - видео обрабатывается;
• completed - готово, ссылка лежит в result;
• failed - не получилось, причина в error_message.

В наших запусках ролики по 5-6 секунд в 480p были готовы за 6-7 минут во всех трёх режимах. Длинные ролики и 1080p обрабатываются дольше, закладывайте до получаса. Опрашивать статус раз в 10-15 секунд достаточно, чаще раза в секунду нельзя - придёт 429.

Формат результата

Во всех режимах результат - одно видео MP4:

{
  "type": "video",
  "urls": [
    "https://storage.bratuha.ru/results/higgsfield-genjutsu/video-1.mp4"
  ]
}

• type - всегда "video".
• urls - массив из одной ссылки на готовый файл.

Пропорции кадра повторяют исходник, а высота кадра соответствует resolution: вертикальный ролик 704×1280 в 480p вернулся как 474×862, горизонтальный 960×540 - как 854×480. Звук исходника сохраняется. Длина результата близка к исходнику, но может быть короче на долю секунды: 6-секундный ролик вернулся длиной 5,7 секунды.

Ценообразование

Цена - за каждую секунду исходного видео. Ставка зависит от режима и resolution:

Длительность сервер сам определяет по файлу и округляет вверх до целой секунды: ролик 8,1 секунды считается как 9 секунд. Минимум - 4 секунды (92 ₽ за перенос или замену в 480p), максимум - 30 секунд.

Задание, число фото и выбранный стиль на цену не влияют. Точная сумма приходит в поле cost ответа на создание операции и сразу списывается с баланса. Ставки могут меняться - перед массовыми запусками сверяйтесь с cost или передавайте max_price.

Ограничения и практические заметки

• POST /api/v1/operations не идемпотентен: каждый запрос создаёт новую операцию и списывает деньги. Чтобы безопасно повторять запрос при обрыве связи, передайте UUID в заголовке Idempotency-Key: повтор в течение 24 часов вернёт исходную операцию без нового списания.
• Передайте max_price в теле запроса, если хотите, чтобы сервер отклонил запуск дороже согласованной суммы ещё до списания. Полезно для 1080p: 30 секунд смены стиля стоят 6870 ₽.
• Операция выполняется асинхронно: сначала приходит queued, результат нужно забирать запросом статуса по id.
• Файлы передаются только ссылками: внешние http/https URL, которые открываются без авторизации. Видео - .mp4 или .mov до 100 МБ, фото - .jpg, .jpeg, .png, .webp.
• Длину видео сервер проверяет ещё до создания операции. Если файл недоступен, его длину не удалось определить или она вне пределов от 4 до 30 секунд, API вернёт ошибку 400, операция не создастся и деньги не спишутся.
• Для object_swap в кадре исходника нужно не меньше 409 600 пикселей: 854×480, 640×640 или больше. Ролик меньшего размера модель не примет, операция завершится ошибкой с возвратом денег.
• В заданиях ссылайтесь на фото по порядку: «персонаж с фото 1», «предмет с фото 2». Порядок фото в массиве сохраняется.
• Модерация видео строгая. Замена человека в кадре (object_swap) иногда отклоняется как nsfw даже без откровенного содержания - деньги за такую операцию возвращаются. Замена предметов, перенос движения на животное и смена стиля ролика с человеком в наших запусках прошли без отказов.
• Список стилей для restyle может обновляться. Если стиль пропал, операция завершится ошибкой, а деньги вернутся.
• Одна операция - один результат. Для нескольких вариантов создайте несколько операций.