Перейти к содержимому

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

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

AI-native

Отдайте интеграцию кодинг-агенту

Промпт знает эндпоинты, права токенов и путь каждой роли. Агент спросит, кто вы и на каком вы этапе, и напишет код под ваш стек.

Скачать .mdКак подключить →
Начало

Настройка с ИИ

Промпт превращает кодинг-агента в инженера по интеграции ApiHub. Агент определяет вашу роль и этап, предлагает следующий шаг, пишет код и проверяет результат по статусу и телу ответа.

CLAUDE.md

Добавьте промпт в CLAUDE.md в корне проекта. Чтобы вызывать его отдельно, сохраните как сабагента в .claude/agents/apihub.md с полями name и description в начале файла.

---
name: apihub
description: Интеграция с ApiHub: шлюз, токены, инструменты, вендорский API
---
apihub-agent-prompt.md · 302 строки
Скачать
# ApiHub: промпт для кодинг-агента

Ты помогаешь интегрироваться с ApiHub (https://hub.gnzs.pro), маркетплейсом моделей и API с оплатой за вызов. Ты работаешь в репозитории пользователя: читаешь код, пишешь интеграцию и запускаешь проверки. Задача: довести пользователя от текущего этапа до работающей интеграции коротким путём для его роли.

## Как работать

1. Определи роль: покупатель, разработчик, создатель агента, вендор или администратор площадки. Если роль не видна из запроса и кода, задай один вопрос с вариантами ответа.
2. Найди этап по карте в разделе «Путь по ролям». Назови роль, этап и следующий шаг одной строкой.
3. Посмотри стек проекта (package.json, pyproject.toml, requirements.txt, composer.json, go.mod) и пиши код на нём. Для моделей в формате OpenAI используй официальный OpenAI SDK.
4. Делай шаг целиком: код, переменные окружения, команда для проверки.
5. Проверяй результат по статусу и телу ответа, а не только по тому, что код не упал.
6. В конце назови следующий этап пути.

## Правила

- Не придумывай эндпоинты, поля и заголовки. Если чего-то нет в справочнике ниже, посмотри карточку модели или API в каталоге (https://hub.gnzs.pro/models, https://hub.gnzs.pro/tools) или документацию https://hub.gnzs.pro/docs, для /api/v1 — справочник https://hub.gnzs.pro/docs/api.json. Если нет и там, скажи об этом прямо.
- Ключ бери только из переменной окружения APIHUB_KEY. Не выводи его, не пиши в код, коммиты и логи. Проверь, что .env есть в .gitignore.
- Предлагай отдельный токен для каждого сервиса и агента, с минимальными правами. Для вызовов шлюза достаточно gateway:call.
…

С чего начать разговор

Первое сообщение агенту после промпта. Нажмите, чтобы скопировать.

Начало

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

Три шага от ключа до первого ответа.

  1. 1
    Получите ключПри регистрации создаётся токен Default. Для продакшена выпустите в кабинете отдельный токен с правом gateway:call и сохраните его в переменной APIHUB_KEY.
  2. 2
    Найдите адрес APIНа странице модели в каталоге есть её имя, цена и пример вызова. Адрес вызова: https://g.gnzs.pro/g/v1/{slug}/{путь}
  3. 3
    Отправьте запросФормат запроса такой же, как у API продавца. Для моделей это формат OpenAI, поэтому подходит официальный SDK.
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://g.gnzs.pro/g/v1/ravex-gateway/v1",
    api_key=os.environ["APIHUB_KEY"],
)

resp = client.chat.completions.create(
    model="gpt-oss-120b",
    messages=[{"role": "user", "content": "Привет"}],
)
print(resp.choices[0].message.content)

ID модели есть на её странице в каталоге, а список моделей продавца отдаёт GET /g/v1/{slug}/v1/models. Проверить ключ без списания: GET https://hub.gnzs.pro/api/v1/user. Стоимость каждого вызова видна в кабинете, раздел «Расход».

Начало

Путь по ролям

Этапы от знакомства до работающей интеграции. Для каждого этапа: что сделать, какие вызовы нужны и как понять, что этап пройден.

  1. 1
    Выбор

    Найдите модель или API в каталоге. Цена вызова указана на карточке.

    /models/tools
    Известны модель, адрес и цена
  2. 2
    Ключ

    Зарегистрируйтесь, токен Default создастся сам. Для продакшена выпустите токен с gateway:call.

    GET /api/v1/user
    Запрос отвечает 200
  3. 3
    Баланс

    Пополните баланс в кабинете.

    GET /api/v1/wallet
    Баланс больше нуля
  4. 4
    Первый вызов

    Отправьте запрос через шлюз.

    /g/v1/{slug}/…
    Ответ 200, вызов виден в кабинете в разделе «Расход»
  5. 5
    Интеграция

    Вынесите ключ в APIHUB_KEY, обработайте 402, 429 и 5xx.

    402429X-RateLimit-Remaining
    Ошибки обрабатываются без падений
  6. 6
    Контроль расходов

    Следите за потреблением и операциями по балансу.

    GET /api/v1/usage/summaryGET /api/v1/wallet/transactions
    Расходы видны по API и дням
Шлюз

Токены и права

Запросы к шлюзу и API кабинета авторизуются заголовком Authorization. Права токена выбираются при выпуске в кабинете.

Authorization: Bearer $APIHUB_KEY
gateway:callВызовы шлюза
usage:readПрофиль и статистика потребления
wallet:readБаланс и история операций
vendor:manageКабинет продавца: API, модели, цены, выручка
platform:adminОтчёты площадки, только для администраторов
account:manageПрофиль, пароль, пополнение, токены и наборы инструментов. Только в сессии кабинета, ключам не выдаётся

Выпускайте отдельный токен для каждого сервиса и агента с минимальными правами. Для вызовов шлюза достаточно gateway:call.

Шлюз

Адрес вызова

Шлюз проксирует запрос в API продавца. Всё, что идёт после slug, передаётся продавцу как путь.

https://g.gnzs.proшлюз/g/v1маршрут ApiHub/ravex-gatewayslug API/v1/modelsпуть в API продавца
ДоменВызовы обслуживает шлюз на g.gnzs.pro. Адрес hub.gnzs.pro/g/v1/… — псевдоним того же шлюза и работает, но идёт через лишний переход.
Два v1 в адресеПервый относится к маршруту ApiHub, второй к пути продавца. Нужны оба.
МодельПоле model в теле выбирает предложение продавца для этой модели и его цену.
ПотокОтвет со stream: true приходит по SSE.
Заголовки запросаПродавцу уходят только Content-Type и Accept. Доступ к API продавца шлюз подставляет сам, ваш ключ дальше шлюза не идёт.
Шлюз

Выбор продавца

Адрес без продавца в пути: шлюз берёт модель из тела и сам выбирает, кому отдать вызов. Работает для chat/completions, embeddings, rerank, messages и других методов моделей.

Запрос
curl -i "https://g.gnzs.pro/g/v1/chat/completions?sort=cheaper&country=RU" \
  -H "Authorization: Bearer $APIHUB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-oss-120b", "messages": [{"role": "user", "content": "Привет"}]}'

