# Responses

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

```bash tab="cURL"
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": "Привет!"}'
```

```python tab="Python"
response = client.responses.create(
    model="gpt-5-nano",
    instructions="Отвечай коротко.",
    input="Привет!",
    extra_headers={"Idempotency-Key": "order-1842-summary"},
)
print(response.output_text, response.usage)
```

```ts tab="TypeScript"
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` и ошибки работают так же, как у
[чата](https://souz.ai/docs/chat.md). Поля `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": "…"` из [Файлы](https://souz.ai/docs/files.md) |
| файл (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 tab="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` значат то же, что [в чате](https://souz.ai/docs/chat.md#ответ-чата). По `id` ответа
  `GET /v1/jobs/{id}` вернёт статус и списание.

## Поток Responses

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

```python tab="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_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]`. Остальные коды совпадают с [ошибками чата](https://souz.ai/docs/chat.md#ошибки-чата).

**Дальше**

- [Чат](https://souz.ai/docs/chat.md) — тот же вызов по контракту Chat Completions.
- [Повторы](https://souz.ai/docs/idempotency.md) — `Idempotency-Key` для ответа.
- [Модели](https://souz.ai/docs/models.md) — `capabilities` и `params` в карточке.

---

Оглавление документации: https://souz.ai/llms.txt. Всё руководство одним файлом: https://souz.ai/llms-full.txt. Справочник методов: https://souz.ai/docs/api-reference.md.
