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

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

## Тело запроса (`application/json`)

Схема `ResponseRequest`.

| Поле | Обязательно | Тип | Описание |
|---|---|---|---|
| `include` | нет | `array | null` | Принимается только `reasoning.encrypted_content`, он на ответ не влияет. |
| `input` | да |  | Текст запроса или вся переписка элементами. |
| `instructions` | нет | `string | null` | Системное сообщение перед `input`. |
| `max_output_tokens` | нет | `integer | null` | Граница длины ответа, включая рассуждение. Без поля действует предел модели. |
| `max_price_multiplier` | нет |  |  |
| `metadata` | нет | `object | null` | Принимается и не хранится. |
| `model` | да | `string` |  |
| `parallel_tool_calls` | нет | `boolean | null` |  |
| `previous_response_id` | нет | `string | null` | Не поддерживается, передайте переписку в `input`. |
| `prompt_cache_key` | нет | `string` |  |
| `reasoning` | нет | `object | null` |  |
| `routing` | нет | схема `Routing` |  |
| `routing_options` | нет |  |  |
| `safety_identifier` | нет | `string` |  |
| `store` | нет | `boolean | null` | Ответы не хранятся для продолжения: `true` получает `400 invalid_request`. `false` выключает и хранение текстов в истории запросов, как у чата. |
| `stream` | нет | `boolean`; по умолчанию `false` |  |
| `temperature` | нет | `number | null, double` |  |
| `text` | нет | `object | null` |  |
| `tool_choice` | нет |  | `auto`, `none`, `required` или `{"type": "function", "name": "…"}`. |
| `tools` | нет | `array` | Инструменты-функции. Для модели без `capabilities.tools` API отвечает `400 capability_mismatch`. |
| `top_p` | нет | `number | null, double` |  |
| `truncation` | нет | `string | null` | Только `disabled`. |
| `user` | нет | `string` |  |

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

```bash
curl -X POST 'https://api.souz.ai/v1/responses' \
  -H "Authorization: Bearer $SOUZ_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "input": "Привет!",
  "model": "gpt-5-nano"
}'
```

```python
import os
import requests

response = requests.post(
    "https://api.souz.ai/v1/responses",
    headers={"Authorization": f"Bearer {os.environ['SOUZ_API_KEY']}"},
    json={
        "input": "Привет!",
        "model": "gpt-5-nano",
    },
)
print(response.json())
```

```ts
const response = await fetch("https://api.souz.ai/v1/responses", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SOUZ_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "input": "Привет!",
    "model": "gpt-5-nano"
  }),
});
console.log(await response.json());
```

## Ответы

### 200

Ответ модели целиком или потоком событий.

- `application/json`, схема `ResponseObject`

```json
{
  "channel": "blue",
  "created_at": 1758801600,
  "error": null,
  "id": "resp_1a2b3c4d5e6f",
  "incomplete_details": null,
  "model": "gpt-5-nano",
  "object": "response",
  "output": [
    {
      "content": [
        {
          "annotations": [],
          "text": "Привет! Чем помочь?",
          "type": "output_text"
        }
      ],
      "id": "msg_1a2b3c4d5e6f_0",
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "parallel_tool_calls": true,
  "status": "completed",
  "tool_choice": "auto",
  "tools": [],
  "usage": {
    "cost": 3000,
    "currency": "RUB",
    "input_tokens": 10,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 24,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 34
  }
}
```
- `text/event-stream`, схема `ResponseStreamEvent`

### 400

Запрос отклонён; `error.detail[]` называет поля и допустимые значения.

- `application/json`, схема `Error`

```json
{
  "error": {
    "code": "capability_mismatch",
    "detail": [
      {
        "allowed": [
          "1:1",
          "16:9",
          "9:16"
        ],
        "path": "aspect_ratio",
        "reason": "unsupported_value"
      }
    ],
    "message": "the model does not support this value",
    "type": "invalid_request_error"
  }
}
```

### 401

Нет ключа или ключ недействителен.

- `application/json`, схема `Error`

### 402

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

- `application/json`, схема `Error`

```json
{
  "error": {
    "code": "insufficient_balance",
    "message": "insufficient balance",
    "type": "billing_error"
  }
}
```

### 403

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

- `application/json`, схема `Error`

```json
{
  "error": {
    "code": "forbidden",
    "detail": [
      {
        "reason": "requires_api_key"
      }
    ],
    "message": "this endpoint takes an API key; a management key manages the account only",
    "type": "permission_error"
  }
}
```

### 404

Нет такого объекта у этого аккаунта.

- `application/json`, схема `Error`

### 409

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

- `application/json`, схема `Error`

### 413

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

- `application/json`, схема `Error`

### 415

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

- `application/json`, схема `Error`

### 429

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

- `application/json`, схема `Error`

### 502

Модель не справилась или исход вызова неизвестен; ничего не списано.

- `application/json`, схема `Error`

### 503

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

- `application/json`, схема `Error`

### 504

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

- `application/json`, схема `Error`

---

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