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

Ключи, заголовки и лимиты

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

Python JavaScript curl

import os

from openai import OpenAI

client = OpenAI(
    base_url="https://ai.globall.dev/v1",
    api_key=os.environ["TOK_API_KEY"],
)

for m in client.models.list().data:
    print(m.id)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://ai.globall.dev/v1",
  apiKey: process.env.TOK_API_KEY,
});

const list = await client.models.list();
for (const m of list.data) console.log(m.id);

curl https://ai.globall.dev/v1/models \
  -H "Authorization: Bearer $TOK_API_KEY"

Заголовки запроса

Authorization: header; Bearer gw_live_… — ключ из кабинета. Единственный обязательный заголовок.
X-Conversation-Id: header; Липкость диалога: продолжение разговора уходит на тот же маршрут. Шлюз хранит от него только хэш.
Idempotency-Key: header; Повтор без второго списания. Работает только при stream: false; ответ хранится 24 часа. Если в настройках организации включено «Не хранить содержимое», ответ не сохраняется вообще — повтор с тем же ключом исполнится заново и спишется второй раз.

Больше ни один заголовок на ответ не влияет: User-Agent попадает в журнал запросов, остальное шлюз не читает и вендору не передаёт. Заголовка проекта нет вовсе — проект это способ сгруппировать ключи в кабинете, и расходы разносятся по проекту того ключа, которым сделан запрос.

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

X-Request-Id: header; Идентификатор запроса. Назовите его в поддержке — по нему найдётся вся история попыток.
X-Cost-Usd: header; Списанная сумма в долларах. В потоковом ответе приходит трейлером, после последнего кадра.
X-Degraded: header; true, если ответ пришёл с запасной ступени, а не с основной.
Retry-After: header; Секунды до повтора. Всегда есть у 429 и 503; у 502 приходит, когда вендор назвал своё время. Если он пришёл — ждите столько, сколько там написано, какой бы ни был статус.
X-Route, X-Attempts: header; Какой маршрут ответил и с какой попытки. Идентификатор маршрута — наш внутренний и меняется без предупреждения: годится для поддержки и графиков, не для логики кода.
X-Idempotent-Replay: header; true, если это повтор по Idempotency-Key, а не новый ответ; рядом X-Original-Request-Id — идентификатор того запроса, чей ответ вы получили.
WWW-Authenticate: header; Bearer realm="aigw" — только вместе с 401.

Лимит на ключ

Дневной и месячный потолок в рублях задаётся в кабинете. Когда он выбран, запросы получают 429 с кодом spend_limit_exceeded и Retry-After до начала следующего окна; деньги дальше не списываются.

Пауза, блокировка, приостановка

Ключ на паузе — 403 key_paused, снимается в кабинете. Ключ, остановленный автоматикой, — 403 key_blocked с причиной в тексте. Приостановленная организация — 403 org_suspended. Отозванный ключ — 401.

Ключ, которого шлюз не знает, и запрос без заголовка Authorization получают 401 с кодом unauthorized и заголовком WWW-Authenticate.