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": "Привет!"}'response = client.responses.create(
model="gpt-5-nano",
instructions="Отвечай коротко.",
input="Привет!",
extra_headers={"Idempotency-Key": "order-1842-summary"},
)
print(response.output_text, response.usage)const response = await client.responses.create(
{ model: "gpt-5-nano", instructions: "Отвечай коротко.", input: "Привет!" },
{ headers: { "Idempotency-Key": "order-1842-summary" } },
);
console.log(response.output_text, response.usage);Модели, каналы, Авто-роутинг, списание, Idempotency-Key и ошибки работают так же, как у
чата. Поля routing, routing_options и max_price_multiplier передайте в теле.
Поля Responses
| Поле | Тип | По умолчанию | Что делает |
|---|---|---|---|
model | string | обязательно | Модель с modality: chat |
input | string, array | обязательно | Текст или элементы переписки |
instructions | string | нет | Системная инструкция перед input |
max_output_tokens | integer | предел модели | Граница ответа |
temperature, top_p | number | у модели | Как в чате |
reasoning.effort | string | у модели | Глубина рассуждения, ступени те же, что у reasoning_effort чата |
tools, tool_choice | array, string | нет | Вызов функций с type: "function" |
parallel_tool_calls | boolean | true | Несколько вызовов функций за ответ |
text.format | object | текст | json_object или json_schema |
text.verbosity | string | у модели | Подробность ответа: уходит к умеющим каналам, без них игнорируется |
store | boolean | false | Только false; с false тексты не попадают в историю |
stream | boolean | false | Ответ потоком событий |
Поля 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 принимается и модели не передаётся.
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
{
"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 по порядку с нуля.
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:
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_request | file_id картинки чужой, истёк или не картинка (unknown_file, file_expired, unsupported_format) | Загрузите файл заново |
400 capability_mismatch | Встроенный поиск в tools или возможность, которой нет ни у одного канала | Уберите инструмент или выберите модель по capabilities |
Пути в detail[].path указывают на поля запроса Responses: max_output_tokens, input[2].content,
tools[0]. Остальные коды совпадают с ошибками чата.
Дальше