Higgsfield Genjutsu Light API

Higgsfield Genjutsu Light API

Higgsfield Genjutsu Light - облегчённая версия Higgsfield Genjutsu для коротких роликов. Она берёт готовое видео от 4 до 15 секунд и сохраняет его движение, ракурс и монтаж, а меняет то, что вы попросите:

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

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

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

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

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

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

Тело запроса

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

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

Параметры

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

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

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

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "higgsfield-genjutsu-light",
  "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-light',
    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-light',
        '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, стоимость - 140 ₽.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "higgsfield-genjutsu-light",
  "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-light',
    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-light',
        '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())

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

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

{
  "id": "op_uuid-123",
  "status": "queued",
  "tool": "higgsfield-genjutsu-light",
  "cost": 84,
  "balance_after": 916,
  "created_at": "2026-10-22T13:45:02Z"
}

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

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

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

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

{
  "id": "op_uuid-123",
  "status": "failed",
  "tool": "higgsfield-genjutsu-light",
  "cost": 84,
  "created_at": "2026-10-22T13:45:02Z",
  "completed_at": "2026-10-22T13:51:40Z",
  "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-8 секунд в 480p и 720p были готовы за 6-10 минут в обоих режимах. Длинные ролики и 1080p обрабатываются дольше, закладывайте до получаса. Опрашивать статус раз в 10-15 секунд достаточно, чаще раза в секунду нельзя - придёт 429.

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

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

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

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

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

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

Цена - за каждую секунду исходного видео, ставка зависит только от resolution:

Длительность сервер сам определяет по файлу и округляет вверх до целой секунды: ролик 8,1 секунды считается как 9 секунд. Минимум - 4 секунды, максимум - 15 секунд.

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

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

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