Контракт шлюза

Справочник API

Семейство выбирает поле model. Путь задаёт протокол запроса. Ниже основные операции сотрудника, не административный API.

Авторизация

Передавайте виртуальный токен сотрудника в Authorization: Bearer или x-api-key. Если заданы оба корректных способа, приоритет имеет Authorization. Если Bearer задан и невалиден, x-api-key не проверяется: ответ будет 401. Сессия администратора не заменяет токен.

HTTP

Authorization: Bearer <токен сотрудника>
Content-Type: application/json

Маршруты

Таблица использует базу https://ai-router.foodpicasso.dev/api/v1. Эти же основные пути доступны с префиксом /v1 вместо /api/v1.

Метод и путь	Назначение	Семейства
`POST /chat/completions`	Сообщения, инструменты, JSON или SSE	GLM, Claude, GPT
`POST /messages`	Anthropic Messages	Claude, GLM
`POST /messages/count_tokens`	Передача запроса подсчёта токенов	Claude, GLM
`POST /responses`	OpenAI Responses	GPT, GLM
`POST /responses/compact`	Передача запроса compaction	GPT, GLM
`GET /models`	Модели активных назначений	Все назначенные
`GET /limits`	Квоты назначенных подключений	Все назначенные

Наличие маршрутов подсчёта токенов и compaction означает поддержку передачи запроса шлюзом. Поддержка операции конкретной моделью зависит от провайдера.

Chat Completions

Обязательны точный model и массив messages. В простом запросе сообщение содержит роль user и текст content.

Shell

curl --fail-with-body https://ai-router.foodpicasso.dev/api/v1/chat/completions \
  -H "Authorization: Bearer $PICASSO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "glm-5.3",
    "messages": [{"role": "user", "content": "Привет!"}]
  }'

GLM получает запрос в своём Chat API. Для Claude и GPT шлюз преобразует запрос и возвращает Chat Completions. Поддерживаются текст, изображения, function tools и история вызовов функций, но не все поля OpenAI API.

Потоковый ответ

Добавьте stream: true. Для curl используйте -N, чтобы видеть данные сразу. stream_options.include_usage запрашивает статистику потока Chat Completions.

Shell

curl -N --fail-with-body https://ai-router.foodpicasso.dev/api/v1/chat/completions \
  -H "Authorization: Bearer $PICASSO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "glm-5.3",
    "messages": [{"role": "user", "content": "Привет!"}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

Текст приходит в choices[].delta.content. Рассуждения могут приходить в расширении reasoning_content. Отсутствие текста рассуждений не означает сбой.

Обрыв соединения не считается успешным завершением. Для переведённого Chat-потока шлюз может отправить event: error и закрыть поток без [DONE]. Не запускайте автоматически второй запрос, если первый уже выдал данные.

Anthropic Messages

Нативный протокол для Claude и совместимого GLM. Пример с Claude, если модель доступна вашему токену:

Shell

curl --fail-with-body https://ai-router.foodpicasso.dev/api/v1/messages \
  -H "x-api-key: $PICASSO_TOKEN" \
  -H 'anthropic-version: 2023-06-01' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Привет!"}]
  }'

OpenAI Responses

Нативный путь для GPT и совместимого GLM. Для GPT тело не переводится: используйте полноценный Codex-совместимый запрос и HTTP SSE. Если нужен простой запрос обычного OpenAI-клиента, начните с Chat Completions.

Совместимость и ограничения

Сохраняются GLM-пути: /api/coding/paas/v4/chat/completions, /api/anthropic/v1/messages и его /count_tokens, а также /api/v1/completions. Произвольные операции аккаунта или файлов не проксируются.

Предел тела Chat Completions и legacy GLM: 8 MiB. Общие Messages/Responses: 32 MiB. Превышение возвращает HTTP 413. WebSocket не поддерживается. Лимиты параллелизма и тайм-ауты задаются сервером.

Исходные контракты протоколов: Z.ai, Anthropic Messages, OpenAI Responses. Возможности исходного API не означают поддержку всех этих возможностей шлюзом.

Модели и протоколы

Как выбрать модель и проверить доступ.