API моделей

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

Это не API агентов: там model называет агента организации с его инструментами и подключениями, а здесь модель, которая отвечает на ваш промпт как есть.

От регистрации до первого ответа нужно пополнить баланс, создать ключ в консоли и вызвать модель. Все шаги по порядку на странице «Быстрый старт». Баланс пополняется в консоли разработчика; комиссии за пополнение нет, а вызов стоит столько, сколько берёт хост, который на него ответил, плюс наши 20%.

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

Адреса

КлиентАдресМаршрут
OpenAI SDK, curl, клиенты OpenRouterhttps://api.samreshuuu.ru/v1 (base_url)POST /v1/chat/completions
Anthropic SDKhttps://api.samreshuuu.ru (base_url, без /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
Список моделей, одна модель, хосты модели, хосты, число моделей, оценки моделей (без ключа)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
Картинки (OpenAI SDK images.generate / images.edit)https://api.samreshuuu.ru/v1POST /v1/images/generations, POST /v1/images/edits
Ролики (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
Расшифровка речи (OpenAI SDK audio.transcriptions.create)https://api.samreshuuu.ru/v1POST /v1/audio/transcriptions
Эмбеддинги (OpenAI SDK embeddings.create), список моделей эмбеддингов (без ключа)https://api.samreshuuu.ru/v1POST /v1/embeddings, GET /v1/embeddings/models
Переранжирование (в OpenAI SDK вызова нет)https://api.samreshuuu.ru/v1POST /v1/rerank
Синтез речи (OpenAI SDK audio.speech.create)https://api.samreshuuu.ru/v1POST /v1/audio/speech

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

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

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

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

МетодМаршрутScope ключаСчитается в минутном лимите
GET/v1/modelsбез ключанет
POST/v1/chat/completionsmodels:writeда
POST/v1/messagesmodels:writeда
POST/v1/responsesmodels:writeда
POST/v1/messages/count_tokensmodels:readда
POST/v1/images/generationsmodels:writeда
POST/v1/images/editsmodels:writeда
POST/v1/videosmodels:writeда
POST/v1/audio/transcriptionsmodels:writeда
POST/v1/audio/speechmodels:writeда
POST/v1/embeddingsmodels:writeда
POST/v1/rerankmodels:writeда
GET/v1/videos/{video_id}models:readнет
GET/v1/videos/{video_id}/contentmodels:readнет
GET/v1/generationmodels:readнет
GET/v1/activitymodels:readнет
GET/v1/keymodels:readнет
GET/v1/creditsmodels:readнет
GET/v1/keyskeys:manageнет
POST/v1/keyskeys: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_withheldtrue, если денежные поля равны null, потому что читателю их не показывают; ключ о себе видит свои.
period_resets_atКогда период начнётся заново, ISO 8601; null без лимита или при лимите на весь срок.
accessВариант доступа, с которым выпущен ключ: models, full, apps, read или management; custom, если набор другой.
kindmodel_api (API моделей), agent (агент и сервисы) или management (ключ управления: управляет ключами организации через /v1/keys и модели не вызывает).
stateactive, expiring (срок кончается в ближайшие семь дней), limit_reached (каждый вызов получает key_limit_exceeded до сброса), expired, disabled (ключ отключён и не принимается, пока его не включат) или revoked.
opensЧто открывают слова ключа: agent, connectors, models.
spends_balancetrue, если ключ тратит баланс организации и поэтому принимает лимит трат.
issued_by_key_idКлюч управления, выпустивший этот ключ через /v1/keys; null у ключа из консоли.
disabled_atКогда ключ отключён, ISO 8601; null, пока он включён.
holderКто держит ключ: kind (member или service_account), id и name. Ключ сервисного аккаунта переживает место того, кто его выпустил.
rate_limitsrequests_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.

Модели

Все модели и цены каждого хоста показывает страница «Модели», без ключа. Из кода тот же каталог отдаёт 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, см. «Маршрутизация и кэш».

Перед вызовом на балансе резервируется верхняя оценка: промпт и потолок ответа по цене самого дорогого хоста, к которому может уйти вызов. После ответа списывается фактическая стоимость, остаток резерва возвращается; вызов, который не дал ответа по вине хоста или нашей, не стоит ничего. Как прочитать стоимость вызова, описано в разделе «Учёт и стоимость».

Последняя запись называет 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 сервера на английском. Отказ может уточнять детали запроса.

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

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

Частые вопросы

Чем API моделей отличается от API агентов?

API моделей отдаёт ответ самой модели по вашему промпту и списывает его стоимость с баланса организации. API агентов (POST /v1/chat/completions на samreshuuu.ru) зовёт агента организации с его инструментами и подключениями, и model там называет агента, а не модель.

Какой адрес указать в SDK?

Для OpenAI SDK base URL https://api.samreshuuu.ru/v1. Для Anthropic SDK и Claude Code (ANTHROPIC_BASE_URL) адрес без пути, https://api.samreshuuu.ru: они сами дописывают /v1/messages.

Какой ключ нужен?

Ключ API моделей sk-org-… со scope models:write. Он выпускается в консоли разработчика (https://platform.samreshuuu.ru), раздел «Ключи API», с доступом «API моделей». Ключ агента из того же раздела моделей не вызывает, вариант «Полный доступ» тоже. Список моделей, их хосты и число моделей открываются без ключа.

Сколько стоит вызов?

Вызов стоит столько, сколько берёт хост, который на него ответил, плюс наши 20%: это все наши деньги, комиссии за пополнение нет. Цены всех моделей и хостов на странице samreshuuu.ru/models уже с нашими 20%. Из кода GET /v1/models отдаёт цену каждого хоста в endpoints[].pricing, а pricing модели называет цену хоста по умолчанию. Каждый ответ называет свою точную стоимость в usage.cost (провод OpenAI). Перед вызовом на балансе резервируется верхняя оценка по самому дорогому хосту, к которому может уйти вызов, после ответа списывается фактическая стоимость, остаток резерва возвращается.

Была ли страница полезна?