К содержимому

OpenAI Chat Completions API: запросы и ответы

Формат запроса и ответа OpenAI Chat Completions: адрес, заголовки, поля тела, ответ и ошибки.

Обзор метода

POST https://relay-llm.ru/v1/chat/completions принимает тело в формате OpenAI Chat Completions и возвращает ответ в том же формате.

Шлюз меняет в теле поле model, а в ответе возвращает то значение, которое вы отправили. В потоковом запросе он дополнительно включает stream_options.include_usage: true, чтобы посчитать расход, но отдаёт фрагмент с usage только тем клиентам, которые запросили его сами. Остальные поля уходят модели без изменений, поэтому поддержка конкретного параметра зависит от модели.

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

Передайте ключ в заголовке Authorization: Bearer RELAY_API_KEY или x-api-key: RELAY_API_KEY. Без ключа, а также с неверным, просроченным или отозванным ключом приходит ответ 401 с кодом invalid_api_key.

Не передавайте оба заголовка сразу. Если пришли оба, шлюз читает только Authorization: значение не в схеме Bearer он принимает за ключ целиком и на x-api-key не переключается.

Параметры тела

Тело запроса должно быть JSON-объектом. Повторяющееся поле верхнего уровня даёт ответ 400 invalid_request, даже если имена различаются только регистром (Model и model).

ПолеТипНазначение
modelstring, обязательноИдентификатор модели из каталога или заведённый для неё алиас. Неизвестная модель даёт ответ 404 с кодом model_not_found.
messagesarrayСообщения диалога в формате OpenAI. Структуру шлюз не проверяет: по размеру текста и числу картинок он оценивает стоимость запроса, а роли и обязательность полей определяет модель.
streambooleantrue включает потоковый ответ в формате SSE.
stream_options.include_usagebooleanЗначение true вместе со stream: true добавляет в конец потока фрагмент с usage. Без него шлюз этот фрагмент не передаёт.
max_tokens, max_completion_tokensintegerОграничение длины ответа, целое число от 1 до 16 777 216, иначе ответ 400. Если переданы и max_tokens, и max_completion_tokens, берётся меньшее. Верхняя оценка стоимости, от которой считается резерв до ответа, строится по этому значению, а без него по пределу модели.
modalities, narray, integerТолько для моделей изображений: если в modalities есть image, запрос оценивается по числу изображений n (по умолчанию 1, не больше 128).
остальные полялюбойПередаются модели без изменений.

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

Один и тот же запрос на трёх языках. Адрес API уже подставлен.

cURL

bash
curl https://relay-llm.ru/v1/chat/completions \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "Say hello in one sentence."
      }
    ]
  }'

Python

python
import os
from openai import OpenAI

client = OpenAI(base_url="https://relay-llm.ru/v1", api_key=os.environ["RELAY_API_KEY"])

reply = client.chat.completions.create(
    model="MODEL_ID",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(reply.choices[0].message.content)

JavaScript

ts
const response = await fetch('https://relay-llm.ru/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RELAY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'MODEL_ID',
    messages: [{ role: 'user', content: 'Say hello in one sentence.' }],
  }),
})
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`)
const data = await response.json()
console.log(data.choices[0].message.content)

Вместо MODEL_ID подставьте идентификатор модели из каталога. Примеры читают ключ из переменной окружения RELAY_API_KEY, адрес API уже подставлен.

Ответ

json
{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "model": "MODEL_ID",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 7,
    "total_tokens": 16
  }
}

Текст ответа лежит в choices[0].message.content, расход токенов в usage. Набор остальных полей зависит от модели, а model содержит идентификатор из вашего запроса. Заголовок x-request-id хранит идентификатор запроса: он же указан в строке журнала запросов в кабинете и в теле ошибки.

Потоковый ответ

Как считается резерв и списание

Ошибки

Ошибка приходит с HTTP-кодом и телом в обёртке OpenAI: type, code, message, param и request_id. Значение request_id совпадает с заголовком x-request-id, а к сообщению обычно добавлена ссылка на описание кода.

json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API key See https://relay-llm.ru/docs/errors#invalid_api_key",
    "param": null,
    "request_id": "01990f3c-7a52-7c1e-9b0a-3d5e8f2a4c61"
  }
}

Все коды ошибок

Готовы? Три шага, чтобы начатьВойдите в консоль · пополните баланс · создайте API Key