# API моделей

API моделей отдаёт модели нашего каталога по ключу организации. Запросы принимаются в трёх формах: OpenAI Chat Completions, OpenAI Responses и Anthropic Messages, поэтому подойдут OpenAI SDK, OpenAI Agents SDK, Anthropic SDK, Claude Code и Codex CLI, поменяйте только адрес и ключ. Вызовы оплачиваются с [баланса организации](https://platform.samreshuuu.ru), тариф для этого не нужен.

Это не [API агентов](/docs/openai-compatible): там `model` называет агента организации с его инструментами и подключениями, а здесь модель, которая отвечает на ваш промпт как есть.

От регистрации до первого ответа нужно пополнить баланс, создать ключ в консоли и вызвать модель. Все шаги по порядку на странице [«Быстрый старт»](/docs/quickstart). Баланс пополняется в [консоли разработчика](https://platform.samreshuuu.ru); комиссии за пополнение нет, а вызов стоит столько, сколько берёт хост, который на него ответил, плюс наши 20%.

Страницы API моделей:

- [Запросы и потоковый ответ](/docs/model-api-requests): поля Chat Completions, инструменты, `response_format`, `reasoning`, Responses API и Codex CLI, поток, отмена и как прочитать стоимость вызова.
- [Маршрутизация и кэш](/docs/model-api-routing): выбор хостов в `provider`, запасные модели, `auto`, данные в РФ, кэш промпта, `plugins`.
- [Anthropic SDK и Claude Code](/docs/model-api-anthropic): провод Messages, `anthropic-beta`, подсчёт токенов.
- [Картинки, ролики и речь](/docs/model-api-media): картинки, ролики, расшифровка и синтез речи, эмбеддинги и переранжирование.

## Адреса

| Клиент | Адрес | Маршрут |
| --- | --- | --- |
| OpenAI SDK, curl, клиенты OpenRouter | `https://api.samreshuuu.ru/v1` (`base_url`) | `POST /v1/chat/completions` |
| Anthropic SDK | `https://api.samreshuuu.ru` (`base_url`, без `/v1`) | `POST /v1/messages` |
| Claude Code | `ANTHROPIC_BASE_URL=https://api.samreshuuu.ru` | `POST /v1/messages` |
| Codex CLI, OpenAI Agents SDK, OpenAI SDK `responses.create` | `https://api.samreshuuu.ru/v1` (`base_url`) | `POST /v1/responses` |
| Список моделей, одна модель, хосты модели, хосты, число моделей, оценки моделей (без ключа) | `https://api.samreshuuu.ru/v1` | `GET /v1/models`, `GET /v1/model/{id}`, `GET /v1/models/{id}/endpoints`, `GET /v1/providers`, `GET /v1/models/count`, `GET /v1/benchmarks` |
| Картинки (OpenAI SDK `images.generate` / `images.edit`) | `https://api.samreshuuu.ru/v1` | `POST /v1/images/generations`, `POST /v1/images/edits` |
| Ролики (OpenAI SDK `videos.create` / `videos.retrieve` / `videos.download_content`) | `https://api.samreshuuu.ru/v1` | `POST /v1/videos`, `GET /v1/videos/{id}`, `GET /v1/videos/{id}/content` |
| Расшифровка речи (OpenAI SDK `audio.transcriptions.create`) | `https://api.samreshuuu.ru/v1` | `POST /v1/audio/transcriptions` |
| Эмбеддинги (OpenAI SDK `embeddings.create`), список моделей эмбеддингов (без ключа) | `https://api.samreshuuu.ru/v1` | `POST /v1/embeddings`, `GET /v1/embeddings/models` |
| Переранжирование (в OpenAI SDK вызова нет) | `https://api.samreshuuu.ru/v1` | `POST /v1/rerank` |
| Синтез речи (OpenAI SDK `audio.speech.create`) | `https://api.samreshuuu.ru/v1` | `POST /v1/audio/speech` |

## Аутентификация

Ключ организации `sk-org-…` (см. [Аутентификацию](/docs/authentication)) передаётся в `Authorization: Bearer` или в `x-api-key`, на любом маршруте: OpenAI SDK шлёт первый, Anthropic SDK второй. Запрос с двумя разными ключами в этих заголовках отклоняется с `401` и кодом `ambiguous_api_key`, а не читается по одному из них.

Ключ API моделей выпускается в [консоли разработчика](https://platform.samreshuuu.ru), раздел «Ключи API», с доступом «API моделей» (`models`) и показывается один раз. Ключ агента из того же раздела моделей не вызывает: ни один его вариант, **Полный доступ** тоже, не несёт `models:write`, и вызов с ним отклоняется с `403` и кодом `insufficient_scope`. Ключ управления (доступ `management`, право `keys:manage`) управляет ключами организации через `/v1/keys` и модели тоже не вызывает; в ответе его узнают по `kind: "management"`.

Все маршруты, scope, который они спрашивают, и считается ли запрос в минуте ключа:

| Метод | Маршрут | Scope ключа | Считается в минутном лимите |
| --- | --- | --- | --- |
| GET | `/v1/models` | без ключа | нет |
| POST | `/v1/chat/completions` | `models:write` | да |
| POST | `/v1/messages` | `models:write` | да |
| POST | `/v1/responses` | `models:write` | да |
| POST | `/v1/messages/count_tokens` | `models:read` | да |
| POST | `/v1/images/generations` | `models:write` | да |
| POST | `/v1/images/edits` | `models:write` | да |
| POST | `/v1/videos` | `models:write` | да |
| POST | `/v1/audio/transcriptions` | `models:write` | да |
| POST | `/v1/audio/speech` | `models:write` | да |
| POST | `/v1/embeddings` | `models:write` | да |
| POST | `/v1/rerank` | `models:write` | да |
| GET | `/v1/videos/{video_id}` | `models:read` | нет |
| GET | `/v1/videos/{video_id}/content` | `models:read` | нет |
| GET | `/v1/generation` | `models:read` | нет |
| GET | `/v1/activity` | `models:read` | нет |
| GET | `/v1/key` | `models:read` | нет |
| GET | `/v1/credits` | `models:read` | нет |
| GET | `/v1/keys` | `keys:manage` | нет |
| POST | `/v1/keys` | `keys:manage` | нет |
| GET | `/v1/keys/{key_id}` | `keys:manage` | нет |
| PATCH | `/v1/keys/{key_id}` | `keys:manage` | нет |
| DELETE | `/v1/keys/{key_id}` | `keys:manage` | нет |

Каталог моделей (`GET /v1/models` и маршруты рядом с ним) публичный: ключ не читается. Лимит частоты по тарифу здесь не действует: вызов платит баланс, а расход одного ключа ограничивает его лимит трат, который задаётся у ключа в консоли.

### Ключ о себе

`GET /v1/key` отвечает ключу о нём самом и ничего не тратит:

| Поле | Описание |
| --- | --- |
| `id` | Идентификатор ключа. |
| `name` | Название ключа, заданное в консоли. |
| `key_masked` | Ключ в том виде, в каком его показывает список, `sk-org-…abcd`; целиком ключ показывается один раз, при выпуске. |
| `scopes` | Слова доступа ключа, каждое `ресурс:действие`. |
| `created_at` | Когда ключ выпущен, ISO 8601. |
| `expires_at` | Когда ключ перестанет работать, ISO 8601; `null`, если срока нет. |
| `last_used_at` | Когда ключ последний раз принят, ISO 8601, отметка не чаще раза в несколько минут; `null`, если ни разу. |
| `spend_limit_kop` | Лимит трат ключа в копейках; `null`, если лимита нет. |
| `spend_limit_reset` | Когда лимит начинается заново: `day`, `week` или `month`; `null` при заданном лимите значит лимит на весь срок ключа. |
| `spent_kop` | Всё, что потратил ключ, в копейках. |
| `spent_period_kop` | Потрачено в текущем периоде лимита, в копейках. Идущий вызов учтён по резерву, пока не рассчитан. |
| `limit_remaining_kop` | Остаток лимита в этом периоде, в копейках; `null`, если лимита нет. |
| `spend_withheld` | `true`, если денежные поля равны `null`, потому что читателю их не показывают; ключ о себе видит свои. |
| `period_resets_at` | Когда период начнётся заново, ISO 8601; `null` без лимита или при лимите на весь срок. |
| `access` | Вариант доступа, с которым выпущен ключ: `models`, `full`, `apps`, `read` или `management`; `custom`, если набор другой. |
| `kind` | `model_api` (API моделей), `agent` (агент и сервисы) или `management` (ключ управления: управляет ключами организации через `/v1/keys` и модели не вызывает). |
| `state` | `active`, `expiring` (срок кончается в ближайшие семь дней), `limit_reached` (каждый вызов получает `key_limit_exceeded` до сброса), `expired`, `disabled` (ключ отключён и не принимается, пока его не включат) или `revoked`. |
| `opens` | Что открывают слова ключа: `agent`, `connectors`, `models`. |
| `spends_balance` | `true`, если ключ тратит баланс организации и поэтому принимает лимит трат. |
| `issued_by_key_id` | Ключ управления, выпустивший этот ключ через `/v1/keys`; `null` у ключа из консоли. |
| `disabled_at` | Когда ключ отключён, ISO 8601; `null`, пока он включён. |
| `holder` | Кто держит ключ: `kind` (`member` или `service_account`), `id` и `name`. Ключ сервисного аккаунта переживает место того, кто его выпустил. |
| `rate_limits` | `requests_per_minute` и `tokens_per_minute`, у каждого `limit`, `remaining` и `resets_at`; `remaining` и `resets_at` равны `null`, если минуту не удалось прочитать. |

## Лимиты частоты

Один ключ может начать до 1000 запросов и потратить до 10000000 токенов за календарную минуту. Предел один для всех ключей и не зависит от баланса: он останавливает зациклившийся скрипт, обычная работа до него не доходит. Токены это запрос и ответ без прочитанного из кэша, они считаются по окончании вызова: запрос проходит, пока токены минуты не исчерпаны.

Каждый маршрут вызова отвечает с минутой в заголовках OpenAI: `x-ratelimit-limit-requests`, `x-ratelimit-remaining-requests`, `x-ratelimit-reset-requests` и те же три для `tokens`, сброс в виде `12s`. `/v1/messages` шлёт ещё заголовки Anthropic `anthropic-ratelimit-requests-*` и `anthropic-ratelimit-tokens-*` со сбросом в RFC 3339. Сверх предела вызов отклоняется с `429` и кодом `key_rate_limited`, заголовком `Retry-After` в секундах и минутой в `error.metadata`; деньги не списываются. `429` с кодом `upstream_rate_limited` пришёл от хоста модели, а не от вашего ключа.

Остаток минуты показывает `rate_limits` в [`GET /v1/key`](#ключ-о-себе).

## Модели

Все модели и цены каждого хоста показывает страница [«Модели»](/models), без ключа. Из кода тот же каталог отдаёт `GET /v1/models` в форме OpenAI и OpenRouter. `id` модели имеет вид `<вендор>/<модель>`, как у OpenRouter, поэтому код, написанный под OpenRouter, сохраняет строку модели. В каждой записи:

- `context_length` и `max_output_tokens`;
- `pricing`: цена хоста по умолчанию, куда уходит вызов, если вы не выбрали хост, в рублях (`currency: "RUB"`) за `unit_tokens` токенов для промпта (`prompt`), ответа (`completion`), чтения из кэша (`input_cache_read`) и записи в кэш (`input_cache_write`); цена хоста в долларах переведена по курсу ЦБ, который стоит рядом: `usd_rub_rate` (рублей за доллар) и `usd_rub_rate_on` (дата курса);
- `supported_parameters`: поля запроса, которые модель принимает, среди них `tools`, если её хосты принимают инструменты;
- `endpoints`: хосты, которые обслуживают модель сейчас, у каждого своя цена `pricing` той же формы, окно, вид кэша (`cache`: `auto_prefix`, `session_header`, `explicit_breakpoints` или `none`), принимает ли он инструменты, на каких проводах говорит (`wires`: `chat`, `messages`) и где обрабатывает данные (`data_region`: `ru` или `us`).

Вызов оплачивается по цене хоста, который на него ответил, плюс наши 20%: у одной модели хосты бывают разной цены, как у OpenRouter. Если первый хост не ответил и вызов ушёл к следующему, цена берётся у следующего. Цена в долларах США списывается в рублях по официальному курсу ЦБ РФ на день вызова. Резерв и списание одного вызова идут по одному курсу. Какие хосты допустимы и в каком порядке они пробуются, задаёт объект `provider`, см. [«Маршрутизация и кэш»](/docs/model-api-routing).

Перед вызовом на балансе резервируется верхняя оценка: промпт и потолок ответа по цене самого дорогого хоста, к которому может уйти вызов. После ответа списывается фактическая стоимость, остаток резерва возвращается; вызов, который не дал ответа по вине хоста или нашей, не стоит ничего. Как прочитать стоимость вызова, описано в разделе [«Учёт и стоимость»](/docs/model-api-requests#учёт-и-стоимость).

Последняя запись называет `auto` ([выбор модели](/docs/model-api-routing#выбор-модели-auto)): её цены равны `"-1"`, потому что вызов стоит столько, сколько стоит выбранная модель. Модель вне каталога отклоняется с `404` и кодом `model_not_found`, подмены другой моделью нет.

### Хосты модели и их доступность

Маршруты в форме OpenRouter, все без ключа:

- `GET /v1/model/{id}` отдаёт одну запись списка и в `links.details` путь к её хостам.
- `GET /v1/models/{id}/endpoints` отдаёт хосты модели, которые обслуживают её сейчас: те же поля, что в `endpoints` списка, плюс `provider_name`, `supported_parameters` этого хоста, `supports_implicit_caching` и доля вызовов, на которые хост ответил, в процентах: `uptime_last_5m`, `uptime_last_30m`, `uptime_last_1d`. Считаются все попытки к хосту, в том числе те, что потом спас переход к другому хосту. Сбоем считаются ошибки хоста (5xx, таймаут, `429`, отказ ключа или баланса), а не ошибки запроса и не отмена. Окно без вызовов равно `null`, а не 100. Цифры обновляются раз в полминуты и отстают от реальности до минуты. `latency_last_30m` и `throughput_last_30m` равны `null`: скорость хостов пока не измеряется. Принимает `?data_region=ru`, как список.
- `GET /v1/providers` отдаёт хосты, к которым сейчас уходят вызовы: имя (`name`), слово для `provider.only` и `provider.order` (`slug`), ссылки на политику конфиденциальности, условия и страницу статуса хоста (`privacy_policy_url`, `terms_of_service_url`, `status_page_url`, `null`, если её нет), страну юрлица (`headquarters`) и страну обработки данных (`datacenters`).
- `GET /v1/models/count` отдаёт `{"data": {"count": n}}`: число текстовых моделей списка, с `?output_modalities=all` всех, с `?output_modalities=image,video` моделей с таким ответом.
- `GET /v1/benchmarks` отдаёт оценки моделей: индекс интеллекта Artificial Analysis (`intelligence_index`, от 0 до 100) по всей таблице, сильные выше, и у моделей, которые мы продаём, их id (`model_permaslug`, у остальных `null`). Оценка относится ровно к этой версии модели: у модели, которую источник не оценивал, строки нет. `coding_index` и `agentic_index` пока `null`. У строк текстовых моделей `task_type` равен `intelligence`. Рядом стоят рейтинги медиа по задачам: `task_type` `text-to-image`, `image-editing`, `text-to-video`, `image-to-video`, `text-to-speech` с полем `elo` (слепое сравнение людьми, больше лучше) и `speech-to-text` с полем `word_error_rate` (доля ошибок в словах, меньше лучше). В каждом рейтинге десять лидеров источника и наши модели. Эмбеддинги и реранкеры источник не оценивает. В `meta` дата сверки с источником (`as_of`), ссылка на источник (`source_url`) и подпись (`citation`), которую нужно ставить рядом с цифрами, если вы их публикуете.

`max_tokens` (или `max_completion_tokens`) больше потолка модели урезается до потолка; без него модель получает свой потолок. Резерв на балансе считается от этого числа, поэтому небольшой `max_tokens` нужен и для того, чтобы вызов прошёл при небольшом балансе.

## Ошибки

Провод OpenAI отвечает `{"error": {"message", "type", "code"}, "request_id"}`, провод Anthropic отвечает `{"type": "error", "error": {"type", "message"}, "request_id"}`: ветвитесь по `code` на первом и по `type` на втором. `request_id` совпадает с заголовком `x-request-id` и, на проводе OpenAI, с `id` ответа: назовите его, если пишете в поддержку. Отказ по лимиту трат ключа на проводе OpenAI несёт `error.metadata` с теми же именами, что в ответе ключа: `spend_limit_kop`, `spent_period_kop`, `limit_remaining_kop`, `period_resets_at`, и резерв этого вызова `request_hold_kop`. Отказ `insufficient_balance` несёт в `error.metadata` только `request_hold_kop`: сумму, которую баланс не покрыл.

Таблица приводит стандартный `message` сервера на английском. Отказ может уточнять детали запроса.

| HTTP | type | Код | message | Повтор |
| --- | --- | --- | --- | --- |
| 400 | `invalid_request_error` | `content_blocked` | The model host's safety system refused the prompt or an input image. | нет |
| 400 | `invalid_request_error` | `context_length_exceeded` | The prompt and max_tokens exceed the model's window. | нет |
| 400 | `invalid_request_error` | `invalid_body` | The request body must be a JSON object. | нет |
| 400 | `invalid_request_error` | `invalid_json` | The request body is not valid JSON. | нет |
| 400 | `invalid_request_error` | `invalid_models` | models must be a short list of model ids. | нет |
| 400 | `invalid_request_error` | `invalid_parameter` | A request field has a wrong shape. | нет |
| 400 | `invalid_request_error` | `invalid_provider_preferences` | provider must be an object of OpenRouter's provider preferences. | нет |
| 400 | `invalid_request_error` | `limit_not_spending` | This key spends no balance, so a spending limit has nothing to limit. | нет |
| 400 | `invalid_request_error` | `no_auto_model` | No model meets the request for auto. | нет |
| 400 | `invalid_request_error` | `price_above_max` | Every eligible host of the model is priced above provider.max_price. | нет |
| 400 | `invalid_request_error` | `server_tool` | Anthropic server tools run on Anthropic's side and are not served here. | нет |
| 400 | `invalid_request_error` | `unknown_provider` | The provider object names a host this API does not route to. | нет |
| 400 | `invalid_request_error` | `unsupported_block` | The request has a content block this API does not support. | нет |
| 400 | `invalid_request_error` | `unsupported_parameter` | The request uses a field this API does not support. | нет |
| 400 | `invalid_request_error` | `unsupported_plugin` | Only the auto-router plugin is supported. | нет |
| 400 | `invalid_request_error` | `unsupported_provider_preference` | The provider object has a preference this API does not honour. | нет |
| 400 | `invalid_request_error` | `upstream_bad_request` | The model host refused the request. | нет |
| 401 | `authentication_error` | `ambiguous_api_key` | The request carries two different keys in 'Authorization' and 'x-api-key'. Send one. | нет |
| 401 | `authentication_error` | `invalid_api_key` | The API key is unknown, revoked or expired. | нет |
| 401 | `authentication_error` | `missing_api_key` | Pass an organization API key as 'Authorization: Bearer sk-org-…' or 'x-api-key'. | нет |
| 402 | `billing_error` | `insufficient_balance` | The organization balance does not cover this request (max_tokens is held in full until the answer is settled). Top up the balance or lower max_tokens. | нет |
| 402 | `billing_error` | `key_limit_exceeded` | This API key has reached its spending limit. Raise the limit or use another key. | нет |
| 402 | `billing_error` | `spend_cap_reached` | The organization's monthly spend cap is reached. A billing admin can raise it in the console; a top-up does not lift it. | нет |
| 403 | `permission_error` | `api_keys_not_enabled` | The developer console is not enabled for this organization. | нет |
| 403 | `permission_error` | `balance_not_offered` | The organization balance is not open for the model API. | нет |
| 403 | `permission_error` | `insufficient_scope` | This API key lacks the scope of this route. Create a key with it. | нет |
| 404 | `not_found_error` | `generation_not_found` | No call with this id belongs to this organization in the last 30 days. | нет |
| 404 | `not_found_error` | `key_not_found` | No live key with this id that a management key may manage belongs to this organization. | нет |
| 404 | `not_found_error` | `model_not_found` | The model does not exist. GET /v1/models lists the models this API sells. | нет |
| 404 | `not_found_error` | `no_eligible_host` | No host of the model meets the request's provider preferences. | нет |
| 404 | `not_found_error` | `not_found` | This is not a route of this API. | нет |
| 404 | `not_found_error` | `video_not_found` | No video with this id belongs to this organization. | нет |
| 405 | `invalid_request_error` | `method_not_allowed` | This route does not take this method. | нет |
| 409 | `invalid_request_error` | `video_not_ready` | The video is not completed. Poll GET /v1/videos/{id} until its status is completed. | да |
| 410 | `not_found_error` | `video_expired` | The video's content is past its expires_at and is no longer kept. | нет |
| 413 | `request_too_large` | `request_too_large` | The request body is larger than this API reads. | нет |
| 429 | `rate_limit_error` | `key_rate_limited` | This API key reached its requests or tokens per minute. Retry after Retry-After seconds. | да |
| 429 | `rate_limit_error` | `upstream_rate_limited` | The model host is busy. Retry the request later. | да |
| 500 | `api_error` | `internal_error` | The request failed on our side. Retry it later. | да |
| 502 | `api_error` | `upstream_reply_unreadable` | The model host answered something this API cannot read. | да |
| 502 | `api_error` | `upstream_stream_cut` | The model host broke off the answer. | да |
| 502 | `api_error` | `upstream_unavailable` | No model host answered. Retry the request later. | да |
| 503 | `overloaded_error` | `balance_unavailable` | The organization balance could not be read now. Retry the request later. | да |
| 503 | `overloaded_error` | `model_not_ready` | This model is not served on this deployment now: its vendor account is not configured. | нет |
| 503 | `overloaded_error` | `model_unavailable` | The model has no host available right now. Retry the request later. | да |
| 503 | `overloaded_error` | `upstream_overloaded` | The model host is busy. Retry the request later. | да |
| 504 | `timeout_error` | `upstream_timeout` | The model host did not answer in time. Retry the request later. | да |

Отказы `402` не повторяйте: вызов пройдёт только после пополнения баланса или подъёма лимита. `429 key_rate_limited` повторите через `Retry-After` секунд, другой `429` и `5xx` после паузы.
