Для улучшения работы сайта мы используем файлы cookies. Оставаясь на сайте, вы соглашаетесь с политикой обработки персональных данных.

Прямой доступ к Gate API

Этот раздел предназначен для сценариев, когда запросы к языковым моделям отправляются программно из приложения, скрипта или инструмента (например, curl, Python, JavaScript), минуя веб-интерфейс StarGuard Gate.

StarGuard Gate одновременно реализует OpenAI- и Anthropic-совместимый API. Любой клиент, работающий с этими API, можно направить на Gate без изменения кода — достаточно поменять базовый URL и токен.

Если администратор развернул шлюз в режиме forward proxy, менять базовый URL не нужно вовсе — см. Доступ через forward proxy.

1. Получение токена

Токен доступа отображается в карточке Персональный токен на дашборде (Дашборд).

  1. Откройте дашборд (раздел «Обзор»).

  2. В карточке «Персональный токен» нажмите кнопку Копировать.

  3. Полное значение токена скопировано в буфер обмена.

Токен выдан корпоративным Identity Provider и действует столько же, сколько текущая сессия портала. По истечении срока войдите в StarGuard Gate повторно — токен обновится.

2. Эндпоинты

В зависимости от используемого клиентского формата:

Формат Эндпоинт

OpenAI Chat Completions

POST <GATE_URL>/v1/chat/completions

OpenAI Completions

POST <GATE_URL>/v1/completions

OpenAI Responses

POST <GATE_URL>/v1/responses

Anthropic Messages

POST <GATE_URL>/v1/messages

Список доступных моделей

GET <GATE_URL>/v1/models

Проверка запроса без обращения к модели

POST <GATE_URL>/v1/check

Где <GATE_URL> — адрес StarGuard Gate, предоставленный администратором.

Если развертывание производилось с использованием стандартных docker compose или Helm Chart, полный <GATE_URL> будет состоять из FQDN модуля Gate и постфикса /gate. Например: <GATE_URL> - ai-portal.company.com/gate, тогда URL эндпоинта - https://ai-portal.company.com/gate/v1/chat/completions

3. Аутентификация

Передайте токен в заголовке Authorization:

Authorization: Bearer <токен>

4. Пример запроса в формате OpenAI (curl)

curl -X POST https://<GATE_URL>/v1/chat/completions \
  -H "Authorization: Bearer <токен>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<идентификатор модели>",
    "messages": [
      {"role": "user", "content": "Привет! Расскажи кратко о себе."}
    ]
  }'

Идентификатор модели берётся из карточки «Доступные модели» на дашборде.

5. Пример запроса в формате Anthropic (curl)

curl -X POST https://<GATE_URL>/v1/messages \
  -H "Authorization: Bearer <токен>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<идентификатор модели>",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Привет! Расскажи кратко о себе."}
    ]
  }'

6. Запросы в формате OpenAI Responses

Формат Responses поддерживается с одним обязательным условием: в теле запроса должно быть явно указано "store": false.

curl -X POST https://<GATE_URL>/v1/responses \
  -H "Authorization: Bearer <токен>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<идентификатор модели>",
    "store": false,
    "input": "Привет! Расскажи кратко о себе."
  }'

StarGuard Gate не хранит состояние диалога и не позволяет хранить его на стороне провайдера: только так все проверки безопасности видят полный контекст запроса. Из этого следуют ограничения:

Условие Результат

"store": true или поле store отсутствует

Отказ 400, код store_not_allowed. Значение по умолчанию в Responses API — true, поэтому поле нужно указывать явно

Указан previous_response_id

Отказ 400, код previous_response_not_allowed

Указан conversation

Отказ 400, код conversation_not_allowed

В input присутствует элемент типа item_reference

Отказ 400, код item_reference_not_allowed

Клиент, лишённый серверной памяти, должен присылать полный контекст в каждом запросе. Параметр include: ["reasoning.encrypted_content"] при этом разрешён — именно так сохраняется цепочка рассуждений модели без серверного хранилища.

7. Потоковый режим

Для получения ответа в потоковом режиме (Server-Sent Events) добавьте "stream": true:

curl -X POST https://<GATE_URL>/v1/chat/completions \
  -H "Authorization: Bearer <токен>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<идентификатор модели>",
    "messages": [
      {"role": "user", "content": "Напиши короткое стихотворение."}
    ],
    "stream": true
  }'

Ответ возвращается в формате data: {…​} фрагментами. Последний фрагмент — data: [DONE] для форматов OpenAI Chat Completions и Anthropic. В формате Responses поток закрывается событием response.completed.

Если администратор включил проверку ответов модели, шлюз получает ответ целиком, проверяет его и только затем отдаёт клиенту потоком. Время до первого фрагмента в этом случае увеличивается.

8. Передача вложений

Документы и изображения передаются в нативных для выбранного формата блоках сообщения (file / image_url в OpenAI Chat Completions, input_file / input_image в Responses, document / image в Anthropic Messages).

Шлюз распознаёт вложение и заменяет его текстом перед отправкой в модель, поэтому:

  • документ передается как распознанный текст, а не как файл;

  • этот текст проходит все проверки безопасности наравне с обычным сообщением;

  • вложение, которое нельзя перевести в текст (ссылка на файловое хранилище провайдера, URL, аудио), отклоняется с кодом 400.

Точные правила — какие типы вложений принимаются и что делать с изображениями — задаёт администратор в настройках шлюза.

9. Проверка запроса без обращения к модели

Эндпоинт POST /v1/check прогоняет запрос через входные детекторы и возвращает результат проверки, не обращаясь к языковой модели. Тело запроса совпадает с телом обычного запроса в формате Chat Completions или Messages.

curl -X POST https://<GATE_URL>/v1/check \
  -H "Authorization: Bearer <токен>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<идентификатор модели>",
    "messages": [
      {"role": "user", "content": "Проверяемый текст"}
    ]
  }'

Ответ содержит признак прохождения проверки, имя сработавшего детектора и описание причины. Код 200 означает, что запрос прошёл проверки, 403 — что он был бы заблокирован.

10. Коды ответов

Код Описание

200 OK

Запрос обработан успешно. Заблокированный запрос также возвращает 200: вместо ответа модели приходит ответ в нативном формате, текст которого объясняет причину блокировки. Исключение — POST /v1/check, где блокировка возвращает 403

400 Bad Request

Нарушены условия формата Responses (Прямой доступ к Gate API) либо вложение не может быть обработано (недопустимый тип, неподдерживаемый источник)

401 Unauthorized

Токен отсутствует, недействителен или истёк

403 Forbidden

Нет доступа к запрошенной модели. Для POST /v1/check — запрос заблокирован детектором

413 Payload Too Large

Тело запроса превышает предельный размер, заданный администратором

500 Internal Server Error

Внутренняя ошибка StarGuard Gate

502 Bad Gateway

Внешний LLM-провайдер вернул ошибку либо не удалось распознать вложение

Почему блокировка приходит с кодом 200. Так клиентские библиотеки OpenAI и Anthropic получают корректный ответ вместо исключения, и причина блокировки отображается в интерфейсе приложения как обычный ответ модели. Проверять факт блокировки программно удобнее эндпоинтом POST /v1/check.