API моделей
API моделей отдаёт модели нашего каталога по ключу организации. Запросы принимаются в трёх формах: OpenAI Chat Completions, OpenAI Responses и Anthropic Messages, поэтому подойдут OpenAI SDK, OpenAI Agents SDK, Anthropic SDK, Claude Code и Codex CLI, поменяйте только адрес и ключ. Вызовы оплачиваются с баланса организации, тариф для этого не нужен.
Это не API агентов: там model называет агента организации с его инструментами и подключениями, а здесь модель, которая отвечает на ваш промпт как есть.
От регистрации до первого ответа нужно пополнить баланс, создать ключ в консоли и вызвать модель. Все шаги по порядку на странице «Быстрый старт». Баланс пополняется в консоли разработчика; комиссии за пополнение нет, а вызов стоит столько, сколько берёт хост, который на него ответил, плюс наши 20%.
Страницы API моделей:
- Запросы и потоковый ответ: поля Chat Completions, инструменты,
response_format,reasoning, Responses API и Codex CLI, поток, отмена и как прочитать стоимость вызова. - Маршрутизация и кэш: выбор хостов в
provider, запасные модели,auto, данные в РФ, кэш промпта,plugins. - Anthropic SDK и Claude Code: провод Messages,
anthropic-beta, подсчёт токенов. - Картинки, ролики и речь: картинки, ролики, расшифровка и синтез речи, эмбеддинги и переранжирование.
Адреса
| Клиент | Адрес | Маршрут |
|---|---|---|
| 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-… (см. Аутентификацию) передаётся в 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/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.
Модели
Все модели и цены каждого хоста показывает страница «Модели», без ключа. Из кода тот же каталог отдаёт 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_typetext-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 после паузы.
Частые вопросы
Чем 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). Перед вызовом на балансе резервируется верхняя оценка по самому дорогому хосту, к которому может уйти вызов, после ответа списывается фактическая стоимость, остаток резерва возвращается.