# OpenAI API

API методы и общие форматы ответов и ошибок OpenAI-совместимого API хаба.

Базовый адрес OpenAI API — `https://hub.coreinfra.ai/openai/api/v1`. Ниже перечислены HTTP-методы и WebSocket-соединения этого API; поля запросов описаны в [документации OpenAI](https://developers.openai.com/api/reference/overview).

## API методы

Пути в таблице указаны относительно базового адреса.

| Метод                    | Путь                      | Назначение                                                                                      |
| ------------------------ | ------------------------- | ----------------------------------------------------------------------------------------------- |
| `GET`, `OPTIONS`         | `/models`                 | [Каталог моделей](https://coreinfra.ru/docs/reference/openai/models.md)                         |
| `POST`, `OPTIONS`        | `/chat/completions`       | [OpenAI Chat Completions](https://coreinfra.ru/docs/reference/openai/chat-completions.md)       |
| `POST`, `OPTIONS`        | `/responses`              | [OpenAI Responses](https://coreinfra.ru/docs/reference/openai/responses.md)                     |
| `GET`, WebSocket Upgrade | `/responses`              | [Responses по WebSocket](https://coreinfra.ru/docs/reference/openai/responses.md#differences)   |
| `POST`, `OPTIONS`        | `/responses/input_tokens` | [Подсчет входных токенов](https://coreinfra.ru/docs/reference/openai/responses-input_tokens.md) |
| `POST`, `OPTIONS`        | `/decisions`              | [OpenAI Decisions](https://coreinfra.ru/docs/reference/openai/decisions.md)                     |
| `POST`, `OPTIONS`        | `/images/generations`     | [Генерация изображений](https://coreinfra.ru/docs/reference/openai/images-generations.md)       |
| `POST`, `OPTIONS`        | `/images/edits`           | [Редактирование изображений](https://coreinfra.ru/docs/reference/openai/images-edits.md)        |
| `POST`, `OPTIONS`        | `/embeddings`             | [Векторы](https://coreinfra.ru/docs/reference/openai/embeddings.md)                             |
| `POST`, `OPTIONS`        | `/audio/speech`           | [Синтез речи](https://coreinfra.ru/docs/reference/openai/audio-speech.md)                       |
| `GET`, WebSocket Upgrade | `/realtime`               | [Realtime](https://coreinfra.ru/docs/reference/openai/realtime.md)                              |

CORS `OPTIONS` поддерживается для путей, отмеченных в таблицах.

Для [подписки ChatGPT](https://coreinfra.ru/docs/chatgpt-subscription.md) базовый адрес — `https://hub.coreinfra.ai/openai/subscription/api/v1`. Пути ниже указаны относительно него.

| Метод                    | Путь                  | Назначение                                                                                               |
| ------------------------ | --------------------- | -------------------------------------------------------------------------------------------------------- |
| `GET`, `OPTIONS`         | `/models`             | [Каталог моделей подписки](https://coreinfra.ru/docs/reference/openai/subscription-models.md)            |
| `POST`, `OPTIONS`        | `/responses`          | [Ответ модели](https://coreinfra.ru/docs/reference/openai/subscription-responses.md)                     |
| `GET`, WebSocket Upgrade | `/responses`          | [Responses по WebSocket](https://coreinfra.ru/docs/reference/openai/subscription-responses.md#websocket) |
| `POST`, `OPTIONS`        | `/responses/compact`  | [Сжатие контекста](https://coreinfra.ru/docs/reference/openai/subscription-responses-compact.md)         |
| `POST`, `OPTIONS`        | `/alpha/search`       | [Поиск](https://coreinfra.ru/docs/reference/openai/subscription-alpha-search.md)                         |
| `POST`, `OPTIONS`        | `/images/generations` | [Генерация изображений](https://coreinfra.ru/docs/reference/openai/subscription-images-generations.md)   |
| `POST`, `OPTIONS`        | `/images/edits`       | [Редактирование изображений](https://coreinfra.ru/docs/reference/openai/subscription-images-edits.md)    |

## Доступ и модели

Запросы к моделям по основному базовому адресу принимают `Authorization: Bearer sk-ci2-...`. Заголовки `OpenAI-Organization` и `OpenAI-Project` игнорируются. [Каталог моделей](https://coreinfra.ru/docs/reference/openai/models.md) доступен без ключа и включает несколько видов моделей: наличие идентификатора в каталоге само по себе не означает, что модель подходит любому API методу. Совместимость моделей с API методами приведена в [каталоге моделей](https://coreinfra.ru/docs/catalog.md), цены — на [«Тарифах»](https://hub.coreinfra.ai/pricing).

Для адресов подписки ключ хаба передается в `X-CoreInfra-API-Key`, токен подписки — в `Authorization: Bearer …`.

## Ответы и потоки

OpenAI Chat Completions и OpenAI Responses поддерживают `stream: true`: ответ передается как SSE с `Content-Type: text/event-stream`. Chat Completions передает JSON в строках `data:` и завершает успешный поток маркером `data: [DONE]`; Responses использует именованные события `event: ...`. При конвертации хаб формирует события того протокола, который вызвал клиент.

Images также поддерживает потоковый режим SSE для моделей GPT Image. Синтез речи возвращает аудиобайты либо SSE по `stream_format`. Decisions, Embeddings и подсчет токенов возвращают только JSON. Соединения WebSocket обмениваются JSON-событиями после ответа со статус-кодом `101`.

## Ошибки

Ошибки имеют формат OpenAI:

```json
{
  "error": {
    "message": "Missing required parameter: 'model'.",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}
```

Для ошибок сервера используется `type: "server_error"`, для ограничения частоты — `"rate_limit_error"`, для доступа — `"permission_error"`. Некоторые проверки задают собственные `param` и `code`; они перечислены на страницах соответствующих API методов.

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

Если ошибка возникает после начала потокового ответа SSE, она передается событием потока. Например, в OpenAI Responses (наряду с терминальным событием `response.failed`):

```text
event: error
data: {"type":"error","code":"server_error","message":"The server had an error while processing your request.","param":null,"sequence_number":2}
```

В потоке OpenAI Chat Completions кадр ошибки имеет вид:

```text
data: {"error":{"type":"server_error","message":"Stream error"}}
```
