# Запросы и потоковый ответ

Основной провод API моделей это OpenAI Chat Completions: `POST /v1/chat/completions` на `https://api.samreshuuu.ru/v1`. Здесь описано, что происходит с каждым полем запроса, как устроен поток и как прочитать стоимость вызова. Провод Anthropic Messages описан на странице [«Anthropic SDK и Claude Code»](/docs/model-api-anthropic), выбор хоста и кэш на странице [«Маршрутизация и кэш»](/docs/model-api-routing).

## Поля Chat Completions

Каждое поле верхнего уровня относится к одной из четырёх групп: передаётся хосту как есть, читается нами (модель, потолок ответа, поток, ключ разговора, маршрут), принимается и не применяется, отклоняется с `400`.

| Поле | Что с ним происходит | Примечание |
| --- | --- | --- |
| `messages` | проходит к хосту как прислано |  |
| `tools` | проходит к хосту как прислано |  |
| `tool_choice` | проходит к хосту как прислано |  |
| `parallel_tool_calls` | проходит к хосту как прислано |  |
| `response_format` | проходит к хосту как прислано |  |
| `temperature` | проходит к хосту как прислано |  |
| `top_p` | проходит к хосту как прислано |  |
| `top_k` | проходит к хосту как прислано |  |
| `min_p` | проходит к хосту как прислано |  |
| `repetition_penalty` | проходит к хосту как прислано |  |
| `presence_penalty` | проходит к хосту как прислано |  |
| `frequency_penalty` | проходит к хосту как прислано |  |
| `logit_bias` | проходит к хосту как прислано |  |
| `logprobs` | проходит к хосту как прислано |  |
| `top_logprobs` | проходит к хосту как прислано |  |
| `seed` | проходит к хосту как прислано |  |
| `stop` | проходит к хосту как прислано |  |
| `n` | проходит к хосту как прислано |  |
| `user` | проходит к хосту как прислано |  |
| `metadata` | проходит к хосту как прислано |  |
| `reasoning_effort` | проходит к хосту как прислано |  |
| `reasoning` | проходит к хосту как прислано |  |
| `model` | заменяется: его читает API, хост получает значение API |  |
| `max_tokens` | заменяется: его читает API, хост получает значение API |  |
| `max_completion_tokens` | заменяется: его читает API, хост получает значение API |  |
| `stream` | заменяется: его читает API, хост получает значение API |  |
| `stream_options` | заменяется: его читает API, хост получает значение API |  |
| `prompt_cache_key` | заменяется: его читает API, хост получает значение API |  |
| `session_id` | заменяется: его читает API, хост получает значение API |  |
| `models` | заменяется: его читает API, хост получает значение API |  |
| `provider` | заменяется: его читает API, хост получает значение API |  |
| `plugins` | заменяется: его читает API, хост получает значение API |  |
| `usage` | принимается и отбрасывается |  |
| `transforms` | принимается и отбрасывается |  |
| `store` | принимается и отбрасывается |  |
| `service_tier` | принимается и отбрасывается |  |
| `extra_body` | отклоняется с 400 | extra_body, extra_headers, extra_query and timeout are SDK request options, merged by the SDK before the request is sent; send their fields at the top level of the body. |
| `extra_headers` | отклоняется с 400 | extra_body, extra_headers, extra_query and timeout are SDK request options, merged by the SDK before the request is sent; send their fields at the top level of the body. |
| `extra_query` | отклоняется с 400 | extra_body, extra_headers, extra_query and timeout are SDK request options, merged by the SDK before the request is sent; send their fields at the top level of the body. |
| `timeout` | отклоняется с 400 | extra_body, extra_headers, extra_query and timeout are SDK request options, merged by the SDK before the request is sent; send their fields at the top level of the body. |

Поле, которого нет в таблице, отбрасывается: хост его не получает, ошибки нет, как у OpenRouter. Поэтому новое поле OpenAI SDK не ломает вызов. `transforms` отбрасывается при любом значении, в том числе `["middle-out"]`: промпт не сжимается, а слишком длинный получает `context_length_exceeded`. `extra_body`, `extra_headers`, `extra_query` и `timeout` это опции SDK: SDK сам переносит их поля в тело, и пришедшие в теле они отклоняются.

