# OpenAI Responses

Отличия HTTP и WebSocket вызовов /openai/api/v1/responses через хаб.

`POST /openai/api/v1/responses` создает ответ генеративной модели в формате OpenAI Responses, в том числе через конвертацию. Поля описаны в [документации OpenAI Create a model response](https://developers.openai.com/api/reference/resources/responses/methods/create), модели — в [каталоге](https://coreinfra.ru/docs/catalog.md).

```bash
curl https://hub.coreinfra.ai/openai/api/v1/responses \
  -H "Authorization: Bearer $COREINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"gpt-6-luna","input":"2 + 2"}'
```

Ожидаемый текст — `4`. Фрагмент ответа:

```json
{"output":[{"type":"message","role":"assistant","content":[{"type":"output_text","text":"4"}]}]}
```

## Отличия от API OpenAI

Поле `inference_geo` игнорируется для всех моделей. Остальные игнорируемые клиентские поля и настройки при вызове без конвертации зависят от провайдера модели:

| Провайдер модели | Особенности обработки полей                                                                                                                                                                                                                            |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| OpenAI           | Отключено сохранение (`store: false`), игнорируется `safety_identifier`. Из `service_tier` поддерживаются `auto`, `default`, `priority`, `fast` и `ultrafast` (`fast` тарифицируется как приоритетный режим); `flex` и остальные значения игнорируются |
| DeepSeek         | Игнорируются `user`, `safety_identifier` и `service_tier`                                                                                                                                                                                              |
| Moonshot AI      | Игнорируются `user`, `safety_identifier`, `service_tier` и `prompt_cache_options`                                                                                                                                                                      |
| xAI              | Отключено сохранение (`store: false`), игнорируются `user`, `safety_identifier` и `service_tier`                                                                                                                                                       |

Если у выбранной модели нет тарифа для переданного режима `service_tier`, возвращается ошибка со статус-кодом `400`.

### Неподдерживаемые возможности

Со статус-кодом `400` отклоняются `background: true`, заданные значения `prompt` и `conversation`, отличные от `null`, а также MCP-инструмент с заданным `tunnel_id`. Для MCP используйте `server_url` или `connector_id`.

Запрещены инструменты `code_interpreter`, `file_search`, `image_generation`, `x_search`, `code_execution`, `collections_search` и `attachment_search`. Инструмент `shell` запрещен с окружением `container_auto` или `container_reference`. Проверка распространяется на вложенные пространства имен и инструменты, переданные в истории через `additional_tools` или `tool_search_output`.

Изображения в `input` и результатах инструментов принимаются только в кодировке base64 (`data:image/...;base64,...`); непустые `file_id` запрещены. Для `input_file` запрещены непустые `file_url` и `file_id`: передавайте файл в `file_data` (нарушение отклоняется со статус-кодом `400`). Действуют [общие ограничения размера](https://coreinfra.ru/docs/reference.md#limits).

### При конвертации

Когда выбранная модель не поддерживает Responses напрямую, хаб конвертирует запрос и возвращает ответ в формате Responses:

* Значения `previous_response_id` и `conversation`, отличные от `null`, и элементы `item_reference` отклоняются со статус-кодом `400`: передайте историю непосредственно в `input`.
* Не конвертируются `max_tool_calls`, `top_logprobs`, `truncation`, `stream_options`, `background`, `prompt`, `prompt_cache_retention`, `prompt_cache_options`, `image`, `moderation`, `client_metadata`, `text.verbosity`, `reasoning.context`, `reasoning.mode` и `reasoning.generate_summary`. Из `include` сохраняется только `reasoning.encrypted_content`.
* Инструменты `function` конвертируются без `output_schema`; пространства имен разворачиваются в плоские имена и восстанавливаются в ответе. Инструменты `custom` преобразуются в функцию с текстовым вводом. Другие типы инструментов пропускаются.
* При конвертации в Anthropic Messages без явного лимита выхода используется `max_tokens: 16000` (при `stream: true` — `64000`), и не конвертируются `metadata`, `frequency_penalty`, `presence_penalty`, `store`, `prompt_cache_key`, `detail` у изображений и сводка рассуждений. У JSON Schema сохраняется `schema` (без `name`, `description` и `strict`).
* При конвертации в Chat Completions `max_output_tokens` переносится в `max_completion_tokens`, `text.format` — в `response_format`, и не конвертируется `reasoning.summary`.
* При конвертации в Google Interactions не конвертируются `parallel_tool_calls`, `metadata`, `frequency_penalty`, `presence_penalty` и `prompt_cache_key`; уровень рассуждений `none` сопоставляется с `minimal`, а `xhigh` и `max` — с `high`.
* Настройка рассуждений игнорируется, если модель не поддерживает рассуждения.

### WebSocket

[Документация соединения OpenAI Responses](https://developers.openai.com/api/reference/resources/responses/methods/connect) задает формат WebSocket-событий. Тот же путь обслуживает `GET` с WebSocket Upgrade: `wss://hub.coreinfra.ai/openai/api/v1/responses`. Ключ передается в `Authorization: Bearer …`. Здесь доступны модели с нативной поддержкой OpenAI Responses; конвертация для моделей других протоколов по WebSocket не выполняется.

Клиент передает JSON-события `response.create` и `response.interrupt`. В `response.create` допустимо только `stream: true` (если поле присутствует); любое присутствие `background` отклоняется. `generate` принимает boolean или `null`. Бинарные сообщения не принимаются. Если передан `stream_id`, это непустая строка длиной до 256 символов из латинских букв, цифр, `_`, `-` и `.`; нарушение возвращает событие `error` с кодом `invalid_stream_id`. Размер сообщения ограничен 100 МиБ, длительность соединения — одним часом.

### Резерв и списание

До отправки резервируется сумма по оценке входа и выхода, а итоговое списание определяется `usage`; вызовы веб-поиска и чтения страниц учитываются отдельно от токенов (см. [«Стоимость генеративных моделей»](https://coreinfra.ru/docs/billing/text.md) и [«Тарифы»](https://hub.coreinfra.ai/pricing)).

Когда в ответе модели (например, у моделей Grok без конвертации) присутствуют данные о стоимости и сумма списания рассчитана, хаб возвращает стоимость запроса в рублях в поле `usage.cost_rub`.

## Ошибки

* `400` — запрещенное поле, инструмент, вложение, недоступный уровень обслуживания или невозможная конвертация.
* `502` — ошибка на стороне провайдера модели при выполнении запроса. Ошибка внутри SSE передается событием потока. Для WebSocket неверный Upgrade возвращает статус-код `426`, ограничения полей после соединения — событие `error`.

Формат ошибок приведен в [разделе OpenAI API](https://coreinfra.ru/docs/reference/openai.md#errors); общие ошибки авторизации, баланса и лимитов расходов описаны в [общем справочнике](https://coreinfra.ru/docs/reference.md#errors).
