API roadmap — Разработчикам

Обзор

Три способа подключения, одна платформа.

API Bluweo даёт сторонним приложениям и ИИ-агентам программный доступ ко всему, что умеет веб-интерфейс студии: искать в библиотеке 3D-иконок, создавать новые варианты по промпту, управлять загрузками и получать фоновые события.

REST API — синхронные вызовы для любого HTTP-клиента.
MCP server — готовый инструмент для Claude, Cursor и любого агента с поддержкой MCP.
Webhooks — асинхронные уведомления о долгих генерациях и событиях оплаты.

Обратите внимание: Доступ к API входит в тариф Studio. Тарифы Free и Designer работают только через веб-интерфейс — см. ограничения ниже.

REST, MCP и вебхуки — три способа подключения, расходящиеся от платформы Bluweo.

Быстрый старт

Первый вызов меньше чем за 60 секунд.

Создайте аккаунт и перейдите на Studio.
Создайте ключ API здесь: /dashboard/billing → API keys. Ключи начинаются с blu_live_.
Передавайте его как Bearer-токен в каждом запросе.
Вызовите GET /v1/icons/search?q=fox чтобы убедиться, что ключ работает.

Базовый URL: https://api.bluweo.com. Все запросы должны идти по HTTPS — обычный HTTP API отклонит.

# 1. Search the icon catalogue
curl https://api.bluweo.com/v1/icons/search?q=fox \
  -H "Authorization: Bearer blu_live_..."

Аутентификация

Bearer-ключи в рамках рабочего пространства.

В каждом запросе к API должен быть заголовок Authorization: Bearer <key> . Ключи выпускаются в вашей панели и привязаны к одному рабочему пространству; ограничение по частоте зависит от уровня ключа.

Формат ключа: blu_live_* (рабочий) или blu_test_* (песочница — без списаний, результаты с водяным знаком).
Показывается один раз: на сервере мы храним только хеш ключа. Если потеряли — выпустите новый.
Смена ключа: ключ можно заменить через POST /v1/keys/:id/roll; старый продолжит работать ещё 24 часа, чтобы переход прошёл спокойно.
Отзыв: DELETE /v1/keys/:id действует сразу.

Аутентификация по ключу API — заголовок Bearer в каждом вызове.

REST API

Искать, создавать, скачивать, управлять.

Все конечные точки находятся в /v1/. JSON на входе, JSON на выходе. Поля в snake_case. Метки времени в формате ISO-8601, UTC.

Метод	Путь	Назначение
GET	`/v1/icons`	Список иконок; фильтр по тегу, стилю и цвету.
GET	`/v1/icons/search`	Полнотекстовый поиск по каталогу.
GET	`/v1/icons/:id`	Подробности об одной иконке и её вариантах.
POST	`/v1/icons/generate`	Запускает генерацию с ИИ. Возвращает 202.
GET	`/v1/generations/:id`	Запрашивает статус и результаты генерации.
POST	`/v1/icons/:id/variants`	Создаёт вариант по стилю или цвету из существующей иконки.
GET	`/v1/collections`	Список отобранных коллекций.
POST	`/v1/downloads`	Фиксирует загрузку (списывает 1 кредит).
GET	`/v1/me`	Сведения о рабочем пространстве и остаток кредитов.
POST	`/v1/keys`	Выпускает новый ключ API.
DELETE	`/v1/keys/:id`	Отзывает ключ.

Генерации выполняются асинхронно — POST возвращает 202 и идентификатор задачи; сама отрисовка занимает 5–30 секунд. Вместо ожидания опрашивайте /v1/generations/:id или подпишитесь на generation.completed вебхуки.

Схема асинхронной генерации: POST ставит в очередь, обработчик выполняет, вебхук сообщает.

# Generate a 3D icon
curl https://api.bluweo.com/v1/icons/generate \
  -X POST \
  -H "Authorization: Bearer blu_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "cute 3D fox character, studio lighting",
    "kind": "icon",
    "aspect": "1:1",
    "outputs": 4
  }'

# → 202 { "id": "gen_01H...", "status": "queued" }

# Poll until done
curl https://api.bluweo.com/v1/generations/gen_01H... \
  -H "Authorization: Bearer blu_live_..."

MCP-сервер

Позвольте ИИ-агентам работать с Bluweo как с инструментом.

