Higgsfield Ads Studio API

Краткое практическое введение

Higgsfield Ads Studio превращает текстовый бриф в готовые рекламные баннеры. Вы описываете, что продаёте и какое у вас предложение, а нейросеть сама придумывает несколько разных рекламных концептов и рисует по баннеру на каждый - с заголовком, подписями и оформлением. Через API её удобно запускать для:

• баннеров и постов для соцсетей, сторис и рекламных кабинетов;
• карточек и обложек для маркетплейса с фото настоящего товара;
• быстрой проверки идей: 4-8 разных подач одного предложения за один запуск, чтобы выбрать лучшую или запустить A/B-тест.

Работает в двух сценариях: только по брифу (товар и сцену нейросеть рисует сама) или с вашими фото товара, упаковки или логотипа в image_urls. Каждый вызов создаёт асинхронную операцию: в ответ сразу приходят id и стартовый статус, а ссылки на готовые баннеры вы забираете запросом проверки статуса.

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

• Endpoint: POST /api/v1/operations
• Авторизация: Authorization: Bearer brth_...
• Запрос создаёт операцию и сразу возвращает id, стартовый статус и стоимость.
• Выполнение асинхронное. Обычно баннеры готовы через 2-4 минуты: чем больше batch_size, тем дольше.

Сценарии:

• по брифу - prompt, при желании niche и target_audience;
• с фото товара или логотипом - то же самое плюс от 1 до 10 ссылок в image_urls.

Тело запроса

Базовая форма запроса:

{
  "tool": "higgsfield-ads-studio",
  "input": {
    "prompt": "Кофейня у метро «Тёплый угол»: осеннее меню - тыквенный латте и яблочный пирог, скидка 20% до конца октября.",
    "language": "Russian",
    "batch_size": 2,
    "aspect_ratio": "1:1"
  }
}

• tool - slug нейросети, для этой модели всегда "higgsfield-ads-studio".
• input - параметры запуска. Поля передаются прямо внутри input, без дополнительной вложенности.
• Обязательно передать только prompt. Если не указать language, batch_size и aspect_ratio, сервер подставит Russian, 2 и 1:1.

Параметры

Размер баннеров - около 4 Мп (2K). Примеры из наших запусков: 1:1 - 2048×2048, 4:5 - 1792×2240, 9:16 - 1520×2688.

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

Сценарий 1. Баннеры только по брифу

Нейросеть сама рисует товар, сцену и надписи. Ниша и аудитория необязательны, но делают подачу точнее.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "higgsfield-ads-studio",
    "input": {
      "prompt": "Кофейня у метро «Тёплый угол»: осеннее меню - тыквенный латте и яблочный пирог, скидка 20% до конца октября.",
      "niche": "кофейни",
      "target_audience": "студенты и офисные работники 20-35 лет",
      "language": "Russian",
      "batch_size": 4,
      "aspect_ratio": "9:16"
    }
  }'

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-ads-studio',
    input: {
      prompt:
        'Кофейня у метро «Тёплый угол»: осеннее меню - тыквенный латте и яблочный пирог, скидка 20% до конца октября.',
      niche: 'кофейни',
      target_audience: 'студенты и офисные работники 20-35 лет',
      language: 'Russian',
      batch_size: 4,
      aspect_ratio: '9:16',
    },
  }),
})

const data = await response.json()
console.log(data)

Python

import requests

response = requests.post(
    "https://bratuha.ru/api/v1/operations",
    headers={
        "Authorization": "Bearer brth_ваш_ключ",
        "Content-Type": "application/json",
    },
    json={
        "tool": "higgsfield-ads-studio",
        "input": {
            "prompt": "Кофейня у метро «Тёплый угол»: осеннее меню - тыквенный латте и яблочный пирог, скидка 20% до конца октября.",
            "niche": "кофейни",
            "target_audience": "студенты и офисные работники 20-35 лет",
            "language": "Russian",
            "batch_size": 4,
            "aspect_ratio": "9:16",
        },
    },
    timeout=30,
)

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

Сценарий 2. Баннеры с фото товара и логотипом

Передайте ссылки на фото товара, упаковки или логотип - нейросеть построит концепты вокруг них. Главное фото товара ставьте первым.

cURL

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "higgsfield-ads-studio",
    "input": {
      "prompt": "Керамическая кружка ручной работы, глазурь цвета морской волны. Подарок к Новому году, доставка за 2 дня, цена 1490 ₽.",
      "image_urls": [
        "https://cdn.example.com/source-image-1.jpg",
        "https://cdn.example.com/logo-2.png"
      ],
      "niche": "товары для дома на маркетплейсе",
      "language": "Russian",
      "batch_size": 2,
      "aspect_ratio": "4:5"
    }
  }'

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-ads-studio',
    input: {
      prompt:
        'Керамическая кружка ручной работы, глазурь цвета морской волны. Подарок к Новому году, доставка за 2 дня, цена 1490 ₽.',
      image_urls: [
        'https://cdn.example.com/source-image-1.jpg',
        'https://cdn.example.com/logo-2.png',
      ],
      niche: 'товары для дома на маркетплейсе',
      language: 'Russian',
      batch_size: 2,
      aspect_ratio: '4:5',
    },
  }),
})

const data = await response.json()
console.log(data)

Python

import requests

