Тариф Бизнес

Документация API

Genesis API совместим с форматом OpenAI Chat Completions: достаточно заменить адрес сервера и ключ — и любая библиотека OpenAI начнёт работать через нас. Ниже всё, что API умеет сегодня: эндпоинты, заголовки, форматы запросов и ответов, ошибки и лимиты.

https://api.genesisaihub.netAuthorization: Bearer gk_…Content-Type: application/json

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

От нуля до первого ответа модели — пять строк в терминале.

Тариф Бизнес подключает менеджер. Контакт — на странице тарифов и в боте, в разделе «Тарифы».
Выпустите ключ: Кабинет → API-ключи → «Выпустить ключ». Скопируйте его сразу — он показывается один раз.
Добавьте в белый список хотя бы один IP сервера, с которого пойдут вызовы. Пока список пуст, запросы с ключом получают 403.
Сохраните ключ в переменную окружения и выполните запрос ниже.
Проверьте расход: Кабинет → Статистика — там появится запрос с источником api.

bash

export GENESIS_API_KEY="gk_ваш_ключ"
curl https://api.genesisaihub.net/v1/chat/completions \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-4o-mini", "messages": [{"role": "user", "content": "Привет!"}]}'

Ключа ещё нет? Выпустить в кабинете. Нужен тариф Бизнес.

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

Каждый запрос подписывается сервисным API-ключом. Ключ выпускается в личном кабинете и действует, пока активен тариф Бизнес. Вызовы с ключом принимаются только с IP из белого списка.

Ключ вида gk_…

Ключ начинается с gk_, затем случайная строка. Мы храним только его отпечаток (SHA-256), поэтому полное значение показывается один раз — при выпуске.

Заголовок Authorization

Передавайте ключ в заголовке Authorization: Bearer gk_ваш_ключ. Другие способы (query-параметры, cookie) не принимаются.

Только тариф Бизнес

Ключи выпускаются на тарифе Бизнес. Если подписка истекла, ключ остаётся в списке, но запросы получают 403 до продления.

Как получить или перевыпустить ключ

Войдите на сайт через Telegram и откройте Кабинет → Тариф. Тариф Бизнес подключает менеджер.
Перейдите в Кабинет → API-ключи и нажмите «Выпустить ключ». Дайте ключу понятное название: «Прод», «Тест».
Скопируйте ключ из окна подтверждения. После закрытия окна показать его целиком уже нельзя.
Потеряли или скомпрометировали ключ — нажмите «Отозвать» и выпустите новый. Отозванный ключ перестаёт работать сразу: запросы с ним получают 401. Ключей может быть несколько, например отдельный для каждого сервиса.

То же самое можно сделать в Telegram-боте: кнопка «API-ключ» в главном меню (видна на тарифе Бизнес).

Храните ключ на сервере

Не вставляйте ключ в код мобильных приложений и фронтенда — любой, кто его увидит, сможет тратить ваш лимит. Держите его в переменных окружения или менеджере секретов и вызывайте API со своего бэкенда.

IP-адреса

API-ключ работает только с адресов из белого списка. Пустой список значит, что все вызовы с ключом отклоняются, пока не добавлен хотя бы один IP. По умолчанию пустой белый список блокирует вызовы; администратор может разрешить этому клиенту запросы с любого IP.

Вызовы с API-ключом принимаются только с IP-адресов и сетей из белого списка аккаунта.
Пока в списке нет ни одного адреса, API отклоняет все вызовы с ключом — даже если сам ключ верный.
Можно добавить один адрес, например 203.0.113.10, или сеть CIDR, например 203.0.113.0/24.
Адрес, которого нет в списке, получает тот же ответ 403: message «IP not whitelisted», code ip_not_whitelisted.
Список не ограничивает вход в кабинет и бота. Он действует только на запросы с ключом gk_.

403 IP not whitelisted

Если список пуст или адрес запроса в него не входит, ответ 403. Поле message равно «IP not whitelisted», код ошибки — ip_not_whitelisted. Добавьте хотя бы один IP в кабинете или у администратора — после этого API начнёт принимать вызовы с этих адресов.

Лимит запросов на ключ

На каждый API-ключ можно поставить потолок по числу успешных запросов. Пока лимит не задан, ключ работает как раньше.

