API Endpoints

POST /v1/chat/completions

Основной endpoint. Полностью совместим с форматом OpenAI Chat Completions.

Параметры запроса

Параметр	Тип	Обязательный	Описание
`model`	string	Да	Имя модели: `yandex/yandexgpt`, `sber/gigachat-2-max`, `Qwen/Qwen3-235B-A22B-Instruct-2507` и др.
`models`	array	Нет	Fallback-модели. Если `model` недоступна — попробует модели из этого списка по порядку
`messages`	array	Да	Массив сообщений с `role` (`system` / `user` / `assistant` / `developer` / `tool`) и `content`
`stream`	boolean	Нет	Потоковая генерация (SSE). По умолчанию `false`
`temperature`	float	Нет	Креативность ответа (0.0 — точный, 1.0 — творческий)
`max_tokens`	integer	Нет	Максимум токенов в ответе
`top_p`	float	Нет	Nucleus sampling
`stop`	string / array	Нет	Стоп-последовательности
`reasoning_effort`	string	Нет	Уровень рассуждений: `low`, `medium`, `high`. Для моделей с reasoning
`provider`	object	Нет	Управление маршрутизацией (см. раздел «Маршрутизация»)

Пример ответа

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1717401600,
  "model": "yandex/yandexgpt",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Привет! Чем могу помочь?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 8,
    "total_tokens": 20
  }
}

GET /v1/models

Возвращает список всех доступных моделей в стандартном формате OpenAI.

{
  "object": "list",
  "data": [
    {"id": "yandex/yandexgpt", "object": "model", "owned_by": "yandex"},
    {"id": "sber/gigachat-2-max", "object": "model", "owned_by": "sber"},
    {"id": "Qwen/Qwen3-235B-A22B-Instruct-2507", "object": "model", "owned_by": "yandex"}
  ]
}

GET /v1/models/info

Расширенная информация о моделях с провайдерами, ценами и производительностью. Не требует авторизации.

{
  "data": [
    {
      "id": "yandex/yandexgpt",
      "type": "chat",
      "owned_by": "yandex",
      "context_window": 32768,
      "capabilities": ["openai_compat", "streaming"],
      "providers": [
        {
          "provider": "yandex",
          "status": "ok",
          "latency_ms": 1250.5,
          "throughput_tps": 45.2,
          "tested_at": "2025-01-15T10:30:00Z",
          "pricing": {
            "prompt": 1220,
            "completion": 1220,
            "currency": "RUB",
            "unit": "1M tokens"
          }
        }
      ]
    }
  ]
}

GET /health

Проверка работоспособности системы. Не требует авторизации.

Возвращает статус сервера, здоровье провайдеров и live-метрики за последние 5 минут:

{
  "status": "ok",
  "providers": {
    "yandex": {"recent_errors": 1, "window_sec": 30, "threshold": 3}
  },
  "metrics": {
    "yandex": {
      "latency_ms": {"p50": 1200, "p90": 2500, "p99": 3800},
      "throughput_tps": {"p50": 45, "p90": 30, "p99": 25},
      "samples": 156,
      "window_sec": 300.0
    }
  }
}

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

Каждый ответ содержит заголовки маршрутизации:

Заголовок	Описание
`X-TsarRouter-Provider`	Провайдер, который обработал запрос
`X-TsarRouter-Model`	Модель, которая реально ответила (полезно при fallback)
`X-TsarRouter-Attempts`	JSON-массив всех попыток маршрутизации