Создать ответ Responses

POSThttps://api.souz.ai/v1/responses

Создаёт ответ чат-модели по контракту OpenAI Responses без хранения: каждый запрос несёт всю переписку в input. store: true, previous_response_id, conversation, background: true, prompt и item_reference получают 400 invalid_request. Деньги, каналы, ошибки и Idempotency-Key работают так же, как у POST /v1/chat/completions. С "stream": true ответ приходит как text/event-stream: события response.* с sequence_number, последним идёт response.completed, response.incomplete или response.failed. Подробнее: https://souz.ai/docs/responses.

Авторизация

BearerAuth

API-ключ из кабинета souz.ai, запускает модели. Ключ управления здесь не подходит: API отвечает 403 forbidden с detail[].reason: requires_api_key.

Заголовки

Idempotency-Keystring

Строка до 255 символов, уникальная в пределах аккаунта. Повтор с тем же ключом и параметрами возвращает ту же задачу с текущим статусом, без новой задачи и второго списания. Это работает и при одновременных запросах, и после смены настроек аккаунта: сравниваются только поля запроса. Тот же ключ с другими параметрами получает 409 idempotency_key_conflict. В сравнение не входят store и callback_url, у картинок, видео и музыки ещё и response_format; у синтеза речи формат звука сравнивается. Ключ хранится вместе с задачей без ограничения срока. Повтор проваленной задачи не запускает её заново: для новой попытки нужен новый ключ. Повтор не продлевает срок файлов результата (retention.files_days из GET /v1/key). Ключ работает для картинок, видео, музыки, транскрибации, синтеза речи и чата. У чата и POST /v1/responses сравнивается тело запроса целиком; повтор дожидается идущего вызова и получает тот же ответ (и поток), что первый. Ответ чата хранится сутки. Подробнее: https://souz.ai/docs/idempotency.

Максимальная длина: 255

Тело запроса обязательно

application/json
Схема ResponseRequest
includearray | null

Принимается только reasoning.encrypted_content, он на ответ не влияет.

inputодно изобязательно

Текст запроса или вся переписка элементами.

Вариант 1string
Вариант 2array[ResponseInputItem]
Минимум элементов: 1
instructionsstring | null

Системное сообщение перед input.

max_output_tokensinteger | null

Граница длины ответа, включая рассуждение. Без поля действует предел модели.

Минимум: 1
max_price_multiplierMaxPriceMultiplier | null
metadataobject | null

Принимается и не хранится.

modelstringобязательно
Пример: "gpt-5-nano"
parallel_tool_callsboolean | null
previous_response_idstring | null

Не поддерживается, передайте переписку в input.

prompt_cache_keystring
reasoningobject | null
effortstring | null

Глубина рассуждения, как reasoning_effort чата.

Пример: "medium"
summarystring | null

Принимается и не влияет на ответ.

routingRouting
routing_optionsRoutingOptions | null
safety_identifierstring
storeboolean | null

Ответы не хранятся для продолжения: true получает 400 invalid_request. false выключает и хранение текстов в истории запросов, как у чата.

streamboolean
По умолчанию: false
temperaturenumber | null · double
textobject | null
formatobject

text, json_object или json_schema с name, schema и strict.

typestringобязательно
Значения: text, json_object, json_schema
verbositystring | null
Пример: "medium"
tool_choiceодно из

auto, none, required или {"type": "function", "name": "…"}.

Вариант 1string
Значения: auto, none, required
Вариант 2object
namestring
typestringобязательно
toolsarray[ResponseTool]

Инструменты-функции. Для модели без capabilities.tools API отвечает 400 capability_mismatch.

top_pnumber | null · double
truncationstring | null

Только disabled.

userstring

Ответы

200Ответ модели целиком или потоком событий.
application/json
Схема ResponseObject
channelвсе варианты

Фактический цвет канала, который дал этот ответ. Название и HEX отдаёт GET /v1/channels.

Вариант 1ChannelId
created_atinteger · int64обязательно
errorResponseError | null
idstringобязательно

resp_…; тот же id открывает GET /v1/jobs/{id}.