Model Context Protocol (MCP) — открытый стандарт Anthropic, позволяющий ИИ-агентам вызывать внешние инструменты. Наш сервер размещён по адресу /api/mcp (Streamable HTTP): добавьте этот URL в Claude Code, Claude Desktop, Cursor или любой клиент с поддержкой MCP — и агент сможет искать, просматривать, скачивать и создавать иконки прямо посреди разговора. Устанавливать ничего не нужно.

MCP-сервер предоставляет семь инструментов:

search_icons — поиск по ключевому слову, категории, стилю или коллекции.
get_icon — подробности и предпросмотр 128 px, который агент может увидеть.
list_collections — просмотр отобранных наборов.
get_account — тариф, кредиты, лимит загрузок.
download_icon — файлы 512 px или оригиналы, списания такие же, как на сайте.
generate_icon — генерация в Студии по промпту.
list_generations — недавние запуски Студии и ссылки на изображения.

search_icons работает без ключа (100 вызовов в день). Остальным инструментам нужен личный ключ API из тарифа Studio, переданный в виде Authorization: Bearer blu_live_… — он создаётся в разделе «Настройки → Ключи API». Читать руководство по MCP →

Схема MCP: агент вызывает инструмент, MCP-сервер переводит вызов в REST, результаты возвращаются агенту.

# Claude Code — the Studio-plan key is required
claude mcp add --transport http realisticicon \
  https://realisticicon.com/api/mcp \
  --header "Authorization: Bearer blu_live_..."

Вебхуки

Push-уведомления о фоновых задачах.

Укажите URL вебхука в панели. Мы отправляем POST-запрос с подписанным JSON каждый раз, когда происходит что-то важное, — прежде всего чтобы вам не приходилось постоянно опрашивать статус генерации.

События, которые мы отправляем:

generation.completed — результаты готовы к скачиванию.
generation.failed — кредиты возвращаются автоматически; в теле указана причина ошибки.
credits.low — остаток опустился ниже 20% от лимита тарифа.
subscription.updated — тариф изменён, продлён или отменён.

В каждом сообщении есть заголовок Bluweo-Signature — это HMAC-SHA256 от тела запроса, вычисленный с вашим секретом вебхука. Всегда проверяйте подпись, прежде чем доверять содержимому; POST без подписи может оказаться подделкой.

# Example payload Bluweo POSTs to your endpoint
{
  "event": "generation.completed",
  "data": {
    "id": "gen_01H...",
    "status": "done",
    "outputs": [
      { "url": "https://cdn.bluweo.com/g/.../0.png", "width": 1024, "height": 1024 }
    ],
    "credits_used": 5
  },
  "created_at": "2026-05-16T17:42:11Z"
}

# Header attached:
# Bluweo-Signature: t=1715882531,v1=<hmac>

Ограничения и квоты

На ключ и на месяц — а ещё на секунду, чтобы всем было честно.

К каждому ключу применяются два ограничения: месячный объём (квота по уровню тарифа) и короткие всплески (10 запросов в секунду — чтобы защитить общие ресурсы). Оба возвращаются в каждом ответе в стандартных заголовках X-RateLimit-* .

Тариф	Доступ к API	Месячная квота	Всплеск
Free	— (только веб-интерфейс)	—	—
Designer	— (только веб-интерфейс)	—	—
Studio	REST · MCP · Webhooks	10,000 req	10 req/s

Генерации и загрузки вдобавок расходуют кредиты из лимита тарифа — см. Тарифы. Пополнение пакетом кредитов не увеличивает квоту API — оно лишь покрывает стоимость генерации.

При превышении лимита вернётся 429 Too Many Requests вместе с заголовком Retry-After . Приостановите запросы на это время и повторите — за паузу никаких санкций нет.

Доступ к API по уровням тарифа: Free и Designer — только веб-интерфейс; Studio открывает API.

# Every response includes:
X-RateLimit-Limit:        10000
X-RateLimit-Remaining:    9847
X-RateLimit-Reset:        1715958000   # unix epoch
X-RateLimit-Burst-Limit:  10
X-RateLimit-Burst-Remaining: 7

# On 429:
Retry-After: 3            # seconds

Ошибки

Обычные HTTP-коды и структурированное тело JSON.

Частые коды состояния:

Код	Значение
`200`	OK — синхронный вызов выполнен.
`202`	Accepted — фоновая задача поставлена в очередь.
`400`	Некорректное тело запроса или параметры.
`401`	Ключ API отсутствует или недействителен.
`402`	Кредиты закончились — пополните и повторите.
`403`	Ключ действителен, но уровень тарифа не даёт доступа к API.
`404`	Ресурс не найден.
`409`	Конфликт состояния (например, отзыв уже отозванного ключа).
`429`	Достигнут лимит запросов — см. `Retry-After`.
`5xx`	Это на нашей стороне. Идемпотентные запросы мы повторяем сами; вы тоже можете повторить без риска.

Тело любой ошибки — это JSON: { "error": { "code", "message", "request_id" } }. Обращаясь в поддержку, укажите request_id — так мы сможем поднять трассировку.

# 402 — out of credits
{
  "error": {
    "code": "insufficient_credits",
    "message": "Account has 3 credits; generate(outputs=4) requires 20.",
    "request_id": "req_01H9R..."
  }
}

# 429 — rate limit
{
  "error": {
    "code": "rate_limited",
    "message": "Burst limit of 10 req/s exceeded.",
    "request_id": "req_01H9R..."
  }
}

Ограничения возможностей

Чего API пока не умеет — лучше сказать сразу.

Без офлайна и установки на своих серверах. Генерации всегда выполняются на нашей инфраструктуре. Библиотеку иконок можно кешировать на клиенте, а генерацию с ИИ — нет.
Пакетная генерация за один вызов не поддерживается. Каждый POST /v1/icons/generate обрабатывает один промпт и до 4 результатов. Для больших партий распараллеливайте вызовы сами; ограничение на всплески продолжает действовать.
Максимальная длина промпта: 1 000 символов. Более длинные промпты отклоняются с кодом 400.
Правила о содержании. Мы блокируем промпты про реальных людей, защищённых авторским правом персонажей, откровенный и разжигающий ненависть контент. В таких случаях приходит 400 вместе с code: "policy_violation".
Разрешение результата ограничено 2048 × 2048. Выше — только по отдельному договору.
Время генерации: 5–30 секунд. В худшем случае (очередь переполнена) — до 2 минут. Проектируйте асинхронно: используйте вебхуки, а не частый опрос в цикле.
Транспорт MCP: только Streamable HTTP. Локального пакета stdio (npx) пока нет — подключайтесь к размещённому URL.
На уровне Studio SLA нет. В договорах Enterprise есть доступность 99,9% и закреплённый специалист поддержки. Напишите нам.

Нужно что-то, чего нет в этом списке?

Тарифы Enterprise открывают:

Своё разрешение и донастройку стилей на ваших бренд-материалах.
Выделенные мощности (без общей очереди).
Развёртывание в VPC или на своих серверах.
Закреплённого специалиста поддержки и SLA 99,9%.
Цены по объёму свыше 10 тысяч запросов в месяц.

Связаться с отделом продаж →

Версионирование

v1 — текущая версия. Несовместимые изменения выходят как v2.

Версия указывается в пути URL: /v1/.... Внутри одной версии мы делаем только добавляющие изменения — новые поля, новые конечные точки, новые типы событий. Внутри версии мы никогда не удаляем поле и не меняем его тип.

Когда мы выпустим v2, v1 предыдущая версия проработает ещё как минимум 12 месяцев а дату отключения мы объявим через конечную точку changelog и письмом всем пользователям API.

История изменений: GET /v1/changelog возвращает все изменения с момента запуска, начиная с самых свежих.
Страница статуса: status.bluweo.com текущая доступность и история сбоев.
Уведомления по почте: включаются в панели. Пишем только о предстоящих несовместимых изменениях и крупных сбоях.

# Read the changelog (no auth needed)
curl https://api.bluweo.com/v1/changelog | jq

# Sample entry:
{
  "version": "1.4.0",
  "released_at": "2026-04-22",
  "title": "MCP tools: list_collections + variant generation",
  "highlights": [
    "New MCP tool: list_collections",
    "Variant generation now supports color hex shorthand",
    "Webhook signatures use t=...,v1=... format (v0 deprecated 2026-10-22)"
  ]
}

Готовы приступить?

Создайте первый ключ API в панели или напишите нам, если нужен отдельный договор.

Перейти на Studio Связаться с отделом продаж