# Requests and streaming

The Model API's main wire is OpenAI Chat Completions: `POST /v1/chat/completions` on `https://api.samreshuuu.ru/v1`. This page says what happens to each request field, how the stream works and how to read a call's cost. The Anthropic Messages wire is on the [Anthropic SDK and Claude Code](/docs/model-api-anthropic) page, host choice and caching on [Routing and caching](/docs/model-api-routing).

## Chat Completions fields

Every top-level field falls into one of four groups: passed to the host as is, read by us (the model, the output ceiling, the stream, the conversation key, the route), accepted and not applied, refused with `400`.

| Field | What happens to it | Note |
| --- | --- | --- |
| `messages` | passed to the host as sent |  |
| `tools` | passed to the host as sent |  |
| `tool_choice` | passed to the host as sent |  |
| `parallel_tool_calls` | passed to the host as sent |  |
| `response_format` | passed to the host as sent |  |
| `temperature` | passed to the host as sent |  |
| `top_p` | passed to the host as sent |  |
| `top_k` | passed to the host as sent |  |
| `min_p` | passed to the host as sent |  |
| `repetition_penalty` | passed to the host as sent |  |
| `presence_penalty` | passed to the host as sent |  |
| `frequency_penalty` | passed to the host as sent |  |
| `logit_bias` | passed to the host as sent |  |
| `logprobs` | passed to the host as sent |  |
| `top_logprobs` | passed to the host as sent |  |
| `seed` | passed to the host as sent |  |
| `stop` | passed to the host as sent |  |
| `n` | passed to the host as sent |  |
| `user` | passed to the host as sent |  |
| `metadata` | passed to the host as sent |  |
| `reasoning_effort` | passed to the host as sent |  |
| `reasoning` | passed to the host as sent |  |
| `model` | replaced: read by this API, the host gets this API's value |  |
| `max_tokens` | replaced: read by this API, the host gets this API's value |  |
| `max_completion_tokens` | replaced: read by this API, the host gets this API's value |  |
| `stream` | replaced: read by this API, the host gets this API's value |  |
| `stream_options` | replaced: read by this API, the host gets this API's value |  |
| `prompt_cache_key` | replaced: read by this API, the host gets this API's value |  |
| `session_id` | replaced: read by this API, the host gets this API's value |  |
| `models` | replaced: read by this API, the host gets this API's value |  |
| `provider` | replaced: read by this API, the host gets this API's value |  |
| `plugins` | replaced: read by this API, the host gets this API's value |  |
| `usage` | accepted and dropped |  |
| `transforms` | accepted and dropped |  |
| `store` | accepted and dropped |  |
| `service_tier` | accepted and dropped |  |
| `extra_body` | refused with 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` | refused with 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` | refused with 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` | refused with 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. |

A field the table does not list is dropped: the host never gets it and there is no error, as on OpenRouter, so a new OpenAI SDK field does not break the call. `transforms` is dropped whatever its value, `["middle-out"]` included: the prompt is not compressed, and one that is too long gets `context_length_exceeded`. `extra_body`, `extra_headers`, `extra_query` and `timeout` are SDK options: the SDK moves their fields into the body itself, and sent inside the body they are refused.

A `max_tokens` (or `max_completion_tokens`) above the model's ceiling is cut to the ceiling. Without one the answer budget is the model's default, `default_output_tokens` in `GET /v1/models`. Reasoning counts against the answer budget. Either way the budget stays within the model's window minus the prompt. The hold on the balance is sized from this number.

### Tools

`tools`, `tool_choice` and `parallel_tool_calls` reach the host as OpenAI functions. You run the tools: the server never calls them, and you send the result back as a `role: "tool"` message. A call with `tools` goes only to a host that takes tools: the model's `supported_parameters` in `GET /v1/models` lists `tools` when it has such hosts.

### response_format

`response_format` (`json_object` or `json_schema`) reaches the host as is. The host, not this API, enforces the schema: validate the answer on your side.

### reasoning

The reasoning depth is set by `reasoning_effort` in OpenAI's form or by the `reasoning` object in OpenRouter's form (`effort` or `max_tokens`). A level is one of the words `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, weakest first; `none` turns reasoning off. An unknown word gets a `400`.

