OpenAI Responses API: запросы и ограничения
Формат запроса и ответа OpenAI Responses для клиентов, которым нужен именно он.
Обзор метода
POST https:// принимает тело в формате OpenAI Responses. Поддержка зависит от модели и маршрута. Если протокол явно запрещён, шлюз отклоняет запрос; иначе запрос передаётся модели, которая может вернуть 502 upstream_error вместо быстрого отказа. Для не-OpenAI моделей используйте Chat Completions, пока поддержка Responses не подтверждена.
Шлюз читает поля model, stream и max_output_tokens. Остальное уходит модели без изменений, поэтому поддержка конкретного параметра зависит от модели.
Аутентификация
Передайте ключ в заголовке Authorization: Bearer RELAY_API_KEY или x-api-key: RELAY_API_KEY. Без ключа, а также с неверным, просроченным или отозванным ключом приходит ответ 401 с кодом invalid_api_key. Если заголовков два, шлюз читает только Authorization.
Параметры тела
| Поле | Тип | Назначение |
|---|---|---|
model | string, обязательно | Идентификатор модели из каталога или заведённый для неё алиас. Неизвестная модель даёт ответ 404 с кодом model_not_found. |
stream | boolean | true включает потоковый ответ в формате SSE. |
max_output_tokens | integer | Ограничение длины ответа, целое число от 1 до 16 777 216, иначе ответ 400. Верхняя оценка стоимости, от которой считается резерв до ответа, строится по этому значению и пределам модели. |
previous_response_id | string | Не поддерживается: значение, которое начинается с resp_, даёт ответ 400. Передавайте историю диалога в поле input. |
background | boolean | Не поддерживается: true даёт ответ 400. |
| остальные поля | любой | Передаются модели без изменений. |
Клиент без хранения состояния на сервере присылает элементы type: "reasoning" во входе заново после вызова инструмента. Если маршрут модели отвечает на такие элементы ошибкой 400, шлюз убирает их перед отправкой, и рассуждение прошлого хода к модели не попадает. Остальное тело не меняется.
Пример запроса
Один и тот же запрос на трёх языках. Адрес API уже подставлен.
cURL
curl https://relay-llm.ru/v1/responses \
-H "Authorization: Bearer $RELAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MODEL_ID",
"input": "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.responses.create(
model="MODEL_ID",
input="Say hello in one sentence.",
)
print(reply.output_text)JavaScript
const response = await fetch('https://relay-llm.ru/v1/responses', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.RELAY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'MODEL_ID',
input: 'Say hello in one sentence.',
}),
})
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`)
const data = await response.json()
const message = data.output.find((item) => item.type === 'message')
console.log(message.content.find((part) => part.type === 'output_text').text)Вместо MODEL_ID подставьте идентификатор модели из каталога. Примеры читают ключ из переменной окружения RELAY_API_KEY, адрес API уже подставлен.
Ответ
{
"id": "resp_01Ab3cD",
"object": "response",
"model": "MODEL_ID",
"status": "completed",
"output": [
{
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "Hello! How can I help you today?"
}
]
}
],
"usage": {
"input_tokens": 9,
"output_tokens": 7,
"total_tokens": 16
}
}Текст ответа лежит в output, расход токенов в usage. Поле model содержит идентификатор из вашего запроса. Заголовок x-request-id хранит идентификатор запроса. Первым элементом output у моделей с рассуждением бывает type: "reasoning" без поля content, поэтому ищите текст в элементе type: "message" или читайте output_text в SDK. В usage.input_tokens входят кэшированные токены: прочитанные и записанные лежат в input_tokens_details. Токены рассуждений входят в output_tokens.
С stream: true ответ приходит событиями SSE в формате Responses. Шлюз передаёт их без пересборки и подменяет только model и идентификаторы.
Как считается резерв и списание
Ошибки
Ошибка приходит с HTTP-кодом и телом в обёртке OpenAI: type, code, message, param и 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"
}
}