Models

Интерфейс списка моделей отвечает на один вопрос: какие модели может вызывать текущий токен. Возвращается результат, отфильтрованный по правам токена, группе и статусу публикации, а не полный каталог моделей платформы. Значение model в запросе обязано быть взято из этого списка.

Получение списка доступных моделей

GET /v1/models

curl https://api.routeapi.ai/v1/models \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

Ответ:

{
  "success": true,
  "object": "list",
  "data": [
    {
      "id": "gpt-5.5",
      "object": "model",
      "created": 1626777600,
      "owned_by": "openai",
      "supported_endpoint_types": ["openai", "openai-response"]
    },
    {
      "id": "claude-sonnet-4-5",
      "object": "model",
      "created": 1626777600,
      "owned_by": "anthropic",
      "supported_endpoint_types": ["openai", "anthropic"]
    },
    {
      "id": "text-embedding-3-large",
      "object": "model",
      "created": 1626777600,
      "owned_by": "openai",
      "supported_endpoint_types": ["embeddings"]
    }
  ]
}

Поле	Описание
`id`	Значение, которое подставляется в `model` при вызове; единственный надёжный идентификатор модели
`object`	Всегда `"model"`
`created`	Фиксированное значение-заполнитель `1626777600`, это не реальное время публикации; не используйте его для сортировки или оценки новизны
`owned_by`	Тип канала, к которому относится модель (например, `openai`, `anthropic`); для собственных моделей платформы — `custom`
`supported_endpoint_types`	Список типов эндпоинтов, доступных для этой модели, см. Типы эндпоинтов ниже

В корне ответа одновременно присутствуют success и поля object/data в стиле OpenAI. OpenAI SDK читает только data, дополнительное поле success не мешает разбору.

Порядок элементов в data не гарантируется: два запроса могут вернуть разный порядок. Если нужен фиксированный порядок, сортируйте на стороне клиента.

Типы эндпоинтов

supported_endpoint_types — это расширенное поле RouteAPI и единственный сигнал о возможностях в списке моделей. Оно показывает, через какие протокольные входы можно вызвать эту модель:

Значение	Соответствующий эндпоинт
`openai`	`POST /v1/chat/completions`
`openai-response`	`POST /v1/responses`
`anthropic`	`POST /v1/messages`
`gemini`	`POST /v1beta/models/{model}:generateContent`
`embeddings`	`POST /v1/embeddings`
`image-generation`	`POST /v1/images/generations`
`jina-rerank`	`POST /v1/rerank`
`openai-video`	Эндпоинт генерации видео OpenAI
`suno-*`	Эндпоинты серии Suno, см. Suno API

Если в supported_endpoint_types модели нет значения embeddings, не передавайте её в /v1/embeddings — такое несоответствие приведёт к сбою на этапе проксирования.

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

Запрос одной модели

GET /v1/models/{model}

curl https://api.routeapi.ai/v1/models/gpt-5.5 \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

Если модель существует, объект модели возвращается напрямую (без обёртки data):

{
  "id": "gpt-5.5",
  "object": "model",
  "created": 1626777600,
  "owned_by": "openai"
}

Если модель не существует или недоступна текущему аккаунту, возвращается:

