Chat Completions

Общие сведения

• Base URL: https://api.routeapi.ai
• Аутентификация: Authorization: Bearer $ROUTEAPI_KEY с API Key, начинающимся с sk- (создаётся на странице API-ключи). Управляющие ключи с префиксом rat_ не могут вызывать модели.
• Формат ошибок: {"error": {"message": "...", "type": "...", "code": "..."}}; значения кодов состояния описаны в разделе Частые ошибки.

Chat Completions — самый распространённый диалоговый API. Он подходит для чата, помощников по коду, резюме, классификации, вызова инструментов и многоходовых диалогов.

Эндпоинт следует протоколу OpenAI Chat Completions, поэтому в существующей интеграции с OpenAI достаточно заменить Base URL и API-ключ. Через тот же эндпоинт доступны модели Claude, Gemini и других поставщиков: RouteAPI преобразует форматы запроса и ответа внутри.

Endpoint

POST /v1/chat/completions

Полный адрес:

https://api.routeapi.ai/v1/chat/completions

Если в клиенте Base URL указан без /v1 (например, https://api.routeapi.ai), запросы к /chat/completions тоже принимаются: RouteAPI переписывает их в /v1/chat/completions.

Пример запроса

curl https://api.routeapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      { "role": "user", "content": "Представь RouteAPI одним предложением" }
    ]
  }'

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

Поле	Тип	Обязательное	Описание
model	string	Да	ID модели, доступной текущему аккаунту
messages	array	Да	Список сообщений диалога
stream	boolean	Нет	Потоковая выдача через SSE, по умолчанию false
temperature	number	Нет	Температура сэмплирования
top_p	number	Нет	Параметр nucleus sampling
max_tokens	number	Нет	Максимальное число выходных токенов
max_completion_tokens	number	Нет	Новое имя ограничения вывода; если заданы оба поля, RouteAPI при собственном ограничении и учёте использует его
stop	string/array	Нет	Пользовательские стоп-последовательности
n	integer	Нет	Число кандидатов; вернёт ли сервис больше одного, зависит от модели
presence_penalty	number	Нет	Штраф за присутствие
frequency_penalty	number	Нет	Штраф за частоту
seed	number	Нет	По возможности фиксирует сэмплирование; воспроизводимость зависит от модели
user	string	Нет	Идентификатор конечного пользователя, передаётся поддерживающим его сервисам
tools	array	Нет	Определения инструментов
tool_choice	string/object	Нет	Политика выбора инструмента
response_format	object	Нет	JSON mode или JSON Schema
stream_options	object	Нет	Дополнительные параметры потока, например include_usage

Необязательные поля передаются как есть: отсутствующее поле не заполняется значением по умолчанию. Подробнее см. «Явные нулевые значения» ниже.

Формат messages

[
  { "role": "system", "content": "Ты строгий технический ассистент." },
  { "role": "user", "content": "Объясни, что такое API-шлюз." }
]

Основные роли:

Role	Описание
system	Системная инструкция
user	Ввод пользователя
assistant	Предыдущий ответ модели
tool	Результат вызова инструмента

content может быть строкой или массивом блоков для мультимодального ввода, см. Мультимодальный ввод. Если сообщение assistant содержит вызовы инструментов, верните его без изменений и добавьте результаты с role: "tool", см. Вызов инструментов.

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

{
  "id": "chatcmpl_xxx",
  "object": "chat.completion",
  "created": 1730000000,
  "model": "gpt-5.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "RouteAPI — это API-шлюз, объединяющий доступ к моделям разных поставщиков."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 18,
    "total_tokens": 42
  }
}

finish_reason показывает причину завершения: stop (естественное окончание), length (достигнут лимит вывода), tool_calls (модель запрашивает вызов инструмента) или content_filter (сработал фильтр содержимого).

Потоковая выдача

При stream: true ответ приходит как Server-Sent Events. Каждая строка — chat.completion.chunk, приращение лежит в choices[0].delta, поток завершается data: [DONE]:

data: {"id":"chatcmpl_xxx","object":"chat.completion.chunk","created":1730000000,"model":"gpt-5.5","choices":[{"index":0,"delta":{"content":"RouteAPI"},"finish_reason":null}]}

