OpenAI Chat Completions API: запросы и ответы
Формат запроса и ответа OpenAI Chat Completions: адрес, заголовки, поля тела, ответ и ошибки.
Обзор метода
POST https:// принимает тело в формате 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).
| Поле | Тип | Назначение |
|---|---|---|
model | string, обязательно | Идентификатор модели из каталога или заведённый для неё алиас. Неизвестная модель даёт ответ 404 с кодом model_not_found. |
messages | array | Сообщения диалога в формате OpenAI. Структуру шлюз не проверяет: по размеру текста и числу картинок он оценивает стоимость запроса, а роли и обязательность полей определяет модель. |
stream | boolean | true включает потоковый ответ в формате SSE. |
stream_options.include_usage | boolean | Значение true вместе со stream: true добавляет в конец потока фрагмент с usage. Без него шлюз этот фрагмент не передаёт. |
max_tokens, max_completion_tokens | integer | Ограничение длины ответа, целое число от 1 до 16 777 216, иначе ответ 400. Если переданы и max_tokens, и max_completion_tokens, берётся меньшее. Верхняя оценка стоимости, от которой считается резерв до ответа, строится по этому значению, а без него по пределу модели. |
modalities, n | array, integer | Только для моделей изображений: если в modalities есть image, запрос оценивается по числу изображений n (по умолчанию 1, не больше 128). |
| остальные поля | любой | Передаются модели без изменений. |
Пример запроса
Один и тот же запрос на трёх языках. Адрес API уже подставлен.
cURL
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
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
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 уже подставлен.
Ответ
{
"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, а к сообщению обычно добавлена ссылка на описание кода.
{
"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"
}
}