Developer API

AI Gateway API

Один GRIKAI API key и один OpenAI-compatible base URL для нескольких model providers, pay-as-you-go USD balance, routing, fallbacks, logs и spend controls.

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

Создайте ai.gateway key, используйте https://api.grik.io/api/v1 как OpenAI SDK base URL и вызывайте общий model gateway.

Пример

curl -X POST https://api.grik.io/api/v1/keys \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AI Gateway production",
    "scopes": ["ai.gateway"],
    "product": "ai_gateway",
    "environment": "production",
    "spend_limit_micros": 50000000,
    "spend_reset_interval": "monthly"
  }'

curl https://api.grik.io/api/v1/models \
  -H "Authorization: Bearer GRIK_API_KEY"

#Модели

Показывает каталог моделей: доступность providers, размер контекста, pricing, capabilities и data policy metadata.

Метод	Endpoint	Авторизация	Область	Аудитория	Описание
GET	`/models`	Bearer необязателен	-	Разработчики	Показывает AI Gateway models с provider availability, context length, pricing, capabilities и data policy metadata.

GET/models

Показывает AI Gateway models с provider availability, context length, pricing, capabilities и data policy metadata.

Авторизация: Bearer необязателенОбласть: -Аудитория: Разработчики

#Chat completions

Отправляйте OpenAI/OpenRouter-compatible chat requests со streaming, tools, response_format, app attribution headers и idempotency.

Пример

curl -X POST https://api.grik.io/api/v1/chat/completions \
  -H "Authorization: Bearer GRIK_API_KEY" \
  -H "Idempotency-Key: chat_123" \
  -H "HTTP-Referer: https://your-app.example" \
  -H "X-Title: Your App" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Summarize this changelog in three bullets."}
    ],
    "stream": true
  }'

Метод	Endpoint	Авторизация	Область	Аудитория	Описание
POST	`/chat/completions`	API key	ai.gateway	Разработчики	Запускает OpenAI/OpenRouter-compatible chat completions через GRIKAI AI Gateway со streaming, tools, fallbacks и provider routing.Передавайте Idempotency-Key только для create/retry запросов, где он реально реализован.

POST/chat/completions

Запускает OpenAI/OpenRouter-compatible chat completions через GRIKAI AI Gateway со streaming, tools, fallbacks и provider routing.Передавайте Idempotency-Key только для create/retry запросов, где он реально реализован.

Авторизация: API keyОбласть: ai.gatewayАудитория: Разработчики

#Responses API

Отправляйте OpenAI Responses-compatible requests. Gateway маршрутизирует native OpenAI/xAI Responses, Anthropic Messages и OpenAI-compatible providers за одним endpoint.

Пример

curl -X POST https://api.grik.io/api/v1/responses \
  -H "Authorization: Bearer GRIK_API_KEY" \
  -H "Idempotency-Key: resp_123" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.5",
    "input": "Summarize this changelog in three bullets.",
    "max_output_tokens": 600,
    "provider": {
      "allow_fallbacks": true,
      "sort": "price"
    }
  }'

Метод	Endpoint	Авторизация	Область	Аудитория	Описание
POST	`/responses`	API key	ai.gateway	Разработчики	Запускает OpenAI Responses-compatible requests через GRIKAI AI Gateway с тем же model catalog, routing, fallbacks и usage billing.Передавайте Idempotency-Key только для create/retry запросов, где он реально реализован.
POST	`/responses/input_tokens`	API key	ai.gateway	Разработчики	Считает входные токены Responses до запуска. Для моделей OpenAI используется upstream token count, для остальных providers возвращается estimate.Используйте перед upstream hosted-model вызовом.

POST/responses

Запускает OpenAI Responses-compatible requests через GRIKAI AI Gateway с тем же model catalog, routing, fallbacks и usage billing.Передавайте Idempotency-Key только для create/retry запросов, где он реально реализован.

Авторизация: API keyОбласть: ai.gatewayАудитория: Разработчики

POST/responses/input_tokens

Считает входные токены Responses до запуска. Для моделей OpenAI используется upstream token count, для остальных providers возвращается estimate.Используйте перед upstream hosted-model вызовом.

Авторизация: API keyОбласть: ai.gatewayАудитория: Разработчики

#Маршрутизация и fallback

Используйте models fallback arrays и provider routing fields: order, only, ignore, allow_fallbacks и sort.

Пример

curl -X POST https://api.grik.io/api/v1/chat/completions \
  -H "Authorization: Bearer GRIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "models": ["openai/gpt-4o-mini", "minimax/minimax-m3"],
    "provider": {
      "order": ["openrouter", "ricochet"],
      "ignore": ["experimental-provider"],
      "allow_fallbacks": true,
      "sort": "price"
    },
    "messages": [
      {"role": "user", "content": "Generate a release-risk checklist."}
    ]
  }'

#Проверка перед запуском и баланс

Проверяйте актуальные цены моделей, считайте входные токены, оценивайте стоимость запроса и доступный баланс AI Gateway до вызова модели. Пополнение баланса выполняется в личном кабинете.

Пример

curl https://api.grik.io/api/v1/ai-gateway/balance \
  -H "Authorization: Bearer GRIK_API_KEY"

curl -X POST https://api.grik.io/api/v1/responses/input_tokens \
  -H "Authorization: Bearer GRIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.5",
    "input": "Summarize this changelog in three bullets."
  }'

curl -X POST https://api.grik.io/api/v1/ai-gateway/quote \
  -H "Authorization: Bearer GRIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "responses",
    "model": "openai/gpt-5.5",
    "input": "Summarize this changelog in three bullets.",
    "max_output_tokens": 600
  }'

Метод	Endpoint	Авторизация	Область	Аудитория	Описание
GET	`/ai-gateway/balance`	API key	ai.gateway	Разработчики	Возвращает balance_micros, pending reservation micros, available balance и USD display values.
GET	`/ai-gateway/pricing`	Bearer необязателен	-	Разработчики	Возвращает AI Gateway packages, platform fee, minimum charge и видимые клиенту model pricing.
POST	`/responses/input_tokens`	API key	ai.gateway	Разработчики	Считает входные токены Responses до запуска. Для моделей OpenAI используется upstream token count, для остальных providers возвращается estimate.Используйте перед upstream hosted-model вызовом.
POST	`/ai-gateway/quote`	API key	ai.gateway	Разработчики	Оценивает токены, стоимость для клиента, доступный баланс, spend-limit decision и fallback-route charge до запуска. Баланс не резервируется и не списывается.Используйте перед upstream hosted-model вызовом.

GET/ai-gateway/balance

Возвращает balance_micros, pending reservation micros, available balance и USD display values.

Авторизация: API keyОбласть: ai.gatewayАудитория: Разработчики

GET/ai-gateway/pricing

Возвращает AI Gateway packages, platform fee, minimum charge и видимые клиенту model pricing.

Авторизация: Bearer необязателенОбласть: -Аудитория: Разработчики

POST/responses/input_tokens

Авторизация: API keyОбласть: ai.gatewayАудитория: Разработчики

POST/ai-gateway/quote

Оценивает токены, стоимость для клиента, доступный баланс, spend-limit decision и fallback-route charge до запуска. Баланс не резервируется и не списывается.Используйте перед upstream hosted-model вызовом.

Авторизация: API keyОбласть: ai.gatewayАудитория: Разработчики

#Usage logs

Смотрите settled usage events, route attempts, failed reservations, provider costs, customer charges и margin fields.

Метод	Endpoint	Авторизация	Область	Аудитория	Описание
GET	`/ai-gateway/usage`	API key	ai.gateway	Разработчики	Показывает AI Gateway usage events с filters по provider, model, status, date и limit.
GET	`/ai-gateway/usage/:id`	API key	ai.gateway	Разработчики	Возвращает один usage event с token counts, provider cost, platform fee, charge, route attempts и metadata.
GET	`/ai-gateway/reservations`	API key	ai.gateway	Разработчики	Показывает active, failed и settled preflight reservations для idempotency и pending-balance debugging.

GET/ai-gateway/usage

Показывает AI Gateway usage events с filters по provider, model, status, date и limit.

Авторизация: API keyОбласть: ai.gatewayАудитория: Разработчики

GET/ai-gateway/usage/:id

Возвращает один usage event с token counts, provider cost, platform fee, charge, route attempts и metadata.

Авторизация: API keyОбласть: ai.gatewayАудитория: Разработчики

GET/ai-gateway/reservations

Показывает active, failed и settled preflight reservations для idempotency и pending-balance debugging.

Авторизация: API keyОбласть: ai.gatewayАудитория: Разработчики

#API keys

Управляйте ai.gateway keys, disabled status, environment labels, spend limits, reset windows и usage totals.

Метод	Endpoint	Авторизация	Область	Аудитория	Описание
GET	`/keys`	User token	-	Разработчики	Показывает account API keys без raw secret.
POST	`/keys`	User token	-	Разработчики	Создаёт API key с ai.gateway scope и optional spend controls. Raw key возвращается только один раз.
PATCH	`/keys/:id`	User token	-	Разработчики	Обновляет key name, status, scopes, environment, spend limit или reset interval без rotation секрета.
DELETE	`/keys/:id`	User token	-	Разработчики	Отзывает API key по id.

GET/keys

Показывает account API keys без raw secret.

Авторизация: User tokenОбласть: -Аудитория: Разработчики

POST/keys

Создаёт API key с ai.gateway scope и optional spend controls. Raw key возвращается только один раз.

Авторизация: User tokenОбласть: -Аудитория: Разработчики

PATCH/keys/:id

Обновляет key name, status, scopes, environment, spend limit или reset interval без rotation секрета.

Авторизация: User tokenОбласть: -Аудитория: Разработчики

DELETE/keys/:id

Отзывает API key по id.

Авторизация: User tokenОбласть: -Аудитория: Разработчики

#Errors

Clients должны ветвиться по OpenAI-compatible error.type, error.code и HTTP status для billing и retry decisions.

КодОписание

402

Недостаточно credits, budget exceeded или требуется premium approval.

403

API key валиден, но у него нет scope, нужного для endpoint.

429

API key или organization превысили текущий request limit.

503

Нет доступного provider route или upstream provider вернул ошибку.