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

OpenAI Responses API: запросы и ограничения

Формат запроса и ответа OpenAI Responses для клиентов, которым нужен именно он.

Обзор метода

POST https://relay-llm.ru/v1/responses принимает тело в формате OpenAI Responses. Поддержка зависит от модели и маршрута. Если протокол явно запрещён, шлюз отклоняет запрос; иначе запрос передаётся модели, которая может вернуть 502 upstream_error вместо быстрого отказа. Для не-OpenAI моделей используйте Chat Completions, пока поддержка Responses не подтверждена.

Шлюз читает поля model, stream и max_output_tokens. Остальное уходит модели без изменений, поэтому поддержка конкретного параметра зависит от модели.

Формат Chat Completions

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

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

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

ПолеТипНазначение
modelstring, обязательноИдентификатор модели из каталога или заведённый для неё алиас. Неизвестная модель даёт ответ 404 с кодом model_not_found.
streambooleantrue включает потоковый ответ в формате SSE.
max_output_tokensintegerОграничение длины ответа, целое число от 1 до 16 777 216, иначе ответ 400. Верхняя оценка стоимости, от которой считается резерв до ответа, строится по этому значению и пределам модели.
previous_response_idstringНе поддерживается: значение, которое начинается с resp_, даёт ответ 400. Передавайте историю диалога в поле input.
backgroundbooleanНе поддерживается: true даёт ответ 400.
остальные полялюбойПередаются модели без изменений.

Клиент без хранения состояния на сервере присылает элементы type: "reasoning" во входе заново после вызова инструмента. Если маршрут модели отвечает на такие элементы ошибкой 400, шлюз убирает их перед отправкой, и рассуждение прошлого хода к модели не попадает. Остальное тело не меняется.

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

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

cURL

bash
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

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

ts
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 уже подставлен.

Ответ

json
{
  "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.

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