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; no plan is needed for that.

This is not the Agent API: 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 page. The balance is topped up in the developer console; there is no top-up fee, and a call costs what the host that answered it charges, plus our 20%.

The Model API pages:

Addresses

ClientAddressRoute
OpenAI SDK, curl, OpenRouter clientshttps://api.samreshuuu.ru/v1 (base_url)POST /v1/chat/completions
Anthropic SDKhttps://api.samreshuuu.ru (base_url, without /v1)POST /v1/messages
Claude CodeANTHROPIC_BASE_URL=https://api.samreshuuu.ruPOST /v1/messages
Codex CLI, OpenAI Agents SDK, OpenAI SDK responses.createhttps://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/v1GET /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/v1POST /v1/images/generations, POST /v1/images/edits
Videos (OpenAI SDK videos.create / videos.retrieve / videos.download_content)https://api.samreshuuu.ru/v1POST /v1/videos, GET /v1/videos/{id}, GET /v1/videos/{id}/content
Audio transcriptions (OpenAI SDK audio.transcriptions.create)https://api.samreshuuu.ru/v1POST /v1/audio/transcriptions
Embeddings (OpenAI SDK embeddings.create), embedding model list (no key)https://api.samreshuuu.ru/v1POST /v1/embeddings, GET /v1/embeddings/models
Rerank (no OpenAI SDK call)https://api.samreshuuu.ru/v1POST /v1/rerank
Text to speech (OpenAI SDK audio.speech.create)https://api.samreshuuu.ru/v1POST /v1/audio/speech

Authentication

An organization key sk-org-… (see 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, 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:

MethodRouteKey scopeCounts toward the per-minute limit
GET/v1/modelsno keyno
POST/v1/chat/completionsmodels:writeyes
POST/v1/messagesmodels:writeyes
POST/v1/responsesmodels:writeyes
POST/v1/messages/count_tokensmodels:readyes
POST/v1/images/generationsmodels:writeyes
POST/v1/images/editsmodels:writeyes
POST/v1/videosmodels:writeyes
POST/v1/audio/transcriptionsmodels:writeyes
POST/v1/audio/speechmodels:writeyes
POST/v1/embeddingsmodels:writeyes
POST/v1/rerankmodels:writeyes
GET/v1/videos/{video_id}models:readno
GET/v1/videos/{video_id}/contentmodels:readno
GET/v1/generationmodels:readno
GET/v1/activitymodels:readno
GET/v1/keymodels:readno
GET/v1/creditsmodels:readno
GET/v1/keyskeys:manageno
POST/v1/keyskeys:manageno
GET/v1/keys/{key_id}keys:manageno
PATCH/v1/keys/{key_id}keys:manageno
DELETE/v1/keys/{key_id}keys:manageno

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:

FieldDescription
idThe key's id.
nameThe key's name, as set in the console.
key_maskedThe key as a list shows it, sk-org-…abcd; the full key is shown once, when it is minted.
scopesThe key's words, resource:action each.
created_atWhen the key was minted, ISO 8601.
expires_atWhen the key stops working, ISO 8601; null is no end date.
last_used_atWhen the key was last admitted, ISO 8601, stamped at most once in a few minutes; null if never.
spend_limit_kopThe key's spending limit, in kopecks; null is no limit.
spend_limit_resetWhen the limit starts over: day, week or month; null with a limit is a lifetime cap.
spent_kopEverything the key has spent, in kopecks.
spent_period_kopSpent in the limit's current period, in kopecks. A call in flight counts at its hold until it is settled.
limit_remaining_kopWhat is left of the limit in this period, in kopecks; null without a limit.
spend_withheldtrue when the money fields are null because the reader may not see them; a key reading itself sees its own.
period_resets_atWhen the period starts over, ISO 8601; null without a limit or with a lifetime cap.
accessThe preset the key was minted with: models, full, apps, read or management; custom is any other set.
kindmodel_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).
stateactive, 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.
opensWhat the key's words open: agent, connectors, models.
spends_balancetrue when the key spends the organization's balance and so takes a spending limit.
issued_by_key_idThe management key that minted this key over /v1/keys; null for a key minted in the console.
disabled_atWhen the key was switched off, ISO 8601; null while it is on.
holderWho holds the key: kind (member or service_account), id and name. A service account's key outlives the seat of whoever minted it.
rate_limitsrequests_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.

Models

The 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.

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.

The last entry is auto (model choice); 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.