response = requests.post(
    "https://bratuha.ru/api/v1/operations",
    headers={
        "Authorization": "Bearer brth_ваш_ключ",
        "Content-Type": "application/json",
    },
    json={
        "tool": "higgsfield-ads-studio",
        "input": {
            "prompt": "Керамическая кружка ручной работы, глазурь цвета морской волны. Подарок к Новому году, доставка за 2 дня, цена 1490 ₽.",
            "image_urls": [
                "https://cdn.example.com/source-image-1.jpg",
                "https://cdn.example.com/logo-2.png",
            ],
            "niche": "товары для дома на маркетплейсе",
            "language": "Russian",
            "batch_size": 2,
            "aspect_ratio": "4:5",
        },
    },
    timeout=30,
)

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

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

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

{
  "id": "7c1e4b92-3a5f-4d08-b6e2-9f0a1d3c5e47",
  "status": "queued",
  "tool": "higgsfield-ads-studio",
  "cost": 45.2,
  "balance_after": 454.8,
  "created_at": "2026-10-21T08:00:00.000Z"
}

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

Для batch_size = 4 в result.urls приходят четыре ссылки - по одной на каждый баннер:

{
  "id": "7c1e4b92-3a5f-4d08-b6e2-9f0a1d3c5e47",
  "status": "completed",
  "tool": "higgsfield-ads-studio",
  "cost": 45.2,
  "created_at": "2026-10-21T08:00:00.000Z",
  "completed_at": "2026-10-21T08:04:06.000Z",
  "result": {
    "type": "image",
    "urls": [
      "https://storage.bratuha.ru/results/higgsfield-ads-studio/banner-1.png",
      "https://storage.bratuha.ru/results/higgsfield-ads-studio/banner-2.png",
      "https://storage.bratuha.ru/results/higgsfield-ads-studio/banner-3.png",
      "https://storage.bratuha.ru/results/higgsfield-ads-studio/banner-4.png"
    ]
  },
  "error_message": null
}

Ответ при ошибке выполнения

{
  "id": "7c1e4b92-3a5f-4d08-b6e2-9f0a1d3c5e47",
  "status": "failed",
  "tool": "higgsfield-ads-studio",
  "cost": 45.2,
  "created_at": "2026-10-21T08:00:00.000Z",
  "completed_at": "2026-10-21T08:01:10.000Z",
  "result": null,
  "error_message": "Не удалось выполнить операцию"
}

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

Статус проверяется по id, который пришёл в ответ на создание операции. Сохраните его - без id результат конкретного запуска не получить. Баннеры рисуются несколько минут, поэтому опрашивать удобно раз в 10-15 секунд, пока статус не станет completed или failed.

cURL

curl -H "Authorization: Bearer brth_ваш_ключ" \
  https://bratuha.ru/api/v1/operations/7c1e4b92-3a5f-4d08-b6e2-9f0a1d3c5e47

JavaScript / TypeScript

const operationId = '7c1e4b92-3a5f-4d08-b6e2-9f0a1d3c5e47'

const response = await fetch(
  `https://bratuha.ru/api/v1/operations/${operationId}`,
  {
    headers: {
      Authorization: 'Bearer brth_ваш_ключ',
    },
  },
)

const operation = await response.json()
console.log(operation.status, operation.result?.urls)

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

После успешного выполнения в result приходит объект с массивом изображений:

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

• urls - массив ссылок на готовые баннеры. Их столько, сколько вы указали в batch_size: от 1 до 8.
• Каждый баннер - отдельный концепт со своей идеей, композицией и текстом, а не вариация одной картинки.
• Все баннеры одного запуска в одних пропорциях из aspect_ratio, размер около 4 Мп, формат PNG.
• Надписи уже нарисованы на изображении, отдельным текстом или слоями они не возвращаются.

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

Цена зависит только от batch_size: первый баннер стоит 17 ₽, каждый следующий - 9,4 ₽. Пропорции, язык, ниша, аудитория и количество фото в image_urls цену не меняют.

Формула: 17 + 9,4 × (batch_size - 1) ₽. Стоимость списывается при создании операции, точная сумма приходит в поле cost ответа.

Примеры:

• один баннер 1:1 по брифу - 17 ₽;
• четыре сторис 9:16 с фото товара - 45,2 ₽;
• восемь баннеров для A/B-теста - 82,8 ₽.

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

• POST /api/v1/operations не идемпотентен: повтор запроса без заголовка Idempotency-Key создаёт новую операцию и снова списывает стоимость. Передайте UUID в Idempotency-Key, и повтор того же запроса в течение 24 часов вернёт исходную операцию.
• Чтобы не запустить дороже, чем ожидаете, передайте в теле запроса max_price: сервер отклонит запуск дороже этой суммы до списания.
• Операция выполняется асинхронно - готовых баннеров в ответе на POST нет, используйте GET /api/v1/operations/{id}.
• Для image_urls нужны внешние http/https URL, доступные из интернета. Локальные пути, localhost, blob: и data: не подходят. Не больше 10 ссылок, форматы .jpg, .jpeg, .png, .webp.
• Текст на баннерах нейросеть пишет сама по брифу. Если важна точная формулировка, цена или адрес - напишите их в prompt дословно и проверьте результат перед публикацией.
• С фото товара результат бывает без надписей - например, коллаж из нескольких кадров товара. Если надпись обязательна, прямо попросите её в брифе.
• Бриф пишите про товар и предложение, а не про картинку: композицию, стиль и формулировки нейросеть подбирает сама, и при batch_size больше 1 все концепты получаются разными.