`max_tokens` (или `max_completion_tokens`) больше потолка модели урезается до потолка. Без него бюджет ответа равен умолчанию модели, `default_output_tokens` в `GET /v1/models`. Рассуждения входят в бюджет ответа. В обоих случаях бюджет не выходит за окно модели за вычетом промпта. Резерв на балансе считается от этого числа.

### Инструменты

`tools`, `tool_choice` и `parallel_tool_calls` передаются хосту в форме функций OpenAI. Инструменты исполняете вы: сервер их не вызывает, а результат вы возвращаете сообщением `role: "tool"`. Вызов с `tools` уходит только к хосту, который принимает инструменты: `supported_parameters` модели в `GET /v1/models` называет `tools`, если такие хосты есть.

### response_format

`response_format` (`json_object` или `json_schema`) передаётся хосту как есть. Строгость схемы обеспечивает хост, а не мы: проверяйте ответ у себя.

### reasoning

Глубину рассуждения задаёт `reasoning_effort` в форме OpenAI или объект `reasoning` в форме OpenRouter (`effort` или `max_tokens`). Уровень называется одним из слов `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, от слабого к сильному; `none` выключает рассуждения. Неизвестное слово получает `400`.

Какие уровни принимает модель, называет объект `reasoning` модели в `GET /v1/models`: `supported_efforts`, `default_effort` и `mandatory`. `mandatory: true` значит, что модель рассуждает всегда и `none` не принимает. У модели, которая не рассуждает, `reasoning` равен `null`. Уровень, которого ответивший хост не принимает, приводится к ближайшему принимаемому, при равном расстоянии к более слабому; `none` на модели, которая не умеет выключать рассуждения, становится её самым слабым уровнем. Мы переводим уровень в ту форму, которую читает хост. Хосту, у которого рассуждения не настраиваются, поля не отправляются. Сколько токенов ушло на рассуждение, называет `usage.completion_tokens_details.reasoning_tokens`.

## Responses API и Codex CLI

`POST /v1/responses` принимает запрос OpenAI Responses и отвечает объектом `response`, целиком или потоком. Ответы не хранятся: каждый запрос несёт весь разговор в `input`, как Codex CLI шлёт его с `store: false`, а ответ всегда называет `store: false`. Поля, которые ссылаются на сохранённое (`previous_response_id`, `conversation`, сохранённый `prompt`), и `background` отклоняются с `400`.

Codex CLI подключается своим провайдером в `~/.codex/config.toml`:

```toml
model_provider = "samreshuuu"
model = "<id модели со страницы /models>"

[model_providers.samreshuuu]
name = "Сам Решу"
base_url = "https://api.samreshuuu.ru/v1"
env_key = "SAMRESHUUU_API_KEY"
wire_api = "responses"
```

Модели каталога отвечают через Chat Completions своих хостов, поэтому запрос переводится. `instructions` и сообщения `developer` становятся system, `function_call` и `function_call_output` становятся вызовами и результатами инструментов. Инструмент `custom` (у Codex это `apply_patch`) передаётся функцией с одним строковым параметром `input`, его грамматика уходит в описание, а вызов возвращается как `custom_tool_call`. Инструменты из `namespace` передаются по своим именам. Рассуждение модели приходит элементом `reasoning`, его текст стоит в `summary`. С `include: ["reasoning.encrypted_content"]` тот же текст лежит упакованным в `encrypted_content`. Верните элемент в следующем запросе, и модель получит своё рассуждение обратно, в том числе на другом хосте. `reasoning.effort` читается так же, как `reasoning_effort` в Chat Completions: уровень, которого хост не принимает, приводится к ближайшему. `prompt_cache_key` называет разговор для [кэша](/docs/model-api-routing#кэш-промпта).

| Принимается и не применяется | Отклоняется с `400` |
| --- | --- |
| `store`, `service_tier`, `truncation`, `top_logprobs`, `prompt_cache_retention`, `safety_identifier`, `context_management`, `text.verbosity`, инструменты `web_search` и `tool_search` (Codex включает их сам) | `previous_response_id`, `conversation`, `prompt`, `background`, встроенные инструменты OpenAI (`file_search`, `code_interpreter`, `computer_use_preview`, `image_generation`, `mcp`, `local_shell`, `shell`), части `input_file` и `input_audio`, картинка по `file_id`, элемент `item_reference` |

## Потоковый ответ

`stream: true` отдаёт SSE в форме своего провода: чанки `chat.completion.chunk` на `/v1/chat/completions`, события Messages (`message_start`, `content_block_delta`, `ping`, `message_stop`) на `/v1/messages`, события Responses (`response.created`, `response.output_item.added`, `response.output_text.delta`, `response.output_item.done`, `response.completed`) с `sequence_number` на `/v1/responses`. Ответ, обрезанный на `max_output_tokens`, заканчивается событием `response.incomplete`.

**cURL**

```bash
curl -N https://api.samreshuuu.ru/v1/chat/completions \
  -H "Authorization: Bearer $SAMRESHUUU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek/deepseek-v4.1-flash","stream":true,"messages":[{"role":"user","content":"Привет! Что ты умеешь?"}]}'
