Документация
Как вызывать модели и API через шлюз, управлять ключами и балансом и выложить свой API. Для покупателей, разработчиков, создателей агентов и вендоров.
Отдайте интеграцию кодинг-агенту
Промпт знает эндпоинты, права токенов и путь каждой роли. Агент спросит, кто вы и на каком вы этапе, и напишет код под ваш стек.
Настройка с ИИ
Промпт превращает кодинг-агента в инженера по интеграции ApiHub. Агент определяет вашу роль и этап, предлагает следующий шаг, пишет код и проверяет результат по статусу и телу ответа.
Добавьте промпт в CLAUDE.md в корне проекта. Чтобы вызывать его отдельно, сохраните как сабагента в .claude/agents/apihub.md с полями name и description в начале файла.
--- name: apihub description: Интеграция с ApiHub: шлюз, токены, инструменты, вендорский API ---
Сохраните промпт как правило проекта и включите его для всех запросов.
--- description: Интеграция с ApiHub alwaysApply: true ---
Добавьте промпт в AGENTS.md в корне репозитория.
Вставьте промпт в инструкции проекта в Claude или ChatGPT и приложите файлы, с которыми нужно работать.
# 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Получите ключПри регистрации создаётся токен Default. Для продакшена выпустите в кабинете отдельный токен с правом
gateway:callи сохраните его в переменной APIHUB_KEY. - 2Найдите адрес APIНа странице модели в каталоге есть её имя, цена и пример вызова. Адрес вызова:
https://g.gnzs.pro/g/v1/{slug}/{путь} - 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)import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://g.gnzs.pro/g/v1/ravex-gateway/v1",
apiKey: process.env.APIHUB_KEY,
});
const resp = await client.chat.completions.create({
model: "gpt-oss-120b",
messages: [{ role: "user", content: "Привет" }],
});
console.log(resp.choices[0].message.content);curl -i "https://g.gnzs.pro/g/v1/ravex-gateway/v1/chat/completions" \
-H "Authorization: Bearer $APIHUB_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-oss-120b", "messages": [{"role": "user", "content": "Привет"}]}'ID модели есть на её странице в каталоге, а список моделей продавца отдаёт GET /g/v1/{slug}/v1/models. Проверить ключ без списания: GET https://hub.gnzs.pro/api/v1/user. Стоимость каждого вызова видна в кабинете, раздел «Расход».
Путь по ролям
Этапы от знакомства до работающей интеграции. Для каждого этапа: что сделать, какие вызовы нужны и как понять, что этап пройден.
- 1Выбор
Найдите модель или API в каталоге. Цена вызова указана на карточке.
/models/toolsИзвестны модель, адрес и цена - 2Ключ
Зарегистрируйтесь, токен Default создастся сам. Для продакшена выпустите токен с gateway:call.
GET /api/v1/userЗапрос отвечает 200 - 3Баланс
Пополните баланс в кабинете.
GET /api/v1/walletБаланс больше нуля - 4Первый вызов
Отправьте запрос через шлюз.
/g/v1/{slug}/…Ответ 200, вызов виден в кабинете в разделе «Расход» - 5Интеграция
Вынесите ключ в APIHUB_KEY, обработайте 402, 429 и 5xx.
402429X-RateLimit-RemainingОшибки обрабатываются без падений - 6Контроль расходов
Следите за потреблением и операциями по балансу.
GET /api/v1/usage/summaryGET /api/v1/wallet/transactionsРасходы видны по API и дням
- 1Ключ с правами
Выпустите токен с gateway:call, а для мониторинга отдельный с usage:read.
gateway:callusage:readТокены лежат в переменных окружения - 2Подключение
Укажите base_url шлюза в OpenAI SDK или HTTP-клиенте.
https://g.gnzs.pro/g/v1/{slug}/v1Запросы идут через шлюз - 3Первый вызов
Отправьте запрос и сверьте стоимость в кабинете.
/app/spendВызов виден в разделе «Расход» - 4Надёжность
Разбирайте тело ошибки, повторяйте 429 и 5xx с паузой, включите stream, где он нужен.
error.messageX-RateLimit-RemainingСбой продавца не роняет приложение - 5Выбор продавца
Вызывайте модель без продавца в пути: шлюз выберет его по sort и country и повторит у другого при сбое.
/g/v1/chat/completions?sort=cheaperВ ответе есть X-ApiHub-Seller - 6Наблюдаемость
Стройте отчёты по потреблению.
GET /api/v1/usage/seriesПотребление видно по времени
- 1Отдельный токен
Выпустите для агента токен только с gateway:call.
gateway:callАгент не видит баланс и настройки - 2Инструменты
Соберите в кабинете набор инструментов и отдайте агенту его определения.
/app/toolsGET /api/v1/tool-sets/{toolSet}/exportАгент вызывает инструмент - 3Бюджет
Цена вызова известна заранее. Ограничьте число вызовов за сессию и останавливайте агента при 402.
meta.price_per_call402Сессия не выходит за бюджет - 4Контроль
Бэкенд со своим токеном следит за балансом и потреблением.
wallet:readusage:readЕсть оповещение об остатке
- 1Стать вендором
Укажите в кабинете название компании.
кабинетОткрыт кабинет вендора - 2Описать API
Добавьте base_url, заголовки доступа, эндпоинты и спецификацию OpenAPI.
base_urlзаголовки доступаOpenAPIAPI и эндпоинты сохранены - 3Назначить цену
Выберите тариф: за вызов, за объём или за токены.
за вызовза объёмза токеныУ эндпоинтов есть цена - 4Принять шлюз
Проверяйте заголовки доступа и возвращайте учёт потребления.
заголовки доступаX-Input-TokensX-Usage-UnitsЗапросы без заголовков доступа отклоняются - 5Проверка
Сделайте тестовый вызов через шлюз.
/g/v1/{slug}/…X-Gateway-Request-IdУчёт совпадает с ожиданием - 6Публикация
Нажмите «Опубликовать» в кабинете. Модерации нет: открытый API сразу появится в каталоге.
каталогAPI видно покупателям - 7Выручка
Смотрите статистику и выручку в кабинете, выводите заявкой.
POST /api/v1/vendor/payout-requestsВыручка начисляется за оплаченные вызовы
Токены и права
Запросы к шлюзу и API кабинета авторизуются заголовком Authorization. Права токена выбираются при выпуске в кабинете.
Authorization: Bearer $APIHUB_KEYВыпускайте отдельный токен для каждого сервиса и агента с минимальными правами. Для вызовов шлюза достаточно gateway:call.
Адрес вызова
Шлюз проксирует запрос в API продавца. Всё, что идёт после slug, передаётся продавцу как путь.
Выбор продавца
Адрес без продавца в пути: шлюз берёт модель из тела и сам выбирает, кому отдать вызов. Работает для 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Заголовки ответа
Статус и тело — продавца, как он ответил. Шлюз добавляет к ним несколько своих заголовков, остальные заголовки продавца до вас не доходят.
Сумм в ответе нет: цена вызова известна заранее из каталога, а стоимость каждого вызова видна в кабинете, раздел «Расход», и по API — GET /api/v1/usage/calls/{id} с идентификатором из X-Request-Id. В OpenAI SDK заголовки доступны через сырой ответ: with_raw_response в Python и .withResponse() в Node.js.
Списания
Цена вызова — цена продавца плюс наценка площадки: по умолчанию 5 % сверху, у отдельного продавца или API она может быть своей. Продавцу уходит его цена целиком. Суммы считаются до восьми знаков после запятой.
Ошибки
Свои ошибки шлюз отдаёт JSON-ом: {"error": {"message", "status"}}. Ошибку продавца шлюз не переписывает: статус и тело приходят как есть, в формате продавца.
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 ₽, вызовы видны в «Расходе».
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": {…}}Файлы
Файл для продавца — картинку, ролик, запись до 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"API кабинета
База https://hub.gnzs.pro/api/v1. Баланс и статистику можно читать токеном, операции с аккаунтом доступны только в сессии кабинета.
Запросы от шлюза
Шлюз передаёт путь, строку запроса и тело покупателя. Из его заголовков доходят только Content-Type и Accept, остальные ставит шлюз. Ключ покупателя в ваш API не передаётся.
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. Цену шлюз посчитает по тарифу эндпоинта.
Описание API
API и эндпоинты описываются в кабинете вендора.
Подключить APIHUB в Claude / ChatGPT / Cursor
MCP-сервер площадки — один адрес на весь каталог: поиск API, описание методов и вызов с оплатой из вашего кошелька. Ключ вставлять не нужно: клиент откроет страницу входа APIHUB, вы разрешите доступ, и он получит ключ сам.
https://g.gnzs.pro/mcpНаборы инструментов
Соберите в кабинете, в разделе «Инструменты», набор из каталога. У каждого набора свой MCP-коннектор: подключите его адрес в Claude, ChatGPT или Cursor, и каждый метод набора станет отдельным инструментом агента. Кнопка «Определения инструментов (JSON)» отдаёт то же для своего SDK.
https://g.gnzs.pro/mcp/sets/{ключ набора}{
"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": "Вызовы идут через шлюз биржи…"
}