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

Интеграция для реселлеров

Как собрать свой клиентский продукт на AIGate без захардкоженных моделей и цен.

На этой странице собран публичный API-контракт для реселлера. AIGate не создаёт ваших клиентов и не управляет ими: аккаунты, лимиты, розничные цены и платежи остаются на вашем бэкенде.

Храните ключ только на сервереНе вставляйте API-ключ AIGate в браузерный или мобильный код. Вызывайте AIGate со своего бэкенда и отдавайте клиенту только нужный результат и данные биллинга.

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

URL	Назначение
https://api.aigate.shop/v1	Основной API-эндпоинт.
https://ru-api.aigate.shop/v1	RU-мост с тем же API-ключом и форматом запросов.

Модели, доступные ключу

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

bash

curl https://api.aigate.shop/v1/models \  -H "Authorization: Bearer sk-your-api-key"

Актуальные цены AIGate

GET /v1/pricing возвращает действующие цены в долларах для авторизованного ключа. Не зашивайте публичный каталог в код: доступность моделей, тиры, скидки и цены могут меняться.

bash

curl https://api.aigate.shop/v1/pricing \  -H "Authorization: Bearer sk-your-api-key"

json

{  "object": "list",  "currency": "USD",  "data": [    {      "id": "openai/gpt-5.5",      "unit": "1M_tokens",      "input": 0.85,      "output": 3.8,      "cache_read": 0.085,      "cache_write": 0.85,      "tiers": [        {          "name": "standard",          "condition": "tokens <= 272000",          "input": 0.85,          "output": 3.8        }      ],      "discount": {        "percent": 30,        "expires_at": 1785542400      }    }  ]}

Поле	Что значит
unit	1M_tokens, image, second или request.
input / output	Цена в долларах за 1M входных или выходных токенов.
cache_read / cache_write	Цена за 1M кэшированных токенов, если модель поддерживает кэш.
image_output	Цена за 1M выходных image-токенов, если модель использует такой биллинг.
price	Цена за картинку, секунду или запрос для нетокеновых единиц.
tiers	Условные цены. Используйте совпавшее условие вместо базовой цены.
discount	Активная скидка и Unix-время её окончания. Истёкшая скидка в ответ не попадает.

Ключ с фиксированной группойЦена зависит от группы ключа. Для ключа с группой auto маршрут вернёт pricing_group_ambiguous, поэтому для реселлинга создайте ключ с фиксированной группой.

Сколько AIGate списал за запрос

Поддерживаемые успешные ответы генерации содержат usage.cost_usd. Это итоговая сумма в долларах, которую AIGate списал за запрос с учётом правил цены ключа и активной скидки.

json

{  "id": "gate-1785542400",  "object": "chat.completion",  "model": "openai/gpt-5.5",  "choices": [...],  "usage": {    "prompt_tokens": 128,    "completion_tokens": 64,    "total_tokens": 192,    "cost_usd": 0.000352  }}

Для потокового Chat Completions передайте stream_options.include_usage=true и прочитайте usage.cost_usd в последнем usage-чанке. В потоковом Responses значение приходит в response.usage.cost_usd события completed.

Проверка расхода по request id

Если вы сохранили id запроса, можно получить его статус, токены, кэш и списанную сумму. Запросить запись сможет только тот API-ключ, которым она была создана.

bash

curl https://api.aigate.shop/v1/usage/requests/gate-1785542400 \  -H "Authorization: Bearer sk-your-api-key"

json

{  "object": "request_usage",  "request_id": "gate-1785542400",  "status": "success",  "status_code": 200,  "model": "openai/gpt-5.5",  "input_tokens": 128,  "output_tokens": 64,  "total_tokens": 192,  "cost": 0.000352,  "currency": "USD"}

Как добавить свою наценку

В биллинге храните деньги целым числом микродолларов. Рассчитайте розничную сумму от usage.cost_usd и округлите один раз на границе списания с клиента.

const marginPercent = 20;const chargedMicrousd = Math.round(response.usage.cost_usd * 1_000_000);const retailMicrousd = Math.ceil(chargedMicrousd * (1 + marginPercent / 100));const retailUsd = retailMicrousd / 1_000_000;

Контроль баланса

Периодически запрашивайте GET /v1/balance с бэкенда и предупреждайте заранее, если баланс или лимит ключа подходят к нулю. Не вызывайте его перед каждой генерацией.

Кэширование и обновление

Кэшируйте /v1/models и /v1/pricing максимум на 5 минут.
Обновляйте их вместе, чтобы недоступная модель не оставалась в продаже со старой ценой.
Не кэшируйте ответы генерации, если это явно не разрешено правилами вашего продукта.
Для 429 и временных 502/503 используйте повтор с растущей задержкой и случайным разбросом. Ошибки валидации и оплаты вслепую не повторяйте.

Какие ошибки обработать

Статус	Что делать
400	Исправить параметры или использовать ключ с фиксированной группой для /v1/pricing.
401	Отклонить запрос и проверить API-ключ.
402	Остановить новые задачи и пополнить баланс AIGate.
403	Ключу недоступна выбранная модель.
429	Поставить задачу в очередь и повторить с задержкой.
502 / 503	Временно скрыть модель и безопасно повторить запрос.

Чек-лист перед продом

Используйте разные ключи с фиксированной группой для прода и тестов.
Храните балансы и лимиты клиентов в своей базе.
Для каждой задачи сохраняйте request id AIGate, модель, токены, usage.cost_usd и своё списание.
Сверяйте итоговые суммы с /v1/balance и данными расхода по запросам.
Считайте задачу оплаченной только после успешного ответа AIGate.

НазадБалансДальшеChat Completions