# Model API

The Model API serves the models of our catalogue to an organization key. It accepts requests in three forms, OpenAI Chat Completions, OpenAI Responses and Anthropic Messages, so the OpenAI SDK, the OpenAI Agents SDK, the Anthropic SDK, Claude Code and Codex CLI all work: change only the address and the key. Calls are paid from the [organization balance](https://platform.samreshuuu.ru); no plan is needed for that.

This is not the [Agent API](/docs/openai-compatible): there `model` names an agent of your organization with its tools and connections, here it names a model that answers your prompt as is.

From signing up to the first answer, you top up the balance, create a key in the console and call a model. Every step, in order, is on the [Quickstart](/docs/quickstart) page. The balance is topped up in the [developer console](https://platform.samreshuuu.ru); there is no top-up fee, and a call costs what the host that answered it charges, plus our 20%.

The Model API pages:

- [Requests and streaming](/docs/model-api-requests): Chat Completions fields, tools, `response_format`, `reasoning`, the Responses API and Codex CLI, streaming, cancellation and how to read a call's cost.
- [Routing and caching](/docs/model-api-routing): choosing hosts with `provider`, fallback models, `auto`, data in Russia, prompt caching, `plugins`.
- [Anthropic SDK and Claude Code](/docs/model-api-anthropic): the Messages wire, `anthropic-beta`, token counting.
- [Pictures, videos and speech](/docs/model-api-media): pictures, videos, speech transcription and text to speech, embeddings and rerank.

## Addresses

| Client | Address | Route |
| --- | --- | --- |
| OpenAI SDK, curl, OpenRouter clients | `https://api.samreshuuu.ru/v1` (`base_url`) | `POST /v1/chat/completions` |
| Anthropic SDK | `https://api.samreshuuu.ru` (`base_url`, without `/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` |
| Model list, one model, a model's hosts, the hosts, the model count, model scores (no key) | `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` |
| Pictures (OpenAI SDK `images.generate` / `images.edit`) | `https://api.samreshuuu.ru/v1` | `POST /v1/images/generations`, `POST /v1/images/edits` |
| Videos (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` |
| Audio transcriptions (OpenAI SDK `audio.transcriptions.create`) | `https://api.samreshuuu.ru/v1` | `POST /v1/audio/transcriptions` |
| Embeddings (OpenAI SDK `embeddings.create`), embedding model list (no key) | `https://api.samreshuuu.ru/v1` | `POST /v1/embeddings`, `GET /v1/embeddings/models` |
| Rerank (no OpenAI SDK call) | `https://api.samreshuuu.ru/v1` | `POST /v1/rerank` |
| Text to speech (OpenAI SDK `audio.speech.create`) | `https://api.samreshuuu.ru/v1` | `POST /v1/audio/speech` |

## Authentication

An organization key `sk-org-…` (see [Authentication](/docs/authentication)) goes in `Authorization: Bearer` or in `x-api-key`, on any route: the OpenAI SDK sends the first, the Anthropic SDK the second. A request carrying two different keys in these headers is refused with `401` and the code `ambiguous_api_key` rather than read by one of them.

A Model API key is issued in the [developer console](https://platform.samreshuuu.ru), under API keys, with the Model API access (`models`), and is shown once. An agent key from the same section calls no model: none of its options, **Full access** included, carries `models:write`, and a call with it is refused with `403` and the code `insufficient_scope`. A management key (access `management`, scope `keys:manage`) manages the organization's keys over `/v1/keys` and calls no model either; a response tells it by `kind: "management"`.

Every route, the scope it asks and whether it counts on the key's minute:

| Method | Route | Key scope | Counts toward the per-minute limit |
| --- | --- | --- | --- |
| GET | `/v1/models` | no key | no |
| POST | `/v1/chat/completions` | `models:write` | yes |
| POST | `/v1/messages` | `models:write` | yes |
| POST | `/v1/responses` | `models:write` | yes |
| POST | `/v1/messages/count_tokens` | `models:read` | yes |
| POST | `/v1/images/generations` | `models:write` | yes |
| POST | `/v1/images/edits` | `models:write` | yes |
| POST | `/v1/videos` | `models:write` | yes |
| POST | `/v1/audio/transcriptions` | `models:write` | yes |
| POST | `/v1/audio/speech` | `models:write` | yes |
| POST | `/v1/embeddings` | `models:write` | yes |
| POST | `/v1/rerank` | `models:write` | yes |
| GET | `/v1/videos/{video_id}` | `models:read` | no |
| GET | `/v1/videos/{video_id}/content` | `models:read` | no |
| GET | `/v1/generation` | `models:read` | no |
| GET | `/v1/activity` | `models:read` | no |
| GET | `/v1/key` | `models:read` | no |
| GET | `/v1/credits` | `models:read` | no |
| GET | `/v1/keys` | `keys:manage` | no |
| POST | `/v1/keys` | `keys:manage` | no |
| GET | `/v1/keys/{key_id}` | `keys:manage` | no |
| PATCH | `/v1/keys/{key_id}` | `keys:manage` | no |
| DELETE | `/v1/keys/{key_id}` | `keys:manage` | no |

The model catalogue (`GET /v1/models` and the routes beside it) is public: no key is read. The per-plan rate limit does not apply here: the balance pays for the call, and what bounds one key is its spend limit, set on the key in the console.

### The key about itself

`GET /v1/key` answers the key about itself and spends nothing:

| Field | Description |
| --- | --- |
| `id` | The key's id. |
| `name` | The key's name, as set in the console. |
| `key_masked` | The key as a list shows it, `sk-org-…abcd`; the full key is shown once, when it is minted. |
| `scopes` | The key's words, `resource:action` each. |
| `created_at` | When the key was minted, ISO 8601. |
| `expires_at` | When the key stops working, ISO 8601; `null` is no end date. |
| `last_used_at` | When the key was last admitted, ISO 8601, stamped at most once in a few minutes; `null` if never. |
| `spend_limit_kop` | The key's spending limit, in kopecks; `null` is no limit. |
| `spend_limit_reset` | When the limit starts over: `day`, `week` or `month`; `null` with a limit is a lifetime cap. |
| `spent_kop` | Everything the key has spent, in kopecks. |
| `spent_period_kop` | Spent in the limit's current period, in kopecks. A call in flight counts at its hold until it is settled. |
| `limit_remaining_kop` | What is left of the limit in this period, in kopecks; `null` without a limit. |
| `spend_withheld` | `true` when the money fields are `null` because the reader may not see them; a key reading itself sees its own. |
| `period_resets_at` | When the period starts over, ISO 8601; `null` without a limit or with a lifetime cap. |
| `access` | The preset the key was minted with: `models`, `full`, `apps`, `read` or `management`; `custom` is any other set. |
| `kind` | `model_api` (the Model API), `agent` (the agent and the services) or `management` (a management key, which manages the organization's keys over `/v1/keys` and calls no model). |
| `state` | `active`, `expiring` (ends within seven days), `limit_reached` (every call is refused with `key_limit_exceeded` until the reset), `expired`, `disabled` (switched off, refused until switched on) or `revoked`. |
| `opens` | What the key's words open: `agent`, `connectors`, `models`. |
| `spends_balance` | `true` when the key spends the organization's balance and so takes a spending limit. |
| `issued_by_key_id` | The management key that minted this key over `/v1/keys`; `null` for a key minted in the console. |
| `disabled_at` | When the key was switched off, ISO 8601; `null` while it is on. |
| `holder` | Who holds the key: `kind` (`member` or `service_account`), `id` and `name`. A service account's key outlives the seat of whoever minted it. |
| `rate_limits` | `requests_per_minute` and `tokens_per_minute`, each with `limit`, `remaining` and `resets_at`; `remaining` and `resets_at` are `null` when the minute could not be read. |

## Rate limits

One key may start up to 1000 requests and use up to 10000000 tokens in a calendar minute. The ceiling is the same for every key and does not depend on the balance: it stops a looping script, and normal work does not reach it. Tokens are the prompt and the answer, less what was read from the cache, and count when the call ends: a request is let in while the minute's tokens are not used up.

Every call route answers with the minute in OpenAI's headers: `x-ratelimit-limit-requests`, `x-ratelimit-remaining-requests`, `x-ratelimit-reset-requests` and the same three for `tokens`, the reset as `12s`. `/v1/messages` also sends Anthropic's `anthropic-ratelimit-requests-*` and `anthropic-ratelimit-tokens-*` with the reset in RFC 3339. Past the ceiling the call is refused with `429` and code `key_rate_limited`, a `Retry-After` header in seconds and the minute in `error.metadata`; nothing is charged. A `429` with `upstream_rate_limited` is the model host's, not your key's.

What is left of the minute is in `rate_limits` of [`GET /v1/key`](#the-key-about-itself).

## Models

The [Models](/models) page shows every model and each host's price, without a key. From code the same catalogue comes from `GET /v1/models` in the OpenAI and OpenRouter shape. A model `id` reads `<vendor>/<model>`, as on OpenRouter, so code written for OpenRouter keeps its model string. Each entry carries:

- `context_length` and `max_output_tokens`;
- `pricing`: the price of the default host, where a call goes when you pick no host, in roubles (`currency: "RUB"`) per `unit_tokens` tokens for the prompt (`prompt`), the answer (`completion`), cache reads (`input_cache_read`) and cache writes (`input_cache_write`); a dollar host price is converted at the Bank of Russia rate given next to it: `usd_rub_rate` (roubles per dollar) and `usd_rub_rate_on` (the rate's date);
- `supported_parameters`: the request fields the model takes, `tools` among them when its hosts take tools;
- `endpoints`: the hosts serving the model right now, each with its own `pricing` of the same shape, its window, its cache kind (`cache`: `auto_prefix`, `session_header`, `explicit_breakpoints` or `none`), whether it takes tools, the wires it speaks (`wires`: `chat`, `messages`), and where it processes data (`data_region`: `ru` or `us`).

A call is billed at the price of the host that answered it, plus our 20%: one model's hosts can differ in price, as on OpenRouter. If the first host did not answer and the call went on to the next one, the next one's price applies. A US dollar price is charged in roubles at the official Central Bank of Russia rate of the day of the call. The reserve and the charge of one call use one rate. Which hosts are allowed and in what order they are tried is set by the `provider` object, see [Routing and caching](/docs/model-api-routing).

Before the call an upper estimate is held on the balance: the prompt and the output ceiling at the price of the dearest host the call may reach. After the answer the actual cost is charged and the rest of the hold is returned; a call that got no answer through a host's fault or ours costs nothing. How to read a call's cost is under [Accounting and cost](/docs/model-api-requests#accounting-and-cost).

The last entry is `auto` ([model choice](/docs/model-api-routing#model-choice-auto)); its prices read `"-1"`, because the call costs what the chosen model costs. A model outside the catalogue is refused with `404` and the code `model_not_found`; no other model stands in.

### A model's hosts and their availability

Routes in OpenRouter's shape, all without a key:

- `GET /v1/model/{id}` returns one entry of the list, with the path to its hosts in `links.details`.
- `GET /v1/models/{id}/endpoints` returns the hosts serving the model right now: the fields of the list's `endpoints`, plus `provider_name`, that host's `supported_parameters`, `supports_implicit_caching` and the share of calls the host answered, in percent: `uptime_last_5m`, `uptime_last_30m`, `uptime_last_1d`. Every attempt to the host counts, including those a move to another host then saved. Host errors count as failures (5xx, timeout, `429`, a refused key or balance), request errors and cancellations do not. A span without calls is `null`, not 100. The figures refresh every half minute and lag by up to a minute. `latency_last_30m` and `throughput_last_30m` are `null`: host speed is not measured yet. Takes `?data_region=ru`, as the list does.
- `GET /v1/providers` returns the hosts calls go to now: the name (`name`), the word `provider.only` and `provider.order` take (`slug`), links to the host's privacy policy, terms and status page (`privacy_policy_url`, `terms_of_service_url`, `status_page_url`, `null` where there is none), the country of its legal entity (`headquarters`) and of its data processing (`datacenters`).
- `GET /v1/models/count` returns `{"data": {"count": n}}`: the number of text models in the list, all of them with `?output_modalities=all`, those answering with a given output with `?output_modalities=image,video`.
- `GET /v1/benchmarks` returns model scores: the Artificial Analysis Intelligence Index (`intelligence_index`, 0 to 100) for the whole board, strongest first, and for the models we sell their id (`model_permaslug`, `null` for the rest). A score belongs to exactly that model version: a model the source has not evaluated has no row. `coding_index` and `agentic_index` are `null` for now. Text model rows have `task_type` `intelligence`. Beside them are the media arenas by task: `task_type` `text-to-image`, `image-editing`, `text-to-video`, `image-to-video`, `text-to-speech` with an `elo` field (blind human preference, higher is better) and `speech-to-text` with a `word_error_rate` field (share of misheard words, lower is better). Each arena holds the source's ten leaders and our models. The source does not evaluate embedding and rerank models. `meta` holds the date the board was checked against the source (`as_of`), the source link (`source_url`) and the citation (`citation`) to print beside the figures if you publish them.

A `max_tokens` (or `max_completion_tokens`) above the model's ceiling is cut to the ceiling; without one the model gets its ceiling. The hold on the balance is sized from this number, so a modest `max_tokens` also lets a call pass on a small balance.

## Errors

The OpenAI wire answers `{"error": {"message", "type", "code"}, "request_id"}`, the Anthropic wire answers `{"type": "error", "error": {"type", "message"}, "request_id"}`: branch on `code` on the first and on `type` on the second. `request_id` is also the `x-request-id` header and, on the OpenAI wire, the `id` of the answer: quote it when you write to support. A refusal of the key's spend limit carries `error.metadata` on the OpenAI wire under the key's own field names: `spend_limit_kop`, `spent_period_kop`, `limit_remaining_kop`, `period_resets_at`, and this call's hold `request_hold_kop`. An `insufficient_balance` refusal carries only `request_hold_kop` in `error.metadata`: the hold the balance did not cover.

The table quotes the server's default `message`. A refusal may add details of the request.

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

Do not retry a `402`: the call passes only after a top-up or a higher limit. Retry a `429 key_rate_limited` after `Retry-After` seconds, another `429` or a `5xx` after a pause.