{
  "error": {
    "message": "The model 'foo' does not exist",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

Обратите внимание: HTTP-статус при этом остаётся 200. Этот интерфейс помещает ошибку в поле error тела ответа и не выражает «модель не существует» через статус-код. Клиент обязан проверять наличие error в теле ответа; если смотреть только на HTTP-статус, сбой будет принят за успех.

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

Список моделей в других протоколах

Один и тот же набор доступных моделей можно получить в трёх форматах протоколов — выбирайте по вашему SDK.

Формат Claude Messages

Если в запросе GET /v1/models одновременно передать заголовки x-api-key и anthropic-version, ответ будет в стиле Anthropic:

curl https://api.routeapi.ai/v1/models \
  -H "x-api-key: $ROUTEAPI_KEY" \
  -H "anthropic-version: 2023-06-01"

{
  "data": [
    {
      "id": "claude-sonnet-4-5",
      "created_at": "2021-07-20T12:00:00Z",
      "display_name": "claude-sonnet-4-5",
      "type": "model"
    }
  ],
  "first_id": "claude-sonnet-4-5",
  "has_more": false,
  "last_id": "claude-sonnet-4-5"
}

Переключение на этот формат происходит только при одновременном наличии обоих заголовков: если передать лишь x-api-key, ответ по-прежнему будет в формате OpenAI. Значение display_name равно id, это не отображаемое имя из консоли. has_more всегда false — список возвращается целиком за один раз, постраничного вывода нет. Когда список пуст, first_id и last_id — пустые строки.

Формат Gemini

curl "https://api.routeapi.ai/v1beta/models" \
  -H "x-goog-api-key: $ROUTEAPI_KEY"

{
  "models": [
    { "name": "gemini-2.5-pro", "displayName": "gemini-2.5-pro" }
  ],
  "nextPageToken": null
}

Объект модели в формате Gemini содержит также поля inputTokenLimit, supportedGenerationMethods и другие, но RouteAPI заполняет только name и displayName, а остальные поля возвращает как null. Не опирайтесь на эти пустые поля при определении возможностей модели.

Для списка моделей по протоколу Gemini используйте путь /v1beta/models, не передавайте заголовки Gemini в /v1/models.

Без префикса /v1

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

Четыре фильтра, определяющие содержимое списка

Чтобы модель попала в ваш список, она должна пройти все четыре фильтра одновременно. При диагностике ситуации «модели нет в списке» проверяйте их в этом порядке:

Белый список моделей токена — если для токена включено ограничение по моделям, список равен пересечению белого списка с остальными условиями. Если ограничение не включено, переходите к следующему пункту.
Включённые модели группы — берётся объединение включённых моделей вашей пользовательской группы (и группы, указанной в токене). Модель без ни одного доступного канала в список не попадёт.
Статус публикации в каталоге — когда на платформе включён строгий режим метаданных, неопубликованная модель снаружи равнозначна несуществующей.
Настроена ли цена — модели без настроенной цены по умолчанию отфильтровываются, если только на платформе не включён режим для личного использования или в настройках вашего аккаунта не включён параметр «принимать модели без установленной цены».

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

На одной и той же платформе списки моделей у разных токенов могут полностью различаться. Запросить список токеном A, а отправить запрос токеном B — типичная ошибка: при диагностике обязательно делайте и то, и другое одним и тем же токеном.

Диагностика недоступности модели

Если запрос возвращает ошибку, связанную с моделью, сначала определите конкретный этап по тексту ошибки:

Текст ошибки	HTTP	Значение	Что делать
`Model name not specified...`	400	В запросе `model` пустой	Добавьте поле `model`
`This token has no access to model {model}`	403	Модели нет в белом списке этого токена	Добавьте модель токену в консоли или используйте токен без ограничения по моделям
`This token has no access to any models`	403	Для токена включено ограничение по моделям, но белый список пуст	Заполните белый список
`No valid upstream service`	503	У модели нет доступных каналов (не настроены, все отключены или сработал предохранитель)	Проверьте написание ID модели; попробуйте другую модель из списка; обратитесь к администратору платформы
`The model '{model}' does not exist`	200 (`error` в теле)	`GET /v1/models/{model}` не находит модель или она недоступна	Уточните точный ID через `GET /v1/models`

Порядок диагностики:

Вызовите GET /v1/models тем же самым токеном и убедитесь, что модель действительно есть в списке.
Посимвольно сверьте написание model, включая регистр и дефисы. ID модели сопоставляется строго.
Убедитесь, что вызываемый эндпоинт входит в supported_endpoint_types этой модели.
Если всё выше верно, но запрос всё равно падает, проблема на стороне канала (нет доступного вышестоящего сервиса или он вернул ошибку): найдите конкретный ответ вышестоящего сервиса в логах консоли по request ID. Подробнее см. Ошибки и отладка.

Что дальше

Аутентификация — права токена, белый список моделей и настройка квоты.
Chat Completions — диалог с моделью из списка.
Ошибки и отладка — полный перечень статус-кодов и порядок диагностики.
Биллинг и квоты — цены моделей и учёт потребления.