Лимит задаётся отдельно на каждый ключ: число успешных запросов и период — сутки, неделя, месяц или без сброса.
Пока лимит не задан, ключ работает как раньше: этот счётчик его не останавливает.
В счётчик входят только успешные ответы модели, сделанные этим ключом. Ошибка модели, другой ключ, кабинет и бот его не увеличивают.
Сутки начинаются в 00:00 UTC, неделя — в понедельник 00:00 UTC, месяц — первого числа 00:00 UTC. В эту границу счётчик начинается заново.
Период без сброса — общий потолок за всё время. Счётчик не обнуляется.
Когда запросов уже не меньше лимита, следующий вызов с этим ключом получает 429. В message по-русски написано, сколько запросов было разрешено и когда счётчик сбросится. Если сброса нет, message говорит, что счётчик не сбрасывается.
Этот 429 не подменяет отказ по энергии тарифа и не подменяет 403, если адреса нет в белом списке или список пуст.
Снять лимит можно в кабинете. Администратор видит лимит каждого ключа на карточке клиента и может задать другой.

429, если запросов больше, чем разрешено

Ответ приходит как error.code api_key_request_limit. В message указано, сколько запросов было разрешено и когда счётчик сбросится, например 2026-10-04T00:00:00Z. Для лимита без сброса resets_at пустой, а message заканчивается фразой «Счётчик не сбрасывается».

Базовый адрес

Все запросы идут на один домен по HTTPS. Эндпоинты в формате OpenAI живут под префиксом /v1.

base url

https://api.genesisaihub.net

Официальные SDK OpenAI

Укажите base_url равным https://api.genesisaihub.net/v1 и ваш ключ вместо ключа OpenAI. Методы chat.completions.create и models.list работают без изменений.

Обычный HTTP

Тело запроса и ответа — JSON в UTF-8. Для POST обязателен заголовок Content-Type: application/json. Интерактивная схема OpenAPI доступна по адресу https://api.genesisaihub.net/docs.

Эндпоинты

Что доступно по API-ключу. Управление подпиской и ключами по ключу не работает — это делается в кабинете.

Метод	Путь	Зачем	Авторизация
POST	/v1/chat/completions	Ответ модели	API-ключ
GET	/v1/models	Список доступных моделей	API-ключ
GET	/me/usage	Расход и остаток	API-ключ
GET	/auth/me	Проверить ключ	API-ключ
GET	/plans	Тарифы	не нужна
GET	/health	Проверка доступности	не нужна

POST/v1/chat/completionsAPI-ключ

Ответ модели

Главный эндпоинт. Принимает сообщения в формате OpenAI Chat Completions, проверяет энергию тарифа или баланс Бизнес, пересылает запрос модели и возвращает её ответ без изменений. Успешный ответ списывает энергию или деньги; токены пишутся в статистику.

Параметры

modelstring: необязательное · в теле; Идентификатор модели из списка GET /v1/models. Если не передан — openai/gpt-4o-mini. Модель вне списка — ошибка 400.
messagesarray: обязательное · в теле; Непустой список сообщений вида {"role": "system" | "user" | "assistant", "content": "…"}. Пустой список или не список — ошибка 400.
streamboolean: необязательное · в теле; true — ответ приходит потоком: текст частями, в последнем фрагменте есть расход. false или без поля — ответ целиком.
temperature, max_tokens и другиекак у OpenAI: необязательное · в теле; Остальные поля тела передаются модели как есть. Набор поддерживаемых полей зависит от конкретной модели.

Поле	Тип	Описание
`model`необязательное · в теле	string	Идентификатор модели из списка GET /v1/models. Если не передан — openai/gpt-4o-mini. Модель вне списка — ошибка 400.
`messages`обязательное · в теле	array	Непустой список сообщений вида {"role": "system" \| "user" \| "assistant", "content": "…"}. Пустой список или не список — ошибка 400.
`stream`необязательное · в теле	boolean	true — ответ приходит потоком: текст частями, в последнем фрагменте есть расход. false или без поля — ответ целиком.
`temperature, max_tokens и другие`необязательное · в теле	как у OpenAI	Остальные поля тела передаются модели как есть. Набор поддерживаемых полей зависит от конкретной модели.

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

curl

curl https://api.genesisaihub.net/v1/chat/completions \
  -H "Authorization: Bearer gk_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "Отвечай кратко."},
      {"role": "user", "content": "Привет! Что ты умеешь?"}
    ]
  }'

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

200Ответ модели в формате OpenAI

json

{
  "id": "gen-1727900000-abc123",
  "object": "chat.completion",
  "created": 1727900000,
  "model": "openai/gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Привет! Могу ответить на вопрос, написать текст или код."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 21,
    "completion_tokens": 17,
    "total_tokens": 38
  }
}

429Энергия тарифа кончилась

json

