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

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

Как вызывать модели и 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.

Шлюз

Списания

Цена вызова — цена продавца из каталога, без надбавок. Комиссию площадки удерживают из доли продавца; у отдельного продавца или 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Цена за вызов, если инструмент тарифицируется за вызов. Известна до вызова, по ней агент держит бюджет.
Инструменты для агентов →