Запросы и потоковый ответ
Основной провод API моделей это OpenAI Chat Completions: POST /v1/chat/completions на https://api.samreshuuu.ru/v1. Здесь описано, что происходит с каждым полем запроса, как устроен поток и как прочитать стоимость вызова. Провод Anthropic Messages описан на странице «Anthropic SDK и Claude Code», выбор хоста и кэш на странице «Маршрутизация и кэш».
Поля 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:
Модели каталога отвечают через 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 называет разговор для кэша.
| Принимается и не применяется | Отклоняется с 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.
- Последний чанк на проводе 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. Код берётся из таблицы ошибок, текст самого хоста до вас не доходит. Такой вызов не оплачивается: резерв возвращается целиком.
Отмена
Закройте соединение, и хост перестанет генерировать. Оплачивается то, что уже отправлено в поток, как у OpenRouter. Ответ без потока оплачивается полностью, даже если клиент ушёл раньше: модель дописывает его до конца, и вызов закрывается как законченный. Чтобы платить меньше за ответ, который может оказаться ненужным, задавайте max_tokens или используйте поток.
Учёт и стоимость
Ответ на проводе OpenAI несёт usage: сколько токенов ушло на промпт и ответ, сколько прочитано из кэша и записано в него, cost (точная цена вызова) и 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, если сотрудник, выпустивший ключ, не управляет оплатой.
Частые вопросы
Что будет, если закрыть поток посреди ответа?
Хост перестаёт генерировать, и оплачивается то, что уже отправлено. Ответ без потока оплачивается целиком, даже если клиент ушёл раньше: модель дописывает его до конца.
Как узнать, сколько стоил вызов?
На проводе OpenAI последний чанк потока или целый ответ несёт usage.cost в рублях. Для любого вызова, в том числе Messages, GET /v1/generation?id=gen-… отдаёт запись вызова с total_cost; id вызова приходит в заголовке x-request-id.
Почему неизвестное поле не вызывает ошибку?
Неизвестное поле тела отбрасывается и до хоста не доходит, как у OpenRouter: новое поле SDK не ломает вызов. Отклоняются только поля из таблицы со словом «отклоняется».