{
  "error": {
    "code": "limit_exceeded",
    "message": "Лимит тарифа Pro исчерпан: 5 000 из 5 000 ⚡ за период. Чтобы продолжить, перейдите на Advanced.",
    "upgrade": {"plan_code": "advanced", "price_rub": 1890, "url": "https://genesisaihub.net/cabinet/subscription"}
  }
}

429Лимит запросов на ключе исчерпан

json

{
  "error": {
    "code": "api_key_request_limit",
    "message": "Лимит запросов по этому ключу исчерпан: разрешено 100 запросов за сутки. Счётчик сбросится 2026-10-04T00:00:00Z.",
    "limit": 100,
    "period": "day",
    "used": 100,
    "resets_at": "2026-10-04T00:00:00Z"
  }
}

402На тарифе Бизнес пустой баланс

json

{
  "error": {
    "code": "insufficient_balance",
    "message": "Пополните баланс"
  }
}

403IP нет в белом списке

json

{
  "code": "ip_not_whitelisted",
  "message": "IP not whitelisted",
  "detail": "Добавьте хотя бы один IP-адрес в кабинете или у администратора, иначе API не примет вызовы."
}

400Модель не из списка разрешённых

json

{
  "detail": "Модель 'openai/gpt-5' недоступна. Список разрешённых моделей: GET /v1/models"
}

Ответ модели ждём до 120 секунд. Если модель не ответила — ошибка 502 с кодом upstream_error.
Поле usage в ответе — то же, по которому мы считаем токены в вашей статистике.
Неудачные ответы модели записываются в статистику со статусом error, но энергия и деньги не списываются.
Если на ключе задан лимит запросов и успешных ответов уже не меньше этого числа, следующий вызов с этим ключом получает 429 api_key_request_limit. В message сказано, сколько запросов было разрешено и когда счётчик сбросится. Для периода без сброса message говорит, что счётчик не сбрасывается.

GET/v1/modelsAPI-ключ

Список доступных моделей

Какие модели можно указать в поле model. Формат ответа как у OpenAI, поэтому работает client.models.list() в официальных SDK.

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

curl

curl https://api.genesisaihub.net/v1/models \
  -H "Authorization: Bearer gk_ваш_ключ"

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

200Список моделей

json

{
  "object": "list",
  "data": [
    {"id": "openai/gpt-4o-mini", "object": "model", "owned_by": "openai"},
    {"id": "anthropic/claude-haiku-4.5", "object": "model", "owned_by": "anthropic"},
    {"id": "google/gemini-2.5-flash", "object": "model", "owned_by": "google"},
    {"id": "nvidia/nemotron-3-super-120b-a12b:free", "object": "model", "owned_by": "nvidia"}
  ]
}

GET/me/usageAPI-ключ

Расход и остаток

Сводка за текущий период: остаток энергии или баланс Бизнес, плюс статистика токенов по дням и моделям. Считается по всем обращениям аккаунта — через API, бота и сайт.

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

curl

curl https://api.genesisaihub.net/me/usage \
  -H "Authorization: Bearer gk_ваш_ключ"

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

200Сводка за период

json

{
  "plan_code": "b2b",
  "period_start": "2026-09-15T10:00:00Z",
  "period_end": "2026-10-15T10:00:00Z",
  "requests_used": 143,
  "requests_limit": 10000,
  "requests_remaining": 9857,
  "tokens_used": 210500,
  "tokens_limit": null,
  "tokens_remaining": null,
  "energy_used": 420,
  "energy_budget": null,
  "energy_remaining": null,
  "balance_micro_usd": 25000000,
  "markup": "0.15",
  "by_day": [
    {"date": "2026-10-01", "requests": 120, "tokens": 180200},
    {"date": "2026-10-02", "requests": 23, "tokens": 30300}
  ],
  "by_model": [
    {"model": "openai/gpt-4o-mini", "requests": 131, "tokens": 190000},
    {"model": "anthropic/claude-haiku-4.5", "requests": 12, "tokens": 20500}
  ]
}

На тарифах Free, Pro и Advanced смотрите energy_remaining и daily_remaining. tokens_* — статистика, по ним лимит не режется.
На тарифе Бизнес energy_budget равен null: смотрите balance_micro_usd (1 единица = $0.000001) и markup.

GET/auth/meAPI-ключ

Проверить ключ

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

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

curl

curl https://api.genesisaihub.net/auth/me \
  -H "Authorization: Bearer gk_ваш_ключ"

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

200Ключ действует

json