# в ответе
X-ApiHub-Seller: {slug продавца}
X-ApiHub-Route: cheaper:RU
optimalПо умолчанию. Цена, задержка и доля успешных ответов вместе
cheaperМинимальная цена
fasterМинимальная задержка
reliableНаибольшая доля успешных ответов
countryТолько продавцы с обработкой данных в этой стране, например RU.
МодельПишите имя модели со страницы каталога, например gpt-oss-120b. Имя, под которым её знает продавец, шлюз подставит сам.
Повтор у другогоНа 5xx, 429 или обрыв связи шлюз идёт к следующему продавцу, всего до трёх попыток. Платите только за того, кто ответил.
Кто ответилЗаголовки X-ApiHub-Seller и X-ApiHub-Route.
Шлюз

Заголовки ответа

Статус и тело — продавца, как он ответил. Шлюз добавляет к ним несколько своих заголовков, остальные заголовки продавца до вас не доходят.

X-Request-IdИдентификатор вызова. По нему стоимость: GET /api/v1/usage/calls/{id}
X-ApiHub-SellerСлаг продавца, который ответил. Только на адресе без продавца в пути
X-ApiHub-RouteВариант выбора: sort и страна, например optimal или cheaper:RU
X-RateLimit-RemainingСколько запросов осталось. Приходит с отказом 402 или 429
Content-TypeТип ответа продавца. У потока text/event-stream
Cache-ControlКак у продавца, если он его прислал

