Keural API

Вызов модели, зарегистрированной в Keural, в формате OpenAI Chat Completions.

Base URL имеет вид https://<публичный домен API для среды>/llm/v1. Публичный домен API зависит от среды, уточните его у администратора.

Пути для эмбеддингов, генерации изображений, голоса и Responses API не поддерживаются и возвращают 404.

Порядок использованияКопировать ссылку на раздел

Предварительные условияКопировать ссылку на раздел

Выпуск ключа APIКопировать ссылку на раздел

1. Откройте меню аккаунта, выберите Настройки → API. В настольном и мобильном приложениях раздел находится в группе Инструменты.
2. На вкладке API keys выберите владельца ключа (личное или рабочее пространство организации) и Model ID.
3. При необходимости задайте New key expiration (optional, Korea time). Если поле оставить пустым, ключ будет действовать бессрочно, пока его не отзовут.
4. Нажмите Issue key и скопируйте ключ кнопкой Copy key, затем сохраните его в надёжном месте. Полный ключ отображается только один раз.

• Ключ привязан к выбранному рабочему пространству и одной модели. Использование относится к тому, кто выпустил ключ.
• Для одного рабочего пространства и модели существует только один ключ. Чтобы получить новый, переиздайте или отзовите существующий.
• Если ключ утерян, переиздайте его: посмотреть ключ повторно нельзя. После переиздания предыдущий ключ сразу перестаёт работать.
• Если моделей для выпуска нет, попросите администратора проверить публичные настройки модели, тариф и разрешение API организации.

Разрешения API для участников организацииКопировать ссылку на раздел

Этот раздел предназначен для владельцев и администраторов организации. Чтобы участники получали ключи в рабочем пространстве организации, администратор должен сначала разрешить им это. По умолчанию доступ заблокирован для всех участников.

Управление организацией → Organization API состоит из трёх разделов. Если меню не отображается, функция API выключена или у аккаунта нет права управления организацией.

Когда участник выходит из организации или удаляется из неё, ключи, полученные им от организации, автоматически отзываются.

Подключение к клиентуКопировать ссылку на раздел

В приложении, совместимом с OpenAI API (клиент для чата, расширение IDE, инструмент автоматизации), укажите три значения:

1. В настройках приложения добавьте подключение, совместимое с OpenAI (Connection).
2. Укажите Base URL и API Key и сохраните.
3. Выберите модель в списке моделей. В списке отображается только одна модель, подключённая к ключу.
4. Отправьте короткое сообщение и проверьте, что пришёл ответ.

Формат запросов:

Первый запросКопировать ссылку на раздел

export KEURAL_API_KEY='your_issued_key'
export KEURAL_BASE_URL='https://<публичный домен API для среды>/llm/v1'
export MODEL_ID='ID модели с экрана выпуска'

curl "$KEURAL_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KEURAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Здравствуйте.\"}]}"

Значение model в теле запроса должно совпадать с ID модели, подключённой к ключу. Если перед ним стоит путь вида provider/ID-модели, сравнивается часть после последнего /. Если не совпадает, возвращается 403. В ответе поле model всегда содержит ID модели из ключа.

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["KEURAL_API_KEY"],
    base_url=os.environ["KEURAL_BASE_URL"],
)
res = client.chat.completions.create(
    model=os.environ["MODEL_ID"],
    messages=[{"role": "user", "content": "Здравствуйте."}],
)
print(res.choices[0].message.content)

Поддерживаемые поля запросаКопировать ссылку на раздел

Принимаются только 18 полей верхнего уровня, перечисленных ниже. При отправке другого поля возвращается 400. Необязательные поля со значением null считаются не отправленными.

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

• Сообщение tool отвечает на каждый id из предыдущих tool_calls только один раз.
• Графические части (image_url) добавляются только в сообщения user для моделей, которые принимают изображения. Используйте адрес http или https, либо data URI в base64 формата PNG, JPEG, GIF или WebP. detail: auto, low или high.

Тело запросаКопировать ссылку на раздел

Нарушение правил тела запроса возвращает 400, при этом param: body.

Потоковая передачаКопировать ссылку на раздел

Если в запросе указано "stream": true, ответ отправляется через SSE. Каждый фрагмент передаётся как событие data: ..., в конце передаётся data: [DONE]. Если указано "stream_options": {"include_usage": true}, непосредственно перед [DONE] передаётся ещё один фрагмент с данными об использовании токенов.

При include_usage каждый фрагмент содержит usage: null, а последний фрагмент с использованием имеет пустой массив choices. Непотоковый ответ содержит usage только тогда, когда подтверждены и входные, и выходные токены.

Идентификатор ответа id имеет вид chatcmpl-<x-request-id>. Во всех заголовках ответа есть x-request-id.

При ошибке во время потоковой передачи отправляется событие data: с JSON ошибки, и соединение завершается без [DONE]. Если один фрагмент превышает 1 МиБ или ответ превышает 16 МиБ, ответ завершается с кодом 503.

curl -N "$KEURAL_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KEURAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Здравствуйте.\"}],\"stream\":true,\"stream_options\":{\"include_usage\":true}}"

Лимиты использованияКопировать ссылку на раздел

Ограничения действуют по пользователю, организации и модели: по числу одновременных запросов, числу запросов в минуту (RPM) и числу токенов в минуту (TPM). Фактические значения зависят от среды.

Токены в минуту списываются заранее, при получении запроса. Входной текст считается как 1 токен на 4 английских символа, остальные символы как 1 токен на символ, одно изображение как 2 000 токенов. Выход учитывается в объёме max_tokens (максимум 4 096), поэтому если задавать ограничение вывода только в нужном объёме, запас по лимиту будет больше.

Управление ключамиКопировать ссылку на раздел

На вкладке API keys в разделе Настройки → API можно проверить состояние ключей (действует, истёк срок, отозван), переиздать или отозвать их.

Ключ представляет собой строку из 51 символа, которая начинается с krl_llm_. Для одного владельца может быть только один ключ. Если он уже есть, ключ переиздаётся, а не выпускается новый. Срок действия можно задать только на дату после сегодняшнего дня.

Проверка использованияКопировать ссылку на раздел

Запросы через API и использование токенов можно проверить в двух местах.

Условия поискаКопировать ссылку на раздел

Задайте условия и нажмите Search. Чтобы увидеть последние запросы, нажмите Refresh.

Значения на экранеКопировать ссылку на раздел

• Applied time range (KST): фактически запрошенный период. Если время начала или окончания не задано или период превышает 90 дней, отображается период, скорректированный сервером.
• Requests и итоги Input tokens · Output tokens · Total tokens: суммируются только подтверждённые значения. Непроверенные токены отображаются как Unconfirmed.
• Список запросов: для каждого запроса показываются время запроса, Model ID, состояние запроса, входные, выходные и общие токены. На странице 20 записей, переход выполняется кнопками Previous и Next.

Нажмите Request details в строке, чтобы показать следующие значения.

Использование записывается и для потоковых запросов без stream_options.include_usage. Если запрос прервался, он может остаться со статусом Partially confirmed или Unconfirmed.

Формат ошибокКопировать ссылку на раздел

Ошибки возвращаются в формате, совместимом с OpenAI.

{
  "error": {
    "message": "Понятное описание ошибки",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null
  }
}

type определяется кодом состояния, а code позволяет различить причину.

Устранение неполадокКопировать ссылку на раздел

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

• Время возникновения проблемы
• Использованный ID модели
• Название и версия клиентского приложения
• x-request-id из заголовков ответа
• Сообщение об ошибке, показанное на экране