Справочник API моделей

Model API обрабатывает запросы вашей компании к моделям. Отдельный Partner API управляет учётными данными и предоставляет владельцу записи об операциях. Выбирайте интерфейс по выполняемой операции, а не по тому, какой токен оказался под рукой.

Семейства протоколов

Используйте Messages для диалогов в формате Anthropic, Chat Completions для клиентов со списком сообщений и Responses для типизированных входных и выходных элементов и поддерживаемых инструментов поставщика. Для эмбеддингов и изображений нужны модели и маршруты с соответствующими возможностями.

Операции

Пути перечислены в указателе эндпоинтов. Потоковые ответы описывают постепенную передачу результата. Отложенные запросы, пакеты Messages и Files/Batch — отдельные режимы выполнения. Для исследования доступности используйте диагностику ошибок и проверки состояния.

Идентификаторы и модели во всех примерах условные. Заменяйте их каноническим ID или псевдонимом из каталога, полученного с вашей авторизацией. Доступность в каталоге определяет возможности конкретной установки; скопированный пример их не определяет.

Идентификатор диалога и привязка маршрута

Session ID обозначает один диалог. Sticky routing — отдельное предпочтение доступного маршрута или аккаунта поставщика, выполняемое по возможности. Model API принимает идентификатор сессии независимо от выбранного поставщика или модели в общем JSON-маршруте генерации, включая Chat Completions, Messages и Responses. Способ передачи поставщику зависит от возможностей выбранного маршрута; неподдерживающие поставщики не получают неизвестное поле session_id.

Используется первое непустое значение: JSON session_id, затем заголовок X-Session-ID, затем распознанная сессия в metadata.user_id, затем JSON prompt_cache_key. Если этих сигналов нет, Model API вычисляет идентификатор по начальному содержимому system/developer и первому сообщению пользователя. Добавление последующих сообщений, в том числе рост истории с 41 до 43 сообщений, не меняет этот начальный идентификатор. Для такого автоматического поведения менять клиент не нужно.

Уже заданная сессия в metadata.user_id — сигнал совместимости, а не конфликт. Распознаются формы session_<id>, user_<device>_account_<account>_session_<id> и JSON-строка с непустым строковым session_id. Сессионная часть используется только при отсутствии более приоритетных полей. Например, session_chat-42 задаёт идентификатор диалога chat-42. На маршруте с таким способом передачи метаданных изолируется только сессионная часть; сведения об устройстве, аккаунте и остальные метаданные сохраняются. Разные явные поля подчиняются указанному приоритету, а не вызывают ошибку несовпадения.

Обычное значение, например customer_42, не считается идентификатором диалога автоматически. Оно сохраняется без ошибки несовпадения. Маршрут, использующий это занятое поле для передачи сессии, не может одновременно вставить в него управляемую сессию; внутренняя маршрутизация продолжает работать, но внешнее закрепление за аккаунтом и попадание в кеш не обещаются. Для точной идентификации диалога используйте уникальный session_id или X-Session-ID и совместимый способ передачи поставщику. Необязательный разбор оболочки метаданных ограничен 4096 байтами UTF-8; сессионная часть проверяется по тем же правилам ID. Неизвестные или неоднозначные строковые оболочки остаются обычными метаданными.

Для точного разделения создавайте уникальный ID на каждый диалог и повторяйте его в следующих обращениях. Одинаковое начало может дать общую автоматическую сессию; изменение или удаление начала может сменить её. При сжатии истории или смене протокола используйте явный ID. Непустые идентификаторы должны быть строками не более 512 байт UTF-8 без управляющих символов; пробелы по краям удаляются. Несколько заголовков X-Session-ID недопустимы.

{"session_id":"project-chat-123"}

Добавьте это поле в полный запрос генерации либо передайте заголовок X-Session-ID: project-chat-123. Не включайте в ID ключи доступа или персональные данные. Идентификатор изолирован по аутентифицированному аккаунту, API-ключу и канонической модели; изменение любого из них меняет область привязки. Потоковый режим и поддерживаемая асинхронная отправка сохраняют выбранный идентификатор.

Идентификатор сессии не заменяет аутентификацию, ключ идемпотентности или хранение диалога на сервере. Продолжайте передавать контекст, требуемый выбранным протоколом. Он не гарантирует попадание в кеш или постоянный аккаунт и не обходит права доступа, баланс или лимиты запросов. Переключение на допустимый резервный маршрут сохраняется. Для запросов Responses с previous_response_id действуют более строгие ограничения маршрутизации: не рассчитывайте восстановить отсутствующее состояние по началу диалога.

Стабильное начало и отдельная передача поставщику

Внутренний автоматический хеш не учитывает cache_control в известных блоках содержимого и считает одиночный простой текстовый блок эквивалентным такой же строке. Эта нормализация не меняет запрос, отправляемый модели. Пробелы в тексте, данные и детализация изображений, неизвестные свойства и вложенный JSON инструментов сохраняют значение. Изменение самого начала или протокола всё ещё может сменить автоматическую сессию; при сжатии истории или переходе между протоколами нужен явный ID. Распознанная metadata-сессия важнее подсказки кеширования: изменение prompt_cache_key не разделяет такой диалог.

Model API не патчит Sub2API и не использует собственный протокол получателя. Для подключения Sub2API OpenAI/Codex управляемая сессия переводится в уже существующие сигналы OpenAI-совместимой ветки: scoped-заголовок Session_id и prompt_cache_key. Для подключения Sub2API Anthropic/Claude распознанная сессия переносится через metadata.user_id; обычный занятый ID пользователя сохраняется и не может одновременно нести управляемую сессию. Клиентские session_id / X-Session-ID остаются публичными входными сигналами Model API, но это не означает, что X-Session-ID является универсальным egress-контрактом Sub2API. Смешанные подключения нужно разделять по фактической протокольной группе, а не вводить общий самодельный транспорт.

Шлюз может предварительно предпочитать один доступный маршрут для одновременных первых запросов, а после успеха подтверждать привязку. Это не разрешение превышать лимиты, обходить eligibility аккаунтов Sub2API, восстанавливать неизвестное состояние Responses или гарантировать попадание в кеш. Поздно завершившийся старый запрос не может перезаписать более новую привязку.

Предварительное предпочтение маршрута сохраняется только пока у этого размещения есть хотя бы один реально выполняющийся запрос. Отдельного 60-секундного срока маршрутизации больше нет: защитой от зависшего владельца служит существующий lease запроса. После последней неудачи выполняющихся владельцев такое размещение снимается; пригодная подтверждённая привязка имеет приоритет. Это не повтор платного запроса и не выбор аккаунта внутри внешнего шлюза. При вычислении якоря также игнорируется prompt_cache_breakpoint в блоках text/input_text; отправляемый провайдеру запрос не изменяется.