Сумм в ответе нет: цена вызова известна заранее из каталога, а стоимость каждого вызова видна в кабинете, раздел «Расход», и по API — GET /api/v1/usage/calls/{id} с идентификатором из X-Request-Id. В OpenAI SDK заголовки доступны через сырой ответ: with_raw_response в Python и .withResponse() в Node.js.

Шлюз

Списания

Цена вызова — цена продавца плюс наценка площадки: по умолчанию 5 % сверху, у отдельного продавца или API она может быть своей. Продавцу уходит его цена целиком. Суммы считаются до восьми знаков после запятой.

402Баланс до отправкиЕсли на балансе нет денег, запрос не уйдёт продавцу.
2xx · 3xxСписание за успехЗа ответы 4xx и 5xx деньги не списываются. Стоимость вызовов — в кабинете, раздел «Расход».
тарифыВызов, объём, токеныИх можно сочетать. Вход, выход и кэш токенов считаются отдельно.
Шлюз

Ошибки

Свои ошибки шлюз отдаёт JSON-ом: {"error": {"message", "status"}}. Ошибку продавца шлюз не переписывает: статус и тело приходят как есть, в формате продавца.

401ключ недействителенКлюча нет, он отозван или истёк
402на балансе нет денегПополните баланс в кабинете. Запрос продавцу не ушёл
403ключу не выдано право gateway:callВыпустите ключ с этим правом
404продавец не найден, маршрут не найден…Нет такого API, метода или модели
429слишком частоПревышен лимит запросов
502продавец не ответилПродавец недоступен или не уложился в срок
Пример 402
HTTP/1.1 402 Payment Required
Content-Type: application/json; charset=utf-8
X-RateLimit-Remaining: 59

{
  "error": {
    "message": "на балансе нет денег",
    "status": 402
  }
}
Шлюз

Лимиты

Шлюз ограничивает частоту запросов по ключу. При превышении он отвечает 429 с X-RateLimit-Remaining: 0. Подождите и повторите запрос, увеличивая паузу.

Шлюз

Подключить свой аккаунт

Около 1 550 сервисов — почта, календари, таблицы, CRM, поиск — можно вызывать своим аккаунтом через шлюз. Ключ сервиса вводится один раз в кабинете и хранится у сервиса подключений, а не в площадке. Действие стоит 0 ₽, вызовы видны в «Расходе».

1. ПодключитьКабинет, раздел «Подключения»: найдите сервис, заполните его поля и нажмите «Подключить». Ключ проверяет сам сервис при сохранении, неверный — ошибка под формой.
2. Выбрать действиеТам же, в поиске: у каждого действия есть actionId, например hasdata.scrape_web.
X-ConnectionИмя подключения из кабинета. Без заголовка — default. Нужен, если у вас несколько аккаунтов одного сервиса.
Пока только ключи APIСервисы со входом через OAuth подключить пока нельзя.
Вызов действия
curl https://g.gnzs.pro/g/v1/connect/v1/actions/{actionId} \
  -H "Authorization: Bearer $APIHUB_KEY" \
  -H "X-Connection: default" \
  -H "Content-Type: application/json" \
  -d '{"input": {…}}'

# ответ
{"success": true, "data": {…}}
400invalid_requestX-Connection не подходит под [A-Za-z0-9_-]{1,64}
403connection_requiredНи одного подключения нет. Подключите сервис в кабинете
4xxauthorization_failed, connection_not_allowed…Провайдер отверг ваш ключ или подключения с таким именем нет. Статус и тело — как ответил сервис подключений
503credential_unavailableСервис подключений временно недоступен. Повторите позже
Подключения в кабинете →
Шлюз

Файлы

Файл для продавца — картинку, ролик, запись до 1 ГБ — не нужно слать в теле вызова: положите его в хранилище площадки и передайте продавцу ссылку. Большинство API картинок, видео и расшифровки принимают URL. Файл хранится 7 дней, хранение входит в цену вызова.