incomplete_detailsobject | null
reasonstring
Значения: max_output_tokens, content_filter
modelstringобязательно
objectstringобязательно
Значение: "response"
outputarray[ResponseOutputItem]обязательно
parallel_tool_callsbooleanобязательно
statusstringобязательно
Значения: in_progress, completed, incomplete, failed
tool_choiceодно изобязательно
Вариант 1string
Вариант 2object
toolsarray[object]обязательно
usageResponseUsage | null
text/event-stream
Схема ResponseStreamEvent
argumentsstring
codestring | null
content_indexinteger
deltastring
item_idstring
logprobsarray[object]
messagestring
namestring
output_indexinteger
paramstring | null
partobject
refusalstring
sequence_numberintegerобязательно
summary_indexinteger
textstring
typestringобязательно
Пример: "response.output_text.delta"
400Запрос отклонён; `error.detail[]` называет поля и допустимые значения.
application/json
401Нет ключа или ключ недействителен.
application/json
402Запрос не принят из-за денег. `insufficient_balance` значит, что баланса не хватает на

Запрос не принят из-за денег. insufficient_balance значит, что баланса не хватает на самый дешёвый канал с учётом запросов, которые ещё выполняются. key_spend_limit_exceeded значит, что исчерпан потолок трат ключа, member_spend_limit_exceeded — лимит участника, которому выдан ключ. Повтор не поможет, пока баланс не пополнят, лимит не начнётся заново или его не поднимут. Потолок ключа со spend_limit_reset: none действует на всё время ключа. Подробнее: https://souz.ai/docs/balance.

application/json
403Действие запрещено: у ключа не тот вид (модели запускает API-ключ, аккаунтом управляет

Действие запрещено: у ключа не тот вид (модели запускает API-ключ, аккаунтом управляет ключ управления), у роли участника нет права или подпись ссылки на файл не сходится. Причину называет detail[].reason: requires_api_key, requires_management_key, cabinet_only (только в кабинете), insufficient_role (в allowed перечислены роли с правом), not_key_author (секрет ключа открывает только его автор).

application/json
404Нет такого объекта у этого аккаунта.
application/json
409Конфликт с состоянием: тот же `Idempotency-Key` пришёл с другим телом

Конфликт с состоянием: тот же Idempotency-Key пришёл с другим телом (idempotency_key_conflict) или секрет ключа нельзя показать (secret_unavailable).

application/json
413Тело или файл больше предела (`invalid_input`, `detail[].reason: too_large`). У

Тело или файл больше предела (invalid_input, detail[].reason: too_large). У POST /v1/files так же отвечает переполненная квота загрузок аккаунта (storage_limit_exceeded).

application/json
415Тип тела не подходит методу. Методы принимают `Content-Type: application/json`, загрузка

Тип тела не подходит методу. Методы принимают Content-Type: application/json, загрузка файла и транскрибация — multipart/form-data, создание видео — оба типа. В detail[] приходит {"path": "body", "reason": "unsupported_format"} с принимаемыми типами.

application/json
429Слишком частые запросы: повторите через `Retry-After` секунд. Запуск моделей, задачи и

Слишком частые запросы: повторите через Retry-After секунд. Запуск моделей, задачи и файлы результатов частотой не ограничены, их ограничивают баланс и лимиты трат. 429 получает поток запросов с одного адреса с ключом, который сервер не знает, и потоки сверх 1000 одновременных на аккаунт (события задачи, чат с stream: true). Пределы: https://souz.ai/docs/limits.

application/json
502Модель не справилась или исход вызова неизвестен; ничего не списано.
application/json
503Модель сейчас некому исполнить: повторите через `Retry-After`. На плановых работах

Модель сейчас некому исполнить: повторите через Retry-After. На плановых работах приходит maintenance (ответ Maintenance).

application/json
504Модель не ответила за срок запроса (14 минут), `generation_failed` с причиной «не ответила

Модель не ответила за срок запроса (14 минут), generation_failed с причиной «не ответила вовремя»; ничего не списано. В потоке — событие data: {"error": …} без [DONE].

application/json