API Bratuha.ru

Public API Bratuha.ru позволяет запускать нейросети по HTTP без cookie-сессии и без ручной работы в интерфейсе. Интеграция строится вокруг асинхронных операций: вы отправляете запрос на запуск, получаете id операции и затем проверяете её состояние отдельным запросом. Для ИИ-агентов доступны поиск нейросетей, машиночитаемые схемы, оценка цены, временная загрузка файлов и MCP.

Какие маршруты доступны

• POST /api/v1/operations — создать новую операцию.
• GET /api/v1/operations/{id} — проверить статус и получить результат конкретной операции.
• GET /api/v1/tools — найти нейросеть с открытым API.
• GET /api/v1/tools/{slug}/schema — получить JSON Schema параметров.
• POST /api/v1/operations/estimate — узнать точную цену до списания.
• POST /api/v1/uploads и /uploads/presign — загрузить временный входной файл.

Нужна настройка Claude Code, Codex, Cursor или MCP? Откройте Братуха для ИИ-агентов.

Для кого это подходит

• для ботов и внутренних сервисов;
• для CRM, no-code и серверных интеграций;
• для продуктов, которым нужно запускать конкретные нейросети по известному slug;

Что понадобится перед первой интеграцией

1. Зарегистрируйтесь в Bratuha.ru и при необходимости пополните баланс.
2. Создайте API-ключ в кабинете.
3. Найдите нейросеть через GET /api/v1/tools.
4. Прочитайте её JSON Schema через GET /api/v1/tools/{slug}/schema.

Авторизация

• Заголовок: Authorization: Bearer brth_...
• Полный API-ключ показывается только один раз в момент создания.
• Управление ключами выполняется через страницу аккаунта, а не через Public API.

Базовый URL

https://bratuha.ru/api/v1

Где смотреть документацию по конкретной нейросети

1. Запросите GET /api/v1/tools: он возвращает только доступные вашему ключу нейросети.
2. Прочитайте GET /api/v1/tools/{slug}/schema перед составлением запроса.
3. HTML-описание остаётся на странице вида /tools/[slug]/api; markdown — на /tools/[slug]/api.md.

Закрытая или несовместимая нейросеть не попадает в агентский каталог и отвечает как несуществующая.

Общая модель работы

Все операции асинхронные. POST /api/v1/operations не ждёт финальный результат и не держит соединение до конца генерации. Он только создаёт задачу, возвращает её идентификатор и стартовое состояние.

Жизненный цикл операции

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

Как выглядит рабочий цикл интеграции

1. Клиент отправляет POST /api/v1/operations.
2. Сервер создаёт операцию и возвращает id, status, стоимость и время создания.
3. Клиент сохраняет id у себя.
4. Затем клиент делает периодический опрос через GET /api/v1/operations/{id}.
5. Когда статус становится completed, результат можно забирать из поля result.
6. Если статус failed, причину нужно читать из error_message.

Ограничение частоты опроса

Одну и ту же операцию можно проверять не чаще 1 раза в секунду. При более частом опросе сервер вернет 429 с заголовком Retry-After: 1 и кодом rate_limit_exceeded. Ограничение привязано к конкретной операции: параллельный опрос разных операций не блокируется.

Что важно понимать про идентификатор операции

• id операции нужно сохранять на стороне вашего клиента или серверного сервиса сразу после создания.
• Если вы хотите позже показывать пользователю статус операции, сохраните id вместе со своими метаданными в собственной базе.

Формат тела запроса

{
  "tool": "tool-slug",
  "input": {
    "field": "value"
  }
}

Что означает каждое поле

• tool — slug нейросети, который вы берёте со страницы /tools/[slug]/api.
• input — объект параметров для конкретной нейросети.
• Набор полей внутри input всегда зависит от выбранного инструмента.
• Если на странице документации параметр помечен как необязательный, его можно не передавать.

Повторы и предел цены

• Без заголовка Idempotency-Key каждый успешный повторный запрос создаёт новую операцию. Если пользователь может нажать кнопку несколько раз, защитите форму от повторного submit или передавайте ключ.
• С заголовком Idempotency-Key (строка от 1 до 255 символов, обычно UUID) повтор с тем же телом в течение 24 часов возвращает ту же операцию с заголовком Idempotent-Replayed: true и без второго списания. Тот же ключ с другим телом — 409 idempotency_conflict.
• Необязательное поле max_price в теле — предел цены в рублях: если точная стоимость выше, сервер ответит 400 и ничего не создаст.

Что делать при ошибке 503

• Ответ 503 с кодом service_unavailable означает временную нагрузку на базу: операция не создана и средства не списаны.
• Такой запрос нужно повторить через время из заголовка Retry-After.
• Остальные коды повторять автоматически не нужно: 4xx требуют исправить запрос, а 500 стоит сообщить в поддержку.
• 500 на создании операции повторять особенно не стоит: в редком случае обрыва связи операция могла успеть создаться, и повтор оплатит её второй раз. Сверьтесь со списком операций или напишите в поддержку с request_id.
• В каждом ответе есть X-Request-Id, а в теле ошибки — error.request_id. Сохраняйте его и присылайте в поддержку: по нему мы находим конкретный запрос в логах.
• Запросы можно отправлять параллельно: всплеск из 25 одновременных запросов по одному ключу проходит за 0.7 секунды в худшем случае. Специально ограничивать параллельность не нужно — достаточно соблюдать Retry-After, если всё же пришёл 503.

URL файлов

Если нейросеть принимает файлы, в Public API нужно передавать публичные URL, доступные извне.

Ограничения

• Только http и https.
• Нельзя передавать localhost, loopback и private IP.
• URL должен соответствовать допустимым расширениям поля.
• Public API не принимает локальные пути, blob:, data: и другие не-внешние ссылки.

Практика

• Для множественных image/file-полей передавайте массив URL.
• Для проверки статуса используйте периодический опрос с паузой 2-5 секунд и ограничением по числу попыток. Запросы чаще 1 раза в секунду к одной операции будут отклонены с кодом 429.
• Для повторной попытки сначала анализируйте error.code и error_message, а не повторяйте запрос вслепую.
• Если файл хранится во внутреннем хранилище, сначала опубликуйте временный внешний URL, а уже потом отправляйте запрос в Bratuha.ru.

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

curl -X POST https://bratuha.ru/api/v1/operations \
  -H "Authorization: Bearer brth_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "tool-slug",
    "input": {
      "image_url": "https://cdn.example.com/source.jpg",
      "prompt": "Сделай изображение более кинематографичным"
    }
  }'

Создание операции: 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: 'tool-slug',
    input: {
      image_url: 'https://cdn.example.com/source.jpg',
      prompt: 'Сделай изображение более кинематографичным',
    },
  }),
})

const data = await response.json()

if (!response.ok) {
  throw new Error(data.error?.message ?? 'Не удалось создать операцию')
}

const operationId = data.id

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

import requests

response = requests.post(
    "https://bratuha.ru/api/v1/operations",
    headers={
        "Authorization": "Bearer brth_ваш_ключ",
        "Content-Type": "application/json",
    },
    json={
        "tool": "tool-slug",
        "input": {
            "image_url": "https://cdn.example.com/source.jpg",
            "prompt": "Сделай изображение более кинематографичным",
        },
    },
    timeout=30,
)

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

Пример ответа на создание

{
  "id": "9f4d2f65-4b2c-4df8-bf2a-9c6e8b86b352",
  "status": "queued",
  "tool": "tool-slug",
  "cost": 6,
  "balance_after": 194,
  "created_at": "2026-03-13T12:34:56.000Z"
}

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

curl -H "Authorization: Bearer brth_ваш_ключ" \
  https://bratuha.ru/api/v1/operations/9f4d2f65-4b2c-4df8-bf2a-9c6e8b86b352

Проверка статуса: JavaScript / TypeScript

const response = await fetch(
  'https://bratuha.ru/api/v1/operations/9f4d2f65-4b2c-4df8-bf2a-9c6e8b86b352',
  {
    headers: {
      Authorization: 'Bearer brth_ваш_ключ',
    },
  },
)

const data = await response.json()

if (!response.ok) {
  throw new Error(data.error?.message ?? 'Не удалось получить статус')
}

if (data.status === 'completed') {
  console.log(data.result)
}

Пример ответа со статусом completed

{
  "id": "9f4d2f65-4b2c-4df8-bf2a-9c6e8b86b352",
  "status": "completed",
  "tool": "tool-slug",
  "cost": 6,
  "created_at": "2026-03-13T12:34:56.000Z",
  "completed_at": "2026-03-13T12:35:18.000Z",
  "result": {
    "type": "image",
    "images": [
      "https://cdn.bratuha.ru/results/example-image-1.jpg"
    ]
  },
  "error_message": null
}

Практические рекомендации

• Сохраняйте id операции сразу после ответа на create-запрос.
• Делайте периодический опрос с интервалом 2-5 секунд, а не непрерывные запросы без паузы. Минимальный допустимый интервал - 1 секунда (при более частых запросах сервер вернет 429).
• Ставьте верхнюю границу по времени ожидания на стороне клиента.
• Для повторных попыток разделяйте сетевые ошибки и бизнес-ошибки API.
• Не показывайте пользователю кнопку повторного запуска, пока предыдущий create-запрос ещё в полёте.
• Логируйте у себя tool, operation id, HTTP-статус и error.code, чтобы потом было проще разбирать инциденты.

Когда API недоступен

• Если slug указан с ошибкой, API вернёт 404 tool_not_found.
• Если Public API у нейросети выключен, ответ будет таким же: 404 tool_not_found.
• Если схема нейросети пока несовместима с Public API, публично это тоже выглядит как 404 tool_not_found.