Загрузка по ссылке
# 1. заявить файл: data.id и data.attributes.upload_url (PUT, 15 минут)
curl -s https://hub.gnzs.pro/api/v1/files \
  -H "Authorization: Bearer $APIHUB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "cat.png", "size": 123456, "content_type": "image/png"}'

# 2. залить тело прямо в хранилище
curl -X PUT -T cat.png -H "Content-Type: image/png" "$UPLOAD_URL"

# 3. отметить загрузку: data.attributes.download_url — ссылка на час
curl -s -X POST https://hub.gnzs.pro/api/v1/files/$ID/complete \
  -H "Authorization: Bearer $APIHUB_KEY"
download_urlСсылка на скачивание живёт час; свежая — GET /api/v1/files/{id}.
409 · 422409 — тело ещё не залито. 422 — залито больше заявленного size: файл удалён, начните заново.
Квота5 ГБ живых файлов на аккаунт.
files[]Результат продавца — картинку, ролик задания — площадка копирует к себе: GET /api/v1/usage/calls/{X-Request-Id} отдаёт files[] со ссылками. Ссылки продавца живут меньше.
Файлы в кабинете →
Кабинет

API кабинета

База https://hub.gnzs.pro/api/v1. Баланс и статистику можно читать токеном, операции с аккаунтом доступны только в сессии кабинета.

GET/userusage:readПрофиль
GET/walletwallet:readБаланс
GET/wallet/transactionswallet:readОперации по балансу
GET/usage/summaryusage:readСводка потребления
GET/usage/apisusage:readПотребление по API
GET/usage/seriesusage:readПотребление по времени
GET/usage/calls/{requestId}usage:readСтоимость одного вызова по X-Request-Id и копии его результатов (files[])
GET/filesgateway:callМои файлы
POST/filesgateway:callЗаявить файл: ссылка на PUT на 15 минут
POST/files/{id}/completegateway:callОтметить загрузку
GET/files/{id}gateway:callФайл и ссылка на скачивание на час
DELETE/files/{id}gateway:callУдалить файл
POST/wallet/topupсессияПополнение баланса
GET/tokensсессияСписок токенов
POST/tokensсессияВыпуск токена
DELETE/tokens/{tokenId}сессияОтзыв токена
GET/tool-sets/{toolSet}/exportсессияОпределения инструментов набора
PATCH/profileсессияИзменение профиля
PATCH/passwordсессияСмена пароля

Справочник API площадки (OpenAPI) →api.json

Вендорам

Запросы от шлюза

Шлюз передаёт путь, строку запроса и тело покупателя. Из его заголовков доходят только Content-Type и Accept, остальные ставит шлюз. Ключ покупателя в ваш API не передаётся.

Заголовки доступаТе, что вы задали в кабинете при описании API, до 10 штук. Например, Authorization с вашим ключом. Сверяйте их и отклоняйте запросы без них
X-Gateway-Request-IdИдентификатор вызова. Пишите в логи: по нему площадка найдёт вызов
Content-Type, AcceptОт покупателя, как он их прислал. Других его заголовков шлюз не передаёт
Проверка заголовка доступа, Express
import crypto from "node:crypto";

// Тот же заголовок доступа, что задан в кабинете при описании API
const EXPECTED = Buffer.from(`Bearer ${process.env.APIHUB_GATEWAY_KEY}`);

app.use((req, res, next) => {
  const got = Buffer.from(req.get("Authorization") ?? "");
  if (got.length !== EXPECTED.length || !crypto.timingSafeEqual(got, EXPECTED)) {
    return res.status(401).end();
  }
  next();
});

// в ответе сообщите потребление
res.set({
  "X-Input-Tokens": String(usage.input),
  "X-Output-Tokens": String(usage.output),
});
Вендорам

Учёт потребления

Сообщите шлюзу, сколько потратил вызов: заголовками ответа или полем usage в теле в формате, выбранном в предложении, например OpenAI. Цену шлюз посчитает по тарифу эндпоинта.

X-Input-TokensТокены входа
X-Output-TokensТокены выхода
X-Cached-TokensТокены из кэша
X-Usage-UnitsЕдиницы для тарифа за объём
Вендорам

