Responses

POST /v1/responses отвечает по контракту OpenAI Responses поверх того же чата. Используйте его, если клиент умеет только Responses API, например Codex CLI или client.responses.create. Ответы не хранятся: каждый запрос несёт всю переписку в input.

curl https://api.souz.ai/v1/responses \
  -H "Authorization: Bearer $SOUZ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1842-summary" \
  -d '{"model": "gpt-5-nano", "instructions": "Отвечай коротко.", "input": "Привет!"}'

Модели, каналы, Авто-роутинг, списание, Idempotency-Key и ошибки работают так же, как у чата. Поля routing, routing_options и max_price_multiplier передайте в теле.

Поля Responses

ПолеТипПо умолчаниюЧто делает
modelstringобязательноМодель с modality: chat
inputstring, arrayобязательноТекст или элементы переписки
instructionsstringнетСистемная инструкция перед input
max_output_tokensintegerпредел моделиГраница ответа
temperature, top_pnumberу моделиКак в чате
reasoning.effortstringу моделиГлубина рассуждения, ступени те же, что у reasoning_effort чата
tools, tool_choicearray, stringнетВызов функций с type: "function"
parallel_tool_callsbooleantrueНесколько вызовов функций за ответ
text.formatobjectтекстjson_object или json_schema
text.verbositystringу моделиПодробность ответа: уходит к умеющим каналам, без них игнорируется
storebooleanfalseТолько false; с false тексты не попадают в историю
streambooleanfalseОтвет потоком событий

Поля metadata, service_tier, reasoning.summary и include: ["reasoning.encrypted_content"] принимаются и не влияют. Поля user, safety_identifier и prompt_cache_key уходят модели, как в чате.

Переписка в input

Элемент input бывает сообщением, вызовом функции или её результатом.

ЭлементФорма
сообщение{"role": "user", "content": "…"}, роли user, assistant, system, developer
текст{"type": "input_text", "text": "…"}, у ответа модели output_text
картинка{"type": "input_image", "image_url": "https://…"} или "file_id": "…" из Файлы
файл (PDF){"type": "input_file", "filename": "doc.pdf", "file_data": "data:application/pdf;base64,…"}
вызов функции{"type": "function_call", "call_id": "call_1", "name": "…", "arguments": "{…}"}
результат функции{"type": "function_call_output", "call_id": "call_1", "output": "…"}

Элементы output прошлого ответа можно вернуть в input как есть, id и status не обязательны. Элемент reasoning принимается и модели не передаётся.

Python
history = [{"role": "user", "content": "Какая погода в Казани?"}]
tools = [{"type": "function", "name": "get_weather",
          "parameters": {"type": "object", "properties": {"city": {"type": "string"}}}}]
first = client.responses.create(model="gpt-5-nano", input=history, tools=tools)
call = next(item for item in first.output if item.type == "function_call")
history += [call, {"type": "function_call_output", "call_id": call.call_id, "output": "+5"}]
second = client.responses.create(model="gpt-5-nano", input=history, tools=tools)
print(second.output_text)

Ответ Responses

JSON
{
  "id": "resp_1a2b3c4d5e6f",
  "object": "response",
  "created_at": 1758801600,
  "status": "completed",
  "model": "gpt-5-nano",
  "channel": "blue",
  "output": [
    {"id": "msg_1a2b3c4d5e6f_0", "type": "message", "role": "assistant", "status": "completed",
     "content": [{"type": "output_text", "text": "Привет! Чем помочь?", "annotations": []}]}
  ],
  "usage": {"input_tokens": 10, "output_tokens": 24, "total_tokens": 34, "cost": 3000, "currency": "RUB"},
  …
}
  • output содержит reasoning с кратким рассуждением, message с текстом и function_call на каждый вызов функции, если их вернула модель.
  • status: "incomplete" означает, что ответ упёрся в предел длины или фильтр содержания. Причину называет incomplete_details.reason: max_output_tokens или content_filter.
  • usage.cost и channel значат то же, что в чате. По id ответа GET /v1/jobs/{id} вернёт статус и списание.

Поток Responses

С "stream": true приходит text/event-stream с событиями response.* по контракту OpenAI. У каждого события есть sequence_number по порядку с нуля.

Python
stream = client.responses.create(model="gpt-5-nano", input="Привет!", stream=True)
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="")
    elif event.type == "response.completed":
        print(event.response.usage)
  • Поток начинается с response.created и response.in_progress, текст идёт событиями response.output_text.delta, аргументы функций идут response.function_call_arguments.delta.
  • Последним приходит response.completed или response.incomplete с объектом ответа и usage. Отдельного [DONE] нет.
  • Ошибка до первого события приходит обычным JSON. Отказ после : ping приходит событием error, а обрыв после начала ответа приходит событием response.failed.
  • Поток, оборвавшийся до итога, не списывается.

Codex CLI

Codex CLI работает через Responses API. Добавьте Souz API в ~/.codex/config.toml и положите ключ в переменную SOUZ_API_KEY:

toml
model = "gpt-5-nano"
model_provider = "souz"
web_search = "disabled"

[model_providers.souz]
name = "Souz API"
base_url = "https://api.souz.ai/v1"
env_key = "SOUZ_API_KEY"
wire_api = "responses"

web_search = "disabled" нужен потому, что встроенный поиск Codex API отклоняет. Выберите модель с capabilities.tools, иначе Codex не сможет вызывать свои инструменты.

Чего нет в Responses

Ответы не хранятся, поэтому эти поля API отклоняет с 400 invalid_request и путём в detail[].path: store: true, previous_response_id, conversation, background: true, prompt, элемент item_reference и truncation, кроме "disabled". Методов GET /v1/responses/{id} и DELETE /v1/responses/{id} нет.

Из встроенных инструментов поиск (web_search и его версии) получает 400 capability_mismatch, как web_search_options в чате. Остальные встроенные инструменты и include, кроме reasoning.encrypted_content, получают 400 invalid_request.

Ошибки Responses

КодКогдаЧто делать
400 invalid_requestПоле из раздела выше или неверная форма элемента inputИсправьте поле из detail[].path
400 invalid_requestfile_id картинки чужой, истёк или не картинка (unknown_file, file_expired, unsupported_format)Загрузите файл заново
400 capability_mismatchВстроенный поиск в tools или возможность, которой нет ни у одного каналаУберите инструмент или выберите модель по capabilities

Пути в detail[].path указывают на поля запроса Responses: max_output_tokens, input[2].content, tools[0]. Остальные коды совпадают с ошибками чата.

Дальше

  • Чат — тот же вызов по контракту Chat Completions.
  • Повторы — Idempotency-Key для ответа.
  • Модели — capabilities и params в карточке.