Higgsfield Soul 2 API

Higgsfield Soul 2 API

Higgsfield Soul 2 делает фотореалистичные портреты и fashion-снимки: человек в кадре, одежда, свет и атмосфера в духе модной съёмки, уличного фото или плёнки. Через API её удобно подключать к сервисам, где нужны портреты для карточек, лукбуки, обложки и картинки для соцсетей.

Два режима работы:

• По описанию (soul_mode: "text") - снимок с нуля по текстовому заданию.
• По фото (soul_mode: "image") - снимок по вашему портрету: нейросеть берёт фото за основу и делает новый кадр по заданию.

В обоих режимах можно выбрать один из 33 готовых стилей съёмки (style_id), разрешение 720p или 1080p, соотношение сторон и количество картинок - 1 или 4 за запуск.

Каждый вызов создаёт асинхронную операцию. После запуска нужно отдельно проверять статус по id.

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

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

Режимы:

• soul_mode: "text" - по описанию, нужен только prompt.
• soul_mode: "image" - по фото, нужны prompt и image_url.

Тело запроса

{
  "tool": "higgsfield-soul-2",
  "input": {
    "soul_mode": "text",
    "prompt": "...",
    "style_id": "3db34ab5-3439-4317-9e03-08dc30852e69",
    "resolution": "720p",
    "aspect_ratio": "3:4",
    "batch_size": "1"
  }
}

• tool - slug нейросети, всегда "higgsfield-soul-2".
• input - параметры запуска. Все поля передаются напрямую внутри этого объекта.
• Поля, которые вы не передали, получают значения по умолчанию: режим text, стиль «Обычный», 720p, 3:4, одна картинка.

Параметры

Стили

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

По описанию

Одна картинка 720p в обычном стиле.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "higgsfield-soul-2",
  "input": {
    "soul_mode": "text",
    "prompt": "Девушка в красном пальто на мокрой улице вечером, портрет по пояс, мягкий свет витрин",
    "style_id": "3db34ab5-3439-4317-9e03-08dc30852e69",
    "resolution": "720p",
    "aspect_ratio": "3:4",
    "batch_size": "1",
    "enhance_prompt": false
  }
}'

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-soul-2',
    input: {
      soul_mode: 'text',
      prompt: 'Девушка в красном пальто на мокрой улице вечером, портрет по пояс, мягкий свет витрин',
      style_id: '3db34ab5-3439-4317-9e03-08dc30852e69',
      resolution: '720p',
      aspect_ratio: '3:4',
      batch_size: '1',
      enhance_prompt: false,
    },
  }),
})

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-soul-2',
        'input': {
            'soul_mode': 'text',
            'prompt': 'Девушка в красном пальто на мокрой улице вечером, портрет по пояс, мягкий свет витрин',
            'style_id': '3db34ab5-3439-4317-9e03-08dc30852e69',
            'resolution': '720p',
            'aspect_ratio': '3:4',
            'batch_size': '1',
            'enhance_prompt': False,
        },
    },
    timeout=30,
)

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

По описанию: четыре варианта в 1080p

Четыре картинки за один запуск, стиль «Тёплая яркая плёнка», вертикальный кадр для сторис, короткое задание дополняется автоматически.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "higgsfield-soul-2",
  "input": {
    "soul_mode": "text",
    "prompt": "Мужчина в вязаном свитере с собакой у озера, осень, туман",
    "style_id": "dbaabc25-7fee-438c-bd65-ae4d1775d4ab",
    "resolution": "1080p",
    "aspect_ratio": "9:16",
    "batch_size": "4",
    "enhance_prompt": true
  }
}'

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-soul-2',
    input: {
      soul_mode: 'text',
      prompt: 'Мужчина в вязаном свитере с собакой у озера, осень, туман',
      style_id: 'dbaabc25-7fee-438c-bd65-ae4d1775d4ab',
      resolution: '1080p',
      aspect_ratio: '9:16',
      batch_size: '4',
      enhance_prompt: true,
    },
  }),
})

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-soul-2',
        'input': {
            'soul_mode': 'text',
            'prompt': 'Мужчина в вязаном свитере с собакой у озера, осень, туман',
            'style_id': 'dbaabc25-7fee-438c-bd65-ae4d1775d4ab',
            'resolution': '1080p',
            'aspect_ratio': '9:16',
            'batch_size': '4',
            'enhance_prompt': True,
        },
    },
    timeout=30,
)

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

По фото