The levels a model takes are named by its `reasoning` object in `GET /v1/models`: `supported_efforts`, `default_effort` and `mandatory`. `mandatory: true` means the model always reasons and does not take `none`. A model that does not reason has `reasoning: null`. A level the answering host does not take is brought to the nearest one it does, the weaker one on a tie; `none` on a model that cannot turn reasoning off becomes its weakest level. We restate the level in the form the host reads. A host whose reasoning cannot be tuned gets none of these fields. `usage.completion_tokens_details.reasoning_tokens` says how many tokens went to reasoning.

## Responses API and Codex CLI

`POST /v1/responses` takes an OpenAI Responses request and answers with a `response` object, whole or streamed. Nothing is stored: every request carries the whole conversation in `input`, as Codex CLI sends it with `store: false`, and every answer says `store: false`. The fields that point at stored state (`previous_response_id`, `conversation`, a stored `prompt`) and `background` are refused with `400`.

Codex CLI connects as a provider of its own in `~/.codex/config.toml`:

```toml
model_provider = "samreshuuu"
model = "<a model id from /models>"

[model_providers.samreshuuu]
name = "Samreshuuu"
base_url = "https://api.samreshuuu.ru/v1"
env_key = "SAMRESHUUU_API_KEY"
wire_api = "responses"
```