HTTPtypeCodemessageRetry
400invalid_request_errorcontent_blockedThe model host's safety system refused the prompt or an input image.no
400invalid_request_errorcontext_length_exceededThe prompt and max_tokens exceed the model's window.no
400invalid_request_errorinvalid_bodyThe request body must be a JSON object.no
400invalid_request_errorinvalid_jsonThe request body is not valid JSON.no
400invalid_request_errorinvalid_modelsmodels must be a short list of model ids.no
400invalid_request_errorinvalid_parameterA request field has a wrong shape.no
400invalid_request_errorinvalid_provider_preferencesprovider must be an object of OpenRouter's provider preferences.no
400invalid_request_errorlimit_not_spendingThis key spends no balance, so a spending limit has nothing to limit.no
400invalid_request_errorno_auto_modelNo model meets the request for auto.no
400invalid_request_errorprice_above_maxEvery eligible host of the model is priced above provider.max_price.no
400invalid_request_errorserver_toolAnthropic server tools run on Anthropic's side and are not served here.no
400invalid_request_errorunknown_providerThe provider object names a host this API does not route to.no
400invalid_request_errorunsupported_blockThe request has a content block this API does not support.no
400invalid_request_errorunsupported_parameterThe request uses a field this API does not support.no
400invalid_request_errorunsupported_pluginOnly the auto-router plugin is supported.no
400invalid_request_errorunsupported_provider_preferenceThe provider object has a preference this API does not honour.no
400invalid_request_errorupstream_bad_requestThe model host refused the request.no
401authentication_errorambiguous_api_keyThe request carries two different keys in 'Authorization' and 'x-api-key'. Send one.no
401authentication_errorinvalid_api_keyThe API key is unknown, revoked or expired.no
401authentication_errormissing_api_keyPass an organization API key as 'Authorization: Bearer sk-org-…' or 'x-api-key'.no
402billing_errorinsufficient_balanceThe 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
402billing_errorkey_limit_exceededThis API key has reached its spending limit. Raise the limit or use another key.no
402billing_errorspend_cap_reachedThe organization's monthly spend cap is reached. A billing admin can raise it in the console; a top-up does not lift it.no
403permission_errorapi_keys_not_enabledThe developer console is not enabled for this organization.no
403permission_errorbalance_not_offeredThe organization balance is not open for the model API.no
403permission_errorinsufficient_scopeThis API key lacks the scope of this route. Create a key with it.no
404not_found_errorgeneration_not_foundNo call with this id belongs to this organization in the last 30 days.no
404not_found_errorkey_not_foundNo live key with this id that a management key may manage belongs to this organization.no
404not_found_errormodel_not_foundThe model does not exist. GET /v1/models lists the models this API sells.no
404not_found_errorno_eligible_hostNo host of the model meets the request's provider preferences.no
404not_found_errornot_foundThis is not a route of this API.no
404not_found_errorvideo_not_foundNo video with this id belongs to this organization.no
405invalid_request_errormethod_not_allowedThis route does not take this method.no
409invalid_request_errorvideo_not_readyThe video is not completed. Poll GET /v1/videos/{id} until its status is completed.yes
410not_found_errorvideo_expiredThe video's content is past its expires_at and is no longer kept.no
413request_too_largerequest_too_largeThe request body is larger than this API reads.no
429rate_limit_errorkey_rate_limitedThis API key reached its requests or tokens per minute. Retry after Retry-After seconds.yes
429rate_limit_errorupstream_rate_limitedThe model host is busy. Retry the request later.yes
500api_errorinternal_errorThe request failed on our side. Retry it later.yes
502api_errorupstream_reply_unreadableThe model host answered something this API cannot read.yes
502api_errorupstream_stream_cutThe model host broke off the answer.yes
502api_errorupstream_unavailableNo model host answered. Retry the request later.yes
503overloaded_errorbalance_unavailableThe organization balance could not be read now. Retry the request later.yes
503overloaded_errormodel_not_readyThis model is not served on this deployment now: its vendor account is not configured.no
503overloaded_errormodel_unavailableThe model has no host available right now. Retry the request later.yes
503overloaded_errorupstream_overloadedThe model host is busy. Retry the request later.yes
504timeout_errorupstream_timeoutThe 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.

Frequently asked questions

How is the Model API different from the Agent API?

The Model API returns the model's own answer to your prompt and charges its cost to the organization balance. The Agent API (POST /v1/chat/completions on samreshuuu.ru) calls an agent of your organization with its tools and connections, and model there names the agent, not a model.

Which address goes into the SDK?

For the OpenAI SDK the base URL is https://api.samreshuuu.ru/v1. For the Anthropic SDK and Claude Code (ANTHROPIC_BASE_URL) use the address without a path, https://api.samreshuuu.ru: they append /v1/messages themselves.

Which key do I need?

A Model API key sk-org-… with the models:write scope. It is issued in the developer console (https://platform.samreshuuu.ru), under API keys, with the Model API access. An agent key from the same section calls no model, the Full access option included. The model list, its hosts and the model count open without a key.

What does a call cost?

A call costs what the host that answered it charges, plus our 20%: that is all we earn, there is no top-up fee. The prices of every model and host on samreshuuu.ru/models already include our 20%. From code GET /v1/models returns each host's price in endpoints[].pricing, and the model's pricing names the price of its default host. Every answer states its exact cost in usage.cost (OpenAI wire). Before the call an upper estimate is held on the balance at the dearest host the call may reach; after the answer the actual cost is charged and the rest of the hold is returned.

Was this page helpful?