Ваш портрет в image_url, стиль «Плёночная мыльница». Поле enhance_prompt в этом режиме не нужно.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "higgsfield-soul-2",
  "input": {
    "soul_mode": "image",
    "prompt": "Та же женщина в светлом плаще, летний вечер, тёплый свет",
    "image_url": "https://cdn.example.com/source-image-1.jpg",
    "style_id": "7ef8747e-c925-4851-b9e9-6400ddb19df9",
    "resolution": "1080p",
    "aspect_ratio": "3:4",
    "batch_size": "1"
  }
}'

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-soul-2',
    input: {
      soul_mode: 'image',
      prompt: 'Та же женщина в светлом плаще, летний вечер, тёплый свет',
      image_url: 'https://cdn.example.com/source-image-1.jpg',
      style_id: '7ef8747e-c925-4851-b9e9-6400ddb19df9',
      resolution: '1080p',
      aspect_ratio: '3:4',
      batch_size: '1',
    },
  }),
})

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-soul-2',
        'input': {
            'soul_mode': 'image',
            'prompt': 'Та же женщина в светлом плаще, летний вечер, тёплый свет',
            'image_url': 'https://cdn.example.com/source-image-1.jpg',
            'style_id': '7ef8747e-c925-4851-b9e9-6400ddb19df9',
            'resolution': '1080p',
            'aspect_ratio': '3:4',
            'batch_size': '1',
        },
    },
    timeout=30,
)

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

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

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

{
  "id": "op_uuid-123",
  "status": "queued",
  "tool": "higgsfield-soul-2",
  "cost": 0.5,
  "balance_after": 499.5,
  "created_at": "2026-10-21T12:00:00Z"
}

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

Одна картинка:

{
  "id": "op_uuid-123",
  "status": "completed",
  "tool": "higgsfield-soul-2",
  "cost": 0.5,
  "created_at": "2026-10-21T12:00:00Z",
  "completed_at": "2026-10-21T12:00:55Z",
  "result": {
    "type": "image",
    "urls": [
      "https://storage.bratuha.ru/results/higgsfield-soul-2/image-1.png"
    ]
  },
  "error_message": null
}

Четыре картинки (batch_size: "4"):

{
  "id": "op_uuid-456",
  "status": "completed",
  "tool": "higgsfield-soul-2",
  "cost": 3.5,
  "created_at": "2026-10-21T12:00:00Z",
  "completed_at": "2026-10-21T12:03:40Z",
  "result": {
    "type": "image",
    "urls": [
      "https://storage.bratuha.ru/results/higgsfield-soul-2/image-1.png",
      "https://storage.bratuha.ru/results/higgsfield-soul-2/image-2.png",
      "https://storage.bratuha.ru/results/higgsfield-soul-2/image-3.png",
      "https://storage.bratuha.ru/results/higgsfield-soul-2/image-4.png"
    ]
  },
  "error_message": null
}

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

После создания операции сохраните id из ответа и проверяйте статус отдельным запросом:

GET /api/v1/operations/{id}

cURL

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

JavaScript / TypeScript

const status = await fetch(
  'https://bratuha.ru/api/v1/operations/op_uuid-123',
  {
    headers: { Authorization: 'Bearer brth_ваш_ключ' },
  },
)

const result = await status.json()

Одна картинка обычно готова примерно за минуту, четыре в 1080p - за 3-4 минуты. Опрашивайте статус раз в 5-10 секунд.

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

{
  "type": "image",
  "urls": [
    "https://storage.bratuha.ru/results/higgsfield-soul-2/image-1.png"
  ]
}

• type - всегда "image".
• urls - массив ссылок на готовые картинки в PNG. При batch_size: "1" в массиве одна ссылка, при "4" - четыре.

Если операция завершилась с ошибкой, result будет null, а текст ошибки вернётся в error_message.

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

Цена зависит от разрешения и количества картинок. Режим, стиль, соотношение сторон и enhance_prompt на цену не влияют.

Итоговая сумма приходит в поле cost сразу в ответе на создание операции.

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

• POST /api/v1/operations не идемпотентен: повторный запрос создаёт новую операцию и списывает деньги ещё раз.
• Все операции выполняются асинхронно: сначала вы получаете queued, затем проверяете статус по id.
• Для image_url нужны внешние http/https URL с расширениями .jpg, .jpeg, .png, .webp.
• batch_size передаётся строкой: "1" или "4". Если нужно несколько вариантов, выгоднее один запуск с "4", чем четыре отдельных.
• style_id - передавайте только id из таблицы выше.
• В режиме image нейросеть сильно опирается на исходное фото: позу, кадр и фон она часто берёт оттуда, а смену сцены из задания может учесть лишь частично. Для новой сцены с нуля надёжнее режим text.
• В наших пробах при 3:4 картинка 720p получилась 1152×1536 пикселей, 1080p - 1536×2048.
• Задание лучше строить как описание кадра: кто в кадре, одежда, место, свет, план (по пояс, в полный рост). Буквы и надписи на фоне нейросеть рисует неразборчиво.