The catalogue's models answer through their hosts' Chat Completions, so the request is translated. `instructions` and `developer` messages become system, `function_call` and `function_call_output` become tool calls and results. A `custom` tool (Codex's `apply_patch`) is passed as a function of one string parameter, `input`, with its grammar in the description, and its call comes back as a `custom_tool_call`. Tools in a `namespace` are passed by their own names. The model's reasoning comes back as a `reasoning` item with its text in `summary`; with `include: ["reasoning.encrypted_content"]` the same text is packed into `encrypted_content`. Send the item back in the next request and the model gets its reasoning back, on another host too. `reasoning.effort` is read the same way as `reasoning_effort` on Chat Completions: a level the host does not take is brought to the nearest one. `prompt_cache_key` names the conversation for the [cache](/docs/model-api-routing#prompt-caching).

| Accepted and not applied | Refused with `400` |
| --- | --- |
| `store`, `service_tier`, `truncation`, `top_logprobs`, `prompt_cache_retention`, `safety_identifier`, `context_management`, `text.verbosity`, the `web_search` and `tool_search` tools (Codex turns them on by itself) | `previous_response_id`, `conversation`, `prompt`, `background`, OpenAI built-in tools (`file_search`, `code_interpreter`, `computer_use_preview`, `image_generation`, `mcp`, `local_shell`, `shell`), `input_file` and `input_audio` parts, an image by `file_id`, `item_reference` items |

## Streaming

`stream: true` sends SSE in the form of its wire: `chat.completion.chunk` chunks on `/v1/chat/completions`, Messages events (`message_start`, `content_block_delta`, `ping`, `message_stop`) on `/v1/messages`, Responses events (`response.created`, `response.output_item.added`, `response.output_text.delta`, `response.output_item.done`, `response.completed`) with `sequence_number` on `/v1/responses`. An answer cut at `max_output_tokens` ends with `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":"Hi! What can you do?"}]}'
```

**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": "Hi! What can you do?"}],
    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: "Hi! What can you do?" }],
    stream: true,
});
for await (const chunk of stream) process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
```

- On the OpenAI wire the last chunk carries `usage` with the cost even when `stream_options.include_usage` is not passed. `data: [DONE]` follows it.
- While the host is silent the stream may carry SSE comment lines that start with a colon (for example `: OPENROUTER PROCESSING`). They are keep-alives: skip them. The OpenAI and Anthropic SDKs do so themselves.
- A stream that fails after it started ends with an error in its wire's form: on the OpenAI wire one chunk with an `error` object (`message`, `type`, `code`) and a choice with `finish_reason: "error"`, as OpenRouter sends it; on the Anthropic wire an `error` event; on `/v1/responses` a `response.failed` event with `error.code` and `error.message`. The code is one of the [error table](/docs/model-api#errors); the host's own wording does not reach you. Such a call is not paid for: the hold is returned in full.

### Cancellation

Close the connection and the host stops generating. What was already sent into the stream is paid for, as on OpenRouter. An answer without streaming is paid in full even if the client left early: the model finishes it and the call closes as completed. To pay less for an answer you may not need, set `max_tokens` or stream.

## Accounting and cost

An answer on the OpenAI wire carries `usage`: the tokens of the prompt and the answer, what was read from and written to the cache, `cost` (the call's exact price) and `cost_currency` (`RUB`). That is what the balance was charged.

```json
{
  "id": "gen-3f9c2a7e5b1d4c8a9e6f0b2d7a4c1e53",
  "object": "chat.completion",
  "created": 1794326400,
  "model": "deepseek/deepseek-v4.1-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! I can answer questions, write and edit text, and work with code."
      },
      "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"
  }
}
```

The answer's `id` (`gen-…`) equals the `x-request-id` header and the `request_id` of an error answer. Every call that came with a known key leaves a record: an answer, a refusal before any host, a host's refusal, a cut stream, a client that disconnected and an error of ours. Only a refusal of the key's minute limit (`429`) leaves none. With the `id`, `GET /v1/generation?id=gen-…` returns the call's record and spends nothing. An ordinary key sees only its own calls, a management key (`keys:manage`) the calls of the whole organization. Another key's call, another organization's call or an unknown `id` gets `404` with the code `generation_not_found`. The log keeps the calls of today and the 30 days before.

How the call ended is `end_word`, and `cancelled` is `true` exactly when the client disconnected mid-answer. Payment is told by the money, not by a separate word: there is no `paid` field, and what was charged is `total_cost` (`0` for an answer released for our error).

| Field | Description |
| --- | --- |
| `id` | The call's id, `gen-…`: the answer's `id` and its `x-request-id`. |
| `created_at` | When the call started, ISO 8601. |
| `model` | The public model that served the call. |
| `provider_name` | The host that answered; `null` when none did. |
| `streamed` | Whether the answer was streamed. |
| `cancelled` | `true` exactly when the client left mid-answer (`end_word` `client_gone`). |
| `latency` | Milliseconds from the call's start to its first streamed output; `null` for an answer not streamed. |
| `generation_time` | Milliseconds from the first output to the end; the whole call when nothing was streamed first. |
| `finish_reason` | Why the answer ended, as the host said. |
| `tokens_prompt` | Prompt tokens. |
| `tokens_completion` | Completion tokens. |
| `native_tokens_cached` | Prompt tokens read from the host's cache. |
| `total_cost` | What the call cost the balance, in roubles: `0` for an answer released for our error, `null` only for a call that left no money row (refused before any host was asked, or failed on our side first). |
| `usage` | The same figure as `total_cost`, in roubles. |
| `cache_discount` | The cache saving, in roubles, signed: a cache write that was not read back is negative. |
| `is_byok` | Always `false`: a key of this API brings no host key of the client. |
| `upstream_id` | Always `null`: this API does not record it. Present so a client reading it finds the key. |
| `moderation_latency` | Always `null`: this API does not record it. Present so a client reading it finds the key. |
| `native_tokens_prompt` | Always `null`: this API does not record it. Present so a client reading it finds the key. |
| `native_tokens_completion` | Always `null`: this API does not record it. Present so a client reading it finds the key. |
| `native_tokens_reasoning` | Always `null`: this API does not record it. Present so a client reading it finds the key. |
| `native_finish_reason` | Always `null`: this API does not record it. Present so a client reading it finds the key. |
| `num_media_prompt` | Always `null`: this API does not record it. Present so a client reading it finds the key. |
| `num_media_completion` | Always `null`: this API does not record it. Present so a client reading it finds the key. |
| `num_search_results` | Always `null`: this API does not record it. Present so a client reading it finds the key. |
| `origin` | Always `null`: this API does not record it. Present so a client reading it finds the key. |
| `app_id` | Always `null`: this API does not record it. Present so a client reading it finds the key. |
| `end_word` | How the call ended, one word: `completed`, `client_gone`, `upstream_cut`, `host_refused`, `reply_unreadable`, `refused`, `internal_error`. |
| `endpoint` | The route the call came to: `chat_completions`, `messages`, `responses`, `images_generations`, `images_edits`, `videos`, `audio_transcriptions`, `embeddings`, `rerank`, `audio_speech`. |

On the Messages wire the answer's `id` reads `msg_…`, as at Anthropic, and `usage` has no `cost`. To look such a call up, take the `gen-…` from the `x-request-id` header.

Summaries: `GET /v1/activity` returns spend by day, model and host (an ordinary key sees its own calls, a management key the whole organization), and `GET /v1/credits` returns the organization balance the key spends. The balance amounts there are `null` and `spend_withheld` is `true` when the member who issued the key does not manage billing.