{
  "user": {
    "id": 42,
    "telegram_id": 123456789,
    "username": "ivan",
    "first_name": "Иван",
    "is_active": true,
    "created_at": "2026-09-01T12:00:00Z"
  },
  "auth_method": "key"
}

401Ключ отозван или неверный

json

{
  "detail": "API-ключ не найден или отозван"
}

GET/plansбез авторизации

Тарифы

Публичный список тарифов с ценами и лимитами. Авторизация не нужна. Именно отсюда стоит брать актуальные цифры — они хранятся в базе и могут меняться.

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

curl

curl https://api.genesisaihub.net/plans

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

200Список тарифов

json

[
  {"code": "free", "name": "Бесплатный", "price_rub": 0, "period_days": null, "energy_budget": 50, "daily_cap": 25, "api_access": false},
  {"code": "pro", "name": "Pro", "price_rub": 790, "period_days": 30, "energy_budget": 5000, "daily_cap": 350, "api_access": false},
  {"code": "advanced", "name": "Advanced", "price_rub": 1890, "period_days": 30, "energy_budget": 15000, "daily_cap": 1000, "api_access": false},
  {"code": "b2b", "name": "Бизнес", "price_rub": 0, "period_days": null, "energy_budget": null, "daily_cap": null, "api_access": true}
]

GET/healthбез авторизации

Проверка доступности

Жив ли сервис. Авторизация не нужна. Подходит для мониторинга.

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

curl

curl https://api.genesisaihub.net/health

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

200Сервис работает

json

{
  "status": "ok",
  "time": "2026-10-02T08:45:00.000000Z"
}

Коды ошибок

Ошибки проверки запроса и авторизации приходят как {«detail»: …}. Ошибки лимита и ответа модели — как {«error»: {«code», «message»}}. Отказ по белому списку — 403 с полями code, message и detail.

400

Неверный запрос: модель не из списка, пустой messages, stream=true. Также так приходят ошибки валидации на стороне модели (тогда формат — как у 5xx, с кодом upstream_error).

json

{
  "detail": "Поле 'messages' должно быть непустым списком сообщений"
}

401

Нет заголовка Authorization, он не вида Bearer <ключ>, ключ не найден или отозван. В ответе есть заголовок WWW-Authenticate: Bearer.

json

{
  "detail": "API-ключ не найден или отозван"
}

403ip_not_whitelisted

Запрос с API-ключом, а белый список пуст или адрес клиента в него не входит. Пока не добавлен хотя бы один IP, отклоняются все вызовы с ключом. message всегда «IP not whitelisted».

json

{
  "code": "ip_not_whitelisted",
  "message": "IP not whitelisted",
  "detail": "Добавьте хотя бы один IP-адрес в кабинете или у администратора, иначе API не примет вызовы."
}

403

Ключ есть, но у владельца сейчас тариф без доступа к API (подписка B2B истекла), пользователь заблокирован или эндпоинт недоступен по ключу (например, управление подпиской и ключами — только из кабинета).

json

{
    "detail": "API-ключи доступны на тарифе Бизнес (B2B). Подключение — через менеджера."
}

404

Такого пути нет. Проверьте адрес: эндпоинты модели начинаются с /v1, статистика — /me/usage.

json

{
  "detail": "Not Found"
}

422

Тело запроса не разобрать: невалидный JSON или не объект. Формат — стандартный для FastAPI, в detail список ошибок с путём до поля.

json

{
  "detail": [
    {
      "type": "json_invalid",
      "loc": ["body", 0],
      "msg": "JSON decode error",
      "input": {},
      "ctx": {"error": "Expecting value"}
    }
  ]
}

429limit_exceeded

Кончилась энергия тарифа или дневной потолок. message можно показать пользователю как есть. upgrade — следующий тариф: Free → Pro, Pro → Advanced. У Advanced upgrade равен null: нужно продлить подписку. Тариф Бизнес сюда не предлагается.

json

{
  "error": {
    "code": "limit_exceeded",
    "message": "Лимит тарифа Pro исчерпан: 5 000 из 5 000 ⚡ за период. Чтобы продолжить, перейдите на Advanced.",
    "upgrade": {
      "plan_code": "advanced",
      "price_rub": 1890,
      "url": "https://genesisaihub.net/cabinet/subscription"
    }
  }
}

429api_key_request_limit

На этом API-ключе исчерпан лимит успешных запросов. message можно показать как есть: там число разрешённых запросов и момент сброса в UTC. period — day, week, month или forever. У forever resets_at пустой, а message заканчивается фразой «Счётчик не сбрасывается». Запросы из кабинета и бота этот счётчик не тратят и такой ответ не получают. Это не лимит энергии (limit_exceeded) и не пустой баланс. Пока лимит на ключе не задан, этого ответа нет.

json

{
  "error": {
    "code": "api_key_request_limit",
    "message": "Лимит запросов по этому ключу исчерпан: разрешено 100 запросов за сутки. Счётчик сбросится 2026-10-04T00:00:00Z.",
    "limit": 100,
    "period": "day",
    "used": 100,
    "resets_at": "2026-10-04T00:00:00Z"
  }
}

402insufficient_balance

Тариф Бизнес, а на балансе не хватает денег даже на минимальное списание. Запрос к модели не отправляется. Пополните баланс через менеджера.

json

{
  "error": {
    "code": "insufficient_balance",
    "message": "Пополните баланс"
  }
}

502upstream_error

Модель недоступна, не ответила за отведённое время, вернула ошибку 5xx или сервис моделей отклонил запрос. Клиенту это всегда 502, а не 401: 401 значит, что не подошёл ваш ключ. Энергия и деньги не списываются. Повторите через несколько секунд. Ошибки, которые модель вернула на само содержимое запроса, приходят с кодом upstream_error и статусом 4xx (details — исходный ответ).

json

{
  "error": {
    "code": "upstream_error",
    "message": "Модель не ответила за отведённое время",
    "details": null
  }
}

Лимиты и тарифы

Доступ по API даёт тариф Бизнес. Цифры ниже — значения по умолчанию; они хранятся в базе и могут меняться, актуальные всегда отдаёт GET /plans.

Тариф	Цена	Энергия	В день	API-ключ
Бесплатный free	Бесплатно	50 ⚡ навсегда	25 ⚡	нет
Pro pro	790 ₽/мес	5 000 ⚡ за 30 дней	350 ⚡	нет
Advanced advanced	1 890 ₽/мес	15 000 ⚡ за 30 дней	1 000 ⚡	нет
Бизнес b2b	Без абонплаты	оплата по факту	без лимита	да

1 ⚡ = $0.001 нашей себестоимости. Энергия округляется вверх до целого и не бывает меньше 1 ⚡ за успешный ответ, даже у модели без цены.
У Free, Pro и Advanced есть бюджет на период и отдельный дневной потолок. Срабатывает тот, что кончился раньше.
Тариф Бизнес не режется энергией: перед запросом нужен положительный баланс, после успеха списывается себестоимость плюс наценка (по умолчанию 15 %).
Период Pro и Advanced — 30 дней с начала подписки. Продление начинает новый период. Дневной потолок обновляется в 00:00 UTC.
В списание входят только успешные ответы. Ошибка модели записывается в статистику, но энергия и деньги не списываются.
Расход общий для бота, сайта и API-ключа.
Отдельный лимит числа запросов можно поставить на каждый API-ключ. Пока он пуст, ключ работает без этого потолка. Исчерпание — ответ 429 api_key_request_limit, он не заменяет лимит энергии и не заменяет 403 по белому списку.
Ответ модели ждём до 120 секунд, после чего возвращаем 502.

При исчерпании энергии API отвечает 429 limit_exceeded. Если исчерпан лимит запросов на ключе — 429 api_key_request_limit. Остаток в реальном времени — GET /me/usage или раздел «Статистика» в кабинете.

Модели Genesis

Модели, доступные через API. Список по умолчанию задаётся настройками сервера и может расширяться — проверяйте GET /v1/models.

Идентификатор	Примечание
openai/gpt-4o-mini	Модель по умолчанию, если поле model не передано
anthropic/claude-haiku-4.5	—
google/gemini-2.5-flash	—
nvidia/nemotron-3-super-120b-a12b:free	Бесплатная модель: возможны временные ограничения частоты запросов

Что умеет API

Коротко о том, что можно делать ключом тарифа Бизнес.

Ответ модели в формате OpenAI Chat Completions: POST /v1/chat/completions.
Поток ответа: stream: true — текст приходит частями, в конце виден расход.
Запасные модели: поле models, если основная недоступна.
Структурированный вывод: response_format с JSON Schema.
Вызов инструментов: tools и tool_choice.
Кэш длинной инструкции: cache_control, если модель это умеет.
Каталог и цены: GET /v1/models. Список тарифов: GET /plans.
Ключ и тариф меняются в кабинете на сайте или в Telegram-боте.
Вызовы с ключом идут только с IP из белого списка. Пустой список — все такие вызовы отклоняются.

Готовы подключиться?

Ключ выпускается в кабинете, когда активен тариф Бизнес.

Получить API-ключ