```

**Python**

```python
import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["SAMRESHUUU_API_KEY"], base_url="https://api.samreshuuu.ru/v1")

stream = client.chat.completions.create(
    model="deepseek/deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "Привет! Что ты умеешь?"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")
```

**Node.js**

```typescript
import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.SAMRESHUUU_API_KEY, baseURL: "https://api.samreshuuu.ru/v1" });

const stream = await client.chat.completions.create({
    model: "deepseek/deepseek-v4.1-flash",
    messages: [{ role: "user", content: "Привет! Что ты умеешь?" }],
    stream: true,
});
for await (const chunk of stream) process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
```

- Последний чанк на проводе OpenAI несёт `usage` со стоимостью, даже если `stream_options.include_usage` не передан. За ним идёт `data: [DONE]`.
- Пока хост молчит, в поток могут приходить строки-комментарии SSE, которые начинаются с двоеточия (например, `: OPENROUTER PROCESSING`). Это keep-alive: пропускайте их. SDK OpenAI и Anthropic делают это сами.
- Поток, который сорвался после начала, заканчивается ошибкой в форме своего провода: на проводе OpenAI одним чанком с объектом `error` (`message`, `type`, `code`) и вариантом с `finish_reason: "error"`, как у OpenRouter; на проводе Anthropic событием `error`; на `/v1/responses` событием `response.failed` с `error.code` и `error.message`. Код берётся из [таблицы ошибок](/docs/model-api#ошибки), текст самого хоста до вас не доходит. Такой вызов не оплачивается: резерв возвращается целиком.

### Отмена

Закройте соединение, и хост перестанет генерировать. Оплачивается то, что уже отправлено в поток, как у OpenRouter. Ответ без потока оплачивается полностью, даже если клиент ушёл раньше: модель дописывает его до конца, и вызов закрывается как законченный. Чтобы платить меньше за ответ, который может оказаться ненужным, задавайте `max_tokens` или используйте поток.

## Учёт и стоимость

Ответ на проводе OpenAI несёт `usage`: сколько токенов ушло на промпт и ответ, сколько прочитано из кэша и записано в него, `cost` (точная цена вызова) и `cost_currency` (`RUB`). Столько и списано с баланса.

```json
{
  "id": "gen-3f9c2a7e5b1d4c8a9e6f0b2d7a4c1e53",
  "object": "chat.completion",
  "created": 1794326400,
  "model": "deepseek/deepseek-v4.1-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Привет! Отвечаю на вопросы, пишу и правлю тексты, работаю с кодом."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "cache_write_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0
    },
    "cost": 0.01,
    "cost_currency": "RUB"
  }
}
```

`id` ответа (`gen-…`) совпадает с заголовком `x-request-id` и с `request_id` в ответе с ошибкой. Запись остаётся у каждого вызова, который пришёл с известным ключом: у ответа, у отказа до хоста, у отказа хоста, у оборванного потока, у отключившегося клиента и у нашей ошибки. Нет записи только у отказа по минутному лимиту ключа (`429`). По `id` запрос `GET /v1/generation?id=gen-…` отдаёт запись вызова и ничего не тратит. Обычный ключ видит только свои вызовы, ключ управления (`keys:manage`) видит вызовы всей организации. Вызов другого ключа, чужой организации или неизвестный `id` получает `404` с кодом `generation_not_found`. Журнал хранит вызовы за сегодня и 30 прошлых дней.

Чем кончился вызов, называет `end_word`, а `cancelled` равно `true` ровно тогда, когда клиент отключился посреди ответа. Оплату называют деньги, а не отдельное слово: поля `paid` нет, списанное показывает `total_cost` (`0` у ответа, отпущенного по нашей ошибке).

| Поле | Описание |
| --- | --- |
| `id` | Идентификатор вызова, `gen-…`: `id` ответа и его `x-request-id`. |
| `created_at` | Когда начался вызов, ISO 8601. |
| `model` | Публичная модель, которая обслужила вызов. |
| `provider_name` | Хост, который ответил; `null`, если ни один. |
| `streamed` | Шёл ли ответ потоком. |
| `cancelled` | `true` ровно тогда, когда клиент ушёл посреди ответа (`end_word` `client_gone`). |
| `latency` | Миллисекунды от начала вызова до первого вывода потоком; `null`, если ответ шёл не потоком. |
| `generation_time` | Миллисекунды от первого вывода до конца; весь вызов, если сначала ничего не пришло потоком. |
| `finish_reason` | Почему закончился ответ, словами хоста. |
| `tokens_prompt` | Токены промпта. |
| `tokens_completion` | Токены ответа. |
| `native_tokens_cached` | Токены промпта, прочитанные из кэша хоста. |
| `total_cost` | Сколько вызов стоил балансу, в рублях: `0`, если ответ отпущен по нашей ошибке, `null` только у вызова без денежной строки (отказ до обращения к хосту или наша ошибка раньше записи денег). |
| `usage` | То же число, что `total_cost`, в рублях. |
| `cache_discount` | Экономия на кэше в рублях, со знаком: запись в кэш, которую не прочитали, отрицательна. |
| `is_byok` | Всегда `false`: ключ этого API не приносит ключ клиента к хосту. |
| `upstream_id` | Всегда `null`: этот API его не записывает. Поле есть, чтобы клиент, который его читает, нашёл ключ. |
| `moderation_latency` | Всегда `null`: этот API его не записывает. Поле есть, чтобы клиент, который его читает, нашёл ключ. |
| `native_tokens_prompt` | Всегда `null`: этот API его не записывает. Поле есть, чтобы клиент, который его читает, нашёл ключ. |
| `native_tokens_completion` | Всегда `null`: этот API его не записывает. Поле есть, чтобы клиент, который его читает, нашёл ключ. |
| `native_tokens_reasoning` | Всегда `null`: этот API его не записывает. Поле есть, чтобы клиент, который его читает, нашёл ключ. |
| `native_finish_reason` | Всегда `null`: этот API его не записывает. Поле есть, чтобы клиент, который его читает, нашёл ключ. |
| `num_media_prompt` | Всегда `null`: этот API его не записывает. Поле есть, чтобы клиент, который его читает, нашёл ключ. |
| `num_media_completion` | Всегда `null`: этот API его не записывает. Поле есть, чтобы клиент, который его читает, нашёл ключ. |
| `num_search_results` | Всегда `null`: этот API его не записывает. Поле есть, чтобы клиент, который его читает, нашёл ключ. |
| `origin` | Всегда `null`: этот API его не записывает. Поле есть, чтобы клиент, который его читает, нашёл ключ. |
| `app_id` | Всегда `null`: этот API его не записывает. Поле есть, чтобы клиент, который его читает, нашёл ключ. |
| `end_word` | Чем кончился вызов, одним словом: `completed`, `client_gone`, `upstream_cut`, `host_refused`, `reply_unreadable`, `refused`, `internal_error`. |
| `endpoint` | Маршрут, на который пришёл вызов: `chat_completions`, `messages`, `responses`, `images_generations`, `images_edits`, `videos`, `audio_transcriptions`, `embeddings`, `rerank`, `audio_speech`. |

На проводе Messages `id` ответа имеет вид `msg_…`, как у Anthropic, и в `usage` нет `cost`. Чтобы найти такой вызов, берите `gen-…` из заголовка `x-request-id`.

Сводки: `GET /v1/activity` отдаёт расход по дням, моделям и хостам (обычный ключ видит свои вызовы, ключ управления всю организацию), `GET /v1/credits` отдаёт баланс организации, который тратит ключ. Суммы баланса там равны `null` и `spend_withheld` равен `true`, если сотрудник, выпустивший ключ, не управляет оплатой.