Описание API

API и эндпоинты описываются в кабинете вендора.

СпецификацияК эндпоинту можно приложить OpenAPI 3.0. Площадка проверяет её при сохранении.
Инструмент для агентовИмя, назначение и JSON Schema аргументов. Из них собирается инструмент в каталоге /tools и определение в наборах покупателей.
/vendor/{продавец}Ваша страница в каталоге: API и модели, которые вы продаёте.
Агентам

Подключить APIHUB в Claude / ChatGPT / Cursor

MCP-сервер площадки — один адрес на весь каталог: поиск API, описание методов и вызов с оплатой из вашего кошелька. Ключ вставлять не нужно: клиент откроет страницу входа APIHUB, вы разрешите доступ, и он получит ключ сам.

https://g.gnzs.pro/mcp
Claude.ai, Claude DesktopНастройки → Коннекторы → Добавить свой коннектор, адрес https://g.gnzs.pro/mcp. Откроется вход APIHUB и экран «Разрешить».
ChatGPTНастройки → Приложения и коннекторы → создать коннектор с тем же адресом, авторизация OAuth.
Cursor, Claude CodeВ mcp.json — сервер с url https://g.gnzs.pro/mcp; вход откроется в браузере. Можно и без OAuth: заголовок Authorization: Bearer с ключом gateway:call.
Что получает клиентОтдельный ключ «MCP: {клиент}» только с gateway:call на 30 дней, клиент продлевает его сам. Ключ виден в кабинете в «Ключах»: там ему задают лимит расходов и там его удаляют — подключение гаснет.
search_apis, get_api, call_apiИнструменты сервера: найти API, прочитать методы и схему аргументов, вызвать. Вызов идёт тем же шлюзом и по той же цене, что /g/v1.
Агентам

Наборы инструментов

Соберите в кабинете, в разделе «Инструменты», набор из каталога. У каждого набора свой MCP-коннектор: подключите его адрес в Claude, ChatGPT или Cursor, и каждый метод набора станет отдельным инструментом агента. Кнопка «Определения инструментов (JSON)» отдаёт то же для своего SDK.

https://g.gnzs.pro/mcp/sets/{ключ набора}
Адрес коннектораВ кабинете у набора — блок «Подключить в Claude / ChatGPT / Cursor» с адресом и кнопкой «Скопировать». Ключ набора ts_… — публичный, но чужой набор отвечает 404.
ИнструментыИмя — машинное имя метода; совпало у методов разных API — с префиксом слага: {api}__{метод}. В описании — назначение и цена за вызов. Метод, выключенный продавцом, из набора пропадает.
АргументыОдин объект: параметры пути {id} — одноимёнными свойствами, у GET и DELETE остальное уходит строкой запроса, у прочих — JSON-телом. Вызов идёт тем же шлюзом и по той же цене, что /g/v1.
ДоступНа экране согласия — «Весь каталог» или «Только наборы». Ключ только с наборами вызывает лишь их методы — и через MCP, и прямым /g/v1; в «Ключах» видно, к каким наборам он ограничен.
Определения набора
{
  "set": { "id": 12, "name": "Поиск и факты" },
  "tools": [
    {
      "name": "…",
      "description": "…",
      "inputSchema": { "type": "object", "properties": { … } },
      "meta": {
        "effect": "…",
        "safe_to_retry": true,
        "price_per_call": { … },
        "call": { "method": "POST", "url": "/g/v1/{slug}/{путь}" }
      }
    }
  ],
  "hint": "Вызовы идут через шлюз биржи…"
}
GET /api/v1/tool-sets/{toolSet}/exportТо же для кода. Только в сессии кабинета: набор, как и ключи, — настройка аккаунта.
meta.callМетод и полный адрес вызова на https://g.gnzs.pro, ключ с правом gateway:call в Authorization.
name, description, inputSchemaПереносятся в описание tools вашего SDK. inputSchema — JSON Schema аргументов.
meta.price_per_callЦена за вызов, если инструмент тарифицируется за вызов. Известна до вызова, по ней агент держит бюджет.
Инструменты для агентов →