Братуха для ИИ-агентов

Агент — Claude Code, Codex, Cursor, Claude Desktop, OpenCode или ваш собственный скрипт — получает доступ к Братухе через обычный API-ключ. Дальше он работает так же, как человек на сайте, только без интерфейса:

1. находит нужную нейросеть в каталоге (GET /tools);
2. читает её схему: какие поля есть, что обязательно, какие файлы принимаются (GET /tools/{slug}/schema);
3. при необходимости загружает файл во временное хранилище (POST /uploads);
4. узнаёт точную цену до списания (POST /operations/estimate);
5. запускает операцию с ограничением цены и ключом повтора (POST /operations);
6. ждёт результат (GET /operations/{id}) и скачивает файлы по ссылкам.

Списание идёт с вашего баланса Братухи. Три предохранителя защищают бюджет: серверный предел цены max_price, защита от повторного запуска Idempotency-Key и лимит трат на ключ в сутки и в месяц.

Чат-модели (GPT, Claude, Gemini, Grok, Qwen, DeepSeek) доступны тем же ключом через OpenAI- и Anthropic-совместимые эндпоинты, поэтому Claude Code и Codex могут работать на моделях Братухи целиком, без аккаунтов у зарубежных поставщиков.

1. Откройте настройки API и создайте отдельный ключ для агента — так его легко отозвать, а траты видны отдельно.
2. Полный ключ brth_... показывается один раз. Сохраните его в менеджере секретов или переменной окружения, не в файле проекта и не в чате с агентом.
3. Нажмите «Лимиты» у ключа и задайте предел трат в сутки и в месяц. Когда лимит исчерпан, ключ перестаёт запускать генерации и чат до начала следующих суток или месяца; деньги при отказе не списываются. Сутки считаются с 03:00 по московскому времени.

Все инструкции ниже ожидают, что ключ лежит в переменной окружения BRATUHA_API_KEY:

Способы можно сочетать: например, скилл для правил работы и MCP для инструментов.

Скиллы — это инструкции в формате Agent Skills, которые агент читает перед работой. Установщик находит их по адресу https://bratuha.ru/.well-known/agent-skills/index.json и ставит в папку скиллов вашего агента (Claude Code, Codex, Cursor и другие поддерживаемые клиенты).

Устанавливаются два скилла:

• bratuha-media — нейросети изображений, видео, аудио и 3D: обязательный порядок «каталог → схема → оценка → запуск с max_price и Idempotency-Key → ожидание результата», правило подтверждать запуск дороже 100 ₽, если бюджет не задан, и разбор ошибок API.
• bratuha-chat-agents — подключение чат-моделей Братухи к Claude Code, Codex, OpenCode, Cline и Roo Code и типичные ошибки настройки.

После установки скажите агенту, что хотите, например: «Сделай озвучку этого текста через Братуху и сохрани в папку audio». Агент сам найдёт нейросеть, покажет цену и спросит подтверждение.

Скиллы читают ключ только из BRATUHA_API_KEY. Перезапустите агент из терминала, где эта переменная задана.

MCP-сервер работает по протоколу Streamable HTTP без сессий и без OAuth: ключ передаётся заголовком Authorization: Bearer brth_.... Каждый инструмент — тонкая обёртка над соответствующим маршрутом HTTP API, поэтому цены, проверки и лимиты у них общие.

Ответ маршрута с ошибкой приходит агенту как ошибка инструмента, а не как результат, поэтому агент не примет отказ за успех.

Один ключ открывает три совместимых эндпоинта. Список моделей и их цены за миллион токенов — GET /api/v1/models; не берите названия моделей из памяти, они меняются.

Списание — по фактическим токенам после ответа. Перед запросом резервируется оценка стоимости; если на балансе или в лимите ключа её нет, запрос отклоняется до обращения к модели.

Базовый адрес — https://bratuha.ru/api/v1, авторизация — заголовок Authorization: Bearer brth_.... Все ответы и ошибки — JSON. Машиночитаемые версии документации: /developers/api.md и /tools/{slug}/api.md для каждой нейросети, краткая карта сайта для моделей — /llms.txt.

Ниже — полный цикл с реальными формами ответов. Полный HTTP-контракт операций, формат ошибок и примеры на cURL есть на странице Public API.

1. Найти нейросеть

GET /tools?q=&kind=&category= — только нейросети с открытым API. q ищет подстроку в slug, названии, описании, провайдере и категориях; kind — тип результата (image, video, audio, text); category — имя или подпись категории каталога (lip-sync, video-from-images, image-3d, «Липсинк»).

{
  "object": "list",
  "data": [
    {
      "slug": "kling-3-0",
      "name": "Kling 3.0",
      "description": "…",
      "provider": "…",
      "categories": ["video", "video-from-images", "kling"],
      "output_types": ["video"],
      "pricing": { "type": "variable", "from": 11, "currency": "RUB" },
      "runtime": {
        "requests_24h": 120, "success_rate_24h": 97.5,
        "median_duration_ms_24h": 180000
      },
      "schema_url": "/api/v1/tools/kling-3-0/schema",
      "documentation_url": "/tools/kling-3-0/api"
    }
  ]
}

pricing.from — цена «от»; точная цена зависит от параметров и считается оценкой. runtime — живая статистика запусков за сутки и неделю, по ней агент может выбрать более быструю или стабильную нейросеть.

2. Прочитать схему

GET /tools/{slug}/schema возвращает input_schema (JSON Schema 2020-12), pricing, example_input и documentation_markdown. Схема — единственный источник допустимых полей: не подставляйте параметры по памяти.

Расширения x-bratuha-* в схеме:

• x-bratuha-file-kind и x-bratuha-extensions — какой файл ждёт поле (image, video, audio, file) и допустимые расширения;
• x-bratuha-option-labels — русские подписи значений enum;
• x-bratuha-show-if — поле имеет смысл только при указанных значениях других полей;
• x-bratuha-required-when-visible — обязательно, когда видно; в общий required такие поля не входят.

Поля с точкой в идентификаторе (imagine.prompt) передаются вложенным объектом: {"imagine": {"prompt": "…"}}.

3. Загрузить файл

Нейросети принимают файлы только по публичным http(s)-ссылкам. Если файл лежит у агента локально:

• POST /uploads — тело {"filename", "content_type", "data"}, где data — base64 или data URL, размер до 10 МБ. Ответ: {"url", "storage_path", "expires_in_days": 8}.
• POST /uploads/presign — тело {"filename", "content_type", "size"} для файлов до 100 МБ. Ответ содержит url, fields и publicUrl: отправьте форму multipart/form-data на url со всеми fields и самим файлом в поле file (хранилище ответит 201), затем используйте publicUrl в input.

Допустимые типы: изображения (JPEG, PNG, WebP), видео (MP4, MOV, WebM), аудио (MP3, WAV, M4A, AAC, FLAC, OGG, Opus), текстовые файлы и JSON. Файлы API удаляются через 8 дней и не занимают место в библиотеке.

4. Узнать цену

POST /operations/estimate с телом {"tool", "input"} проходит ту же проверку, что и запуск, но ничего не списывает:

{ "tool": "elevenlabs-eleven-v4", "effective_tool": "elevenlabs-eleven-v4",
  "cost": 0.08, "currency": "RUB", "input": { "...": "нормализованные значения" } }

Ошибка валидации приходит кодом 400 с текстом, какое поле исправить.

5. Запустить

POST /operations с заголовком Idempotency-Key и телом {"tool", "input", "max_price"}:

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

{ "id": "801f5327-…", "status": "queued", "tool": "elevenlabs-eleven-v4",
  "cost": 0.08, "balance_after": 1234.56, "created_at": "2026-10-02T18:32:48Z" }

6. Дождаться результата

GET /operations/{id} не чаще раза в секунду на одну операцию (иначе 429 с Retry-After: 1). Статусы: queued → processing → completed или failed.

{ "id": "801f5327-…", "status": "completed", "cost": 0.08,
  "completed_at": "2026-10-02T18:32:57Z",
  "result": { "type": "audio", "urls": ["https://…/file.mp3"], "files": [ { "url": "…" } ] },
  "error_message": null }

При failed стоимость автоматически возвращается на баланс, причина — в error_message. Ссылки на результат могут быть временными: скачайте файлы туда, куда просил пользователь.

7. Баланс и лимиты

GET /balance:

{ "balance": 1234.56, "currency": "RUB",
  "limits": { "daily": 500, "monthly": null, "spent_today": 12.4, "spent_this_month": 310.2,
              "daily_remaining": 487.6, "monthly_remaining": null, "period_timezone": "UTC" } }

null в daily или monthly означает «без лимита».

Лимит трат ключа. Перед каждым платным действием сервер резервирует его цену в лимите ключа; после фактического списания резерв заменяется реальной суммой, при отказе — освобождается. Превышение возвращает key_spend_limit_exceeded до обращения к нейросети: код 402 для операций, Chat Completions и Responses, код 400 в конверте Anthropic для Messages. Возвраты за неудачные операции в счётчике лимита не учитываются — лимит считает попытки, а не итоговые расходы. Сутки и месяц считаются по UTC, то есть с 03:00 по Москве.

Частота. На один ключ — 60 запросов в минуту на создание операций и чат-запросы вместе и не больше 8 одновременных чат-потоков; одну операцию можно опрашивать раз в секунду. Каталог, схемы, оценка и баланс в этот счётчик не входят. При превышении — 429 с Retry-After.

Что делает скилл, а что сервер. Подтверждение запуска дороже 100 ₽ при неясном бюджете — правило скилла, его соблюдает агент. max_price, Idempotency-Key и лимиты ключа проверяет сервер независимо от того, каким клиентом пришёл запрос.

Ключ. Никогда не вставляйте brth_... в чат, скриншот, репозиторий или настройки проекта, которые попадают в git. Если ключ утёк — отключите или удалите его в настройках API: запросы с ним сразу начнут получать 401.

Повторы. 503 с Retry-After — временная перегрузка, повторите тот же запрос с тем же Idempotency-Key. 500 на создании операции без Idempotency-Key повторять вслепую не стоит: сверьтесь со списком операций в кабинете.