data: {"id":"chatcmpl_xxx","object":"chat.completion.chunk","created":1730000000,"model":"gpt-5.5","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

По умолчанию перед data: [DONE] RouteAPI добавляет финальный чанк с расходом токенов и пустым choices. Передайте "stream_options": {"include_usage": false}, чтобы его отключить (каналы без поддержки stream_options присылают его всегда); расход всё равно записывается в логи консоли. Полная обработка событий и ошибки посреди потока описаны в разделе Потоковые ответы.

Настройка SDK

Официальные SDK OpenAI работают без изменений, если указать в них ключ RouteAPI и Base URL.

OpenAI Python SDK

pip install openai

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai/v1",
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Представь RouteAPI одним предложением"}],
)

print(response.choices[0].message.content)

OpenAI Node.js SDK

npm install openai

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.ROUTEAPI_KEY,
  baseURL: 'https://api.routeapi.ai/v1',
});

const response = await client.chat.completions.create({
  model: 'gpt-5.5',
  messages: [{ role: 'user', content: 'Представь RouteAPI одним предложением' }],
});

console.log(response.choices[0].message.content);

LangChain и LiteLLM

Обе библиотеки принимают собственный OpenAI-совместимый эндпоинт:

import os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-5.5",
    openai_api_key=os.environ["ROUTEAPI_KEY"],
    openai_api_base="https://api.routeapi.ai/v1",
)

import os
import litellm

response = litellm.completion(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Представь RouteAPI одним предложением"}],
    api_key=os.environ["ROUTEAPI_KEY"],
    api_base="https://api.routeapi.ai/v1",
)

Другие совместимые клиенты

Любой клиент с настраиваемым Base URL OpenAI подключается теми же тремя настройками:

1. API-ключ — API Key RouteAPI, начинающийся с sk-.
2. Base URL — https://api.routeapi.ai/v1.
3. Модель — ID из ответа GET /v1/models, см. Models.

Готовые конфигурации для Codex, Cursor, Claude Code, OpenCode и других инструментов — в разделе Переход с OpenAI.

Отличия от официального OpenAI API

Более широкий набор моделей

Официальный OpenAI API обслуживает только модели OpenAI. Здесь в том же поле model можно указать модели разных поставщиков — например gpt-5.5, claude-sonnet-4-5 или gemini-2.5-pro — в зависимости от того, что доступно вашему ключу и группе. Какие модели можно вызывать, показывает только GET /v1/models.

Биллинг и лимиты управляются RouteAPI

• Биллинг идёт по прайс-листу RouteAPI, который может отличаться от официальных цен поставщика.
• Лимиты запросов определяются политикой RouteAPI, а не лимитами самого поставщика.
• Баланс и квоты ключей управляются в консоли RouteAPI.

Подробнее: Биллинг и квоты и Цены моделей.

Возможности зависят от выбранной модели

Протокол определяет поля, а работают ли они — решает модель. Вызов инструментов, ввод изображений, структурированный вывод, расход в потоке и управление рассуждением зависят от выбранной модели и стоящего за ней сервиса. Эндпоинт списка моделей не возвращает флаги возможностей, поэтому проверьте нужные реальным запросом до вывода в продакшен.

Явные нулевые значения

Необязательные параметры, переданные как 0, 0.0 или false, сохраняются и передаются дальше, а не отбрасываются как «не заданные». Это позволяет зафиксировать temperature: 0 для детерминированного сэмплирования. Чтобы оставить параметр незаданным, уберите поле, а не передавайте null.

Ошибки вышестоящего сервиса

Когда сервис модели отклоняет запрос, RouteAPI возвращает его статус-код и сообщение в стандартном теле ошибки, добавляя (request id: <id>). Ошибки до маршрутизации — неверный ключ, модель не разрешена, нет доступного канала — используют коды из раздела Частые ошибки.

Примечания по совместимости

• Поддержка одного и того же параметра может отличаться у разных сервисов моделей.
• Если запрос содержит необязательные параметры вроде tools, response_format или stream_options, сначала убедитесь, что выбранная модель их поддерживает.
• Явно переданные 0 или false необязательные параметры считаются заданными пользователем.
• При совместном использовании структурированного вывода и вызова инструментов сначала прочитайте ограничения в разделе Структурированный вывод.

Что дальше

• Responses — более новый протокол OpenAI, распространён в агентах для кода.
• Claude Messages — нативный формат Anthropic для функций, специфичных для Claude.
• Google Gemini API — нативный формат Google.
• Models — какие модели доступны вашему ключу и их типы эндпоинтов.