Partner API — дочерние ключи для ваших пользователей
Один аккаунт — дочерний ключ на каждого пользователя вашей платформы: POST/GET/PATCH/DELETE /v1/keys, лимиты расхода по дням и месяцам, лимиты запросов и одновременных запросов, Idempotency-Key, webhook баланса с повторами и подписью, сверка расходов.
Partner API — для B2B-партнёров, которые встраивают нейросети в свою платформу: один аккаунт и один баланс, а у каждого вашего пользователя — свой дочерний ключ со своим лимитом расхода, списком моделей, лимитом запросов в минуту и одновременных запросов. Ключи создаются, меняются и отзываются через API, без личного кабинета.
Управляющий ключ
Управлять ключами может только управляющий ключ. Отметьте обычный ключ как управляющий в личном кабинете: «Ключи API» → настройки ключа → «Управляющий ключ (Partner API)». Через API управляющий ключ создать или изменить нельзя. Храните его только на своём сервере. Обычный ключ на эндпоинтах управления получает 403 management_key_required.
- Управляющий ключ видит ключи только своего аккаунта; чужой ключ отвечает
404, как несуществующий. - Изменять и отзывать можно только ключи, созданные через API (
managed: true). Ключи из кабинета, подписочные и другие управляющие ключи видны только для чтения. - Все управляющие ключи аккаунта равноправны: любой из них управляет любым дочерним ключом аккаунта, а не только созданными им самим. Так управляющий ключ можно заменить, не теряя доступа к дочерним.
- Секрет ключа возвращается один раз — в ответе на создание. Список, чтение, изменение и повтор по Idempotency-Key его не возвращают.
- Вызовы управления ограничены 300 в минуту на управляющий ключ (
429 management_rate_limited). - Каждое создание, изменение и отзыв записывается в журнал аудита.
- Дочерний ключ видит в
GET /v1/keys,/v1/usageи/v1/generationsтолько себя, аGET /v1/balanceпоказывает ему не баланс аккаунта, а его остаток (см. «Баланс дочернего ключа»).
Создать ключ
| Параметр | Тип | Описание |
|---|---|---|
label | string | Название ключа, до 120 символов. |
external_id | string | Ваш id пользователя, до 128 печатных ASCII-символов. Уникален в аккаунте среди действующих ключей; отозванный ключ его освобождает. |
metadata | object | Произвольный JSON до 2 КБ, возвращается как есть. |
spend_limit | number | null | Лимит расхода ключа, ₽. null — без лимита. |
spend_limit_window | string | Окно лимита: total (по умолчанию, за всё время), daily, monthly. Окна обнуляются в 00:00 по Москве (UTC+3) — каждый день или 1-го числа. |
allowed_models | string[] | Разрешённые модели; пусто — все. |
allowed_ips | string[] | Разрешённые IP или CIDR, до 50; пусто — любые. |
rpm_limit | integer | null | Запросов в минуту для этого ключа; не больше лимита аккаунта. |
max_concurrent | integer | null | Одновременных запросов для этого ключа; не больше лимита аккаунта. |
expires_at | string | null | Срок действия: дата ISO 8601 с часовым поясом (2027-06-30T00:00:00Z) или дата, в будущем, не дальше 10 лет; null — бессрочно. После него ключ получает 401 key_expired, как ключ со сроком из кабинета. |
Неизвестное поле — ошибка 400, а не молчаливый пропуск.
curl https://plusvibeapi.ru/v1/keys \
-H "Authorization: Bearer $PLUSVIBE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: user-42-create-1" \
-d '{
"label": "Alice",
"external_id": "user_42",
"metadata": {"plan": "pro"},
"spend_limit": 500,
"spend_limit_window": "monthly",
"allowed_models": ["deepseek-v4.1-flash"],
"rpm_limit": 60,
"max_concurrent": 4,
"expires_at": "2027-06-30T00:00:00Z"
}'HTTP/1.1 201 Created
{
"object": "api_key",
"id": "cmabc123def456ghi789jkl0",
"prefix": "sk-pv-1a2b3c",
"label": "Alice",
"external_id": "user_42",
"metadata": {"plan": "pro"},
"active": true,
"management": false,
"managed": true,
"created_by_key_id": "cmmgmt000key000000000000",
"created_at": "2026-11-16T10:00:00.000Z",
"last_used_at": null,
"currency": "RUB",
"spend_limit": 500,
"spend_limit_window": "monthly",
"window_resets_at": "2026-11-30T21:00:00.000Z",
"allowed_models": ["deepseek-v4.1-flash"],
"allowed_ips": [],
"rpm_limit": 60,
"max_concurrent": 4,
"expires_at": "2027-06-30T00:00:00.000Z",
"spent": 0,
"spent_total": 0,
"remaining": 500,
"key": "sk-pv-1a2b3c…"
}Идентификаторы и секреты в примерах — условные.
Idempotency-Key
Заголовок Idempotency-Key (1–255 печатных ASCII-символов) делает создание безопасным для повтора. В течение 24 часов повтор с тем же ключом и тем же телом возвращает тот же ключ — с тем же id, 201, заголовком Idempotent-Replayed: true и "key": null: секрет второй раз не показывается. Другое тело с тем же ключом — 422 idempotency_key_reused; пока первый запрос выполняется — 409 idempotency_key_in_progress с Retry-After: 5.
Список и чтение
Ключи аккаунта, новые первыми, с лимитами и расходом. Параметры: external_id — фильтр по вашему id, active — true/false, limit — 1–100 (по умолчанию 20), after — next_after предыдущей страницы. spent — расход в текущем окне лимита (или за всё время), spent_total — за всё время, remaining — остаток лимита, window_resets_at — когда окно обнулится (null для лимита за всё время).
curl "https://plusvibeapi.ru/v1/keys?external_id=user_42" \
-H "Authorization: Bearer $PLUSVIBE_API_KEY"
# next page: ?limit=50&after=<next_after of the previous page>Один ключ в том же формате.
Изменить ключ
Те же поля, что при создании, плюс active — временно выключить и включить ключ. null снимает ограничение, пропущенное поле не меняется. Изменения действуют на следующий запрос.
curl -X PATCH https://plusvibeapi.ru/v1/keys/cmabc123def456ghi789jkl0 \
-H "Authorization: Bearer $PLUSVIBE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"spend_limit": 1000, "spend_limit_window": "daily", "max_concurrent": null, "active": true}'Отозвать ключ
Отзыв окончательный и вступает в силу на всех серверах не позже чем через 5 секунд (обычно сразу): затем запросы этим ключом получают 401. Изменения лимитов и срока действия применяются в те же 5 секунд. История ключа остаётся в /v1/usage, /v1/generations и /v1/keys/{id}/usage.
curl -X DELETE https://plusvibeapi.ru/v1/keys/cmabc123def456ghi789jkl0 \
-H "Authorization: Bearer $PLUSVIBE_API_KEY"
{"object": "api_key", "id": "cmabc123def456ghi789jkl0", "deleted": true}Расход ключа
spent — та же сумма, с которой сравнивается лимит; resets_at — когда окно обнулится.
curl https://plusvibeapi.ru/v1/keys/cmabc123def456ghi789jkl0/usage \
-H "Authorization: Bearer $PLUSVIBE_API_KEY"
{
"object": "api_key.usage",
"key_id": "cmabc123def456ghi789jkl0",
"external_id": "user_42",
"revoked": false,
"currency": "RUB",
"spend_limit": 500,
"spend_limit_window": "monthly",
"window_start": "2026-10-31T21:00:00.000Z",
"resets_at": "2026-11-30T21:00:00.000Z",
"window_resets_at": "2026-11-30T21:00:00.000Z",
"spent": 123.45,
"remaining": 376.55,
"spent_today": 10.2,
"spent_this_month": 123.45,
"spent_total": 980.1
}Лимиты
Лимиты ключа только сужают лимиты аккаунта. Запросы в минуту и одновременные запросы аккаунта зависят от баланса; rpm_limit и max_concurrent выше текущего уровня — ошибка 400 limit_above_account_tier.
| Баланс от | Запросов в минуту | Одновременных запросов |
|---|---|---|
| 0 ₽ | 300 | 10 |
| 50 ₽ | 1 100 | 50 |
| 100 ₽ | 6 600 | 300 |
| 300 ₽ | 19 800 | 900 |
| 1 000 ₽ | 44 000 | 2 000 |
Лимит расхода проверяется до отправки запроса одной атомарной операцией в базе: запрос пропускается, пока расход в окне вместе с резервами уже идущих запросов ключа меньше лимита, и резервирует оценку своей стоимости (даже если она больше остатка — небольшой остаток лимита по-прежнему можно потратить). Превышение лимита возможно только на стоимость запросов, которые уже шли в момент, когда лимит закончился. Когда остаток занят идущими запросами, ответ — 429 key_limit_in_flightс Retry-After; когда лимит израсходован — 402. Если проверить лимит не удалось, запрос получает 503 key_limit_unavailableс Retry-After — неизвестный расход не считается нулём. Запрос, допущенный до полуночи и списанный после неё, засчитывается в окно, в котором был допущен. Изменение суммы лимита, окна или повторное включение ключа пересчитывает его расход по истории.
Баланс дочернего ключа
GET /v1/balance, вызванный дочерним ключом (или любым ключом с лимитом расхода), не раскрывает баланс аккаунта. В balance приходит остаток ключа: меньшее из остатка лимита в текущем окне и доступных средств аккаунта, с флагом allowance: true, limit_window и window_resets_at. Дочерний ключ без лимита видит 0. Управляющий и обычные ключи без лимита получают привычный ответ с балансом аккаунта.
# called WITH THE SUB-KEY itself
curl https://plusvibeapi.ru/v1/balance -H "Authorization: Bearer $SUB_KEY"
{
"balance": 376.55,
"currency": "RUB",
"balance_rub": 376.55,
"allowance": true,
"spend_limit": 500,
"limit_window": "monthly",
"window_resets_at": "2026-11-30T21:00:00.000Z"
}Ошибки
Формат как у OpenAI: {"error": {"message", "type", "code", "cause", "param"}}. Ветвитесь по cause.
| HTTP | cause | Что значит |
|---|---|---|
| 400 | invalid_parameter | Неверное поле; имя поля — в param. |
| 400 | limit_above_account_tier | rpm_limit или max_concurrent выше лимита аккаунта. |
| 400 | invalid_idempotency_key | Idempotency-Key не 1–255 печатных ASCII-символов. |
| 400 | invalid_expires_at | expires_at не дата ISO 8601 с часовым поясом, в прошлом или дальше 10 лет. |
| 401 | invalid_key | Ключ неверный, отключён или отозван. |
| 401 | key_expired | Срок действия ключа (expires_at) истёк. |
| 402 | key_limit_exceeded | Лимит расхода ключа (total) исчерпан. Поднимите лимит. |
| 402 | key_window_exhausted | Дневной или месячный лимит исчерпан (или его не хватает на этот запрос); Retry-After и details.resets_at — до обнуления. |
| 503 | key_limit_unavailable | Не удалось прочитать расход ключа с лимитом; повторите после Retry-After. |
| 403 | management_key_required | Ключ не управляющий. |
| 403 | key_not_manageable | Ключ создан не через API — менять его можно только в кабинете. |
| 403 | ip_not_allowed | IP не входит в белый список управляющего ключа. |
| 403 | key_count_limit | Слишком много активных ключей, созданных через API; отзовите лишние. |
| 404 | key_not_found | Ключа нет в этом аккаунте. |
| 409 | external_id_conflict | external_id уже занят действующим ключом. |
| 409 | idempotency_key_in_progress | Первый запрос с этим Idempotency-Key ещё выполняется; повторите через 5 с. |
| 409 | key_changed | Ключ изменился во время запроса; перечитайте и повторите. |
| 422 | idempotency_key_reused | Idempotency-Key уже использован с другим телом. |
| 429 | management_rate_limited | Больше 300 вызовов управления в минуту. |
| 429 | key_limit_in_flight | Остаток лимита занят выполняющимися запросами ключа; повторите после Retry-After. |
| 429 | key_rpm_limited | Превышен rpm_limit ключа; ждите Retry-After. |
| 429 | key_concurrency_limited | Достигнут max_concurrent ключа; дождитесь завершения запросов (Retry-After: 1). |
| 429 | key_rate_limited | Превышен лимит запросов в минуту аккаунта. |
| 429 | account_concurrency_limited | Достигнут лимит одновременных запросов аккаунта. |
Webhook баланса
Адрес и порог для событий аккаунта. url: null отключает доставку. В ответе — signing_secret для проверки подписи.
curl -X PUT https://plusvibeapi.ru/v1/webhooks/balance \
-H "Authorization: Bearer $PLUSVIBE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://partner.example.com/hooks/billing", "threshold": 1000}'
{
"object": "webhook.balance",
"url": "https://partner.example.com/hooks/billing",
"threshold": 1000,
"currency": "RUB",
"events": ["balance.low", "key.limit_reached"],
"signing_secret": "…"
}События
balance.low— баланс опустился ниже порога; не чаще раза в час.key.limit_reached— лимит ключа исчерпан; один раз на ключ за окно лимита. Без настроенного URL событие не создаётся, а URL, заданный позже, получает только новые события — старые не досылаются.
{
"event": "balance.low",
"balance": 812.5,
"threshold": 1000,
"currency": "RUB",
"balance_rub": 812.5,
"threshold_rub": 1000,
"created_at": "2026-11-16T10:00:00.000Z"
}Доставка и подпись
POST с JSON по стандарту Standard Webhooks: заголовки webhook-id, webhook-timestamp, webhook-signature и x-pv-event. Подпись — v1, + base64(HMAC-SHA256(секрет, id.timestamp.body)). Ответ 2xx — доставлено. Иначе повторяем: сразу, затем через 1, 2, 4, 8, 16 и 32 минуты — 7 попыток за час. webhook-id одинаков во всех попытках — по нему удобно отбрасывать дубли.
import crypto from 'node:crypto';
// secret: "signing_secret" from GET /v1/webhooks/balance
export function verify(secret, headers, rawBody) {
const id = headers['webhook-id'];
const ts = headers['webhook-timestamp'];
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // replay window
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
const expected = crypto.createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest('base64');
return headers['webhook-signature'].split(' ').some((sig) => {
const [, value] = sig.split(',');
return value && value.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(value), Buffer.from(expected));
});
}Сверка
Для сверки по пользователю передайте api_key_id в /v1/generations (постранично, page и limit до 100) или в /v1/usage (последние события и итог). Суммы — в валюте аккаунта.
# every request of one sub-key, newest first (page / limit ≤ 100, dateFrom / dateTo ISO)
curl "https://plusvibeapi.ru/v1/generations?api_key_id=cmabc123def456ghi789jkl0&page=1&limit=100" \
-H "Authorization: Bearer $PLUSVIBE_API_KEY"
# the same key's recent events with a summary (limit ≤ 200, from / to ISO)
curl "https://plusvibeapi.ru/v1/usage?api_key_id=cmabc123def456ghi789jkl0&from=2026-11-01T00:00:00Z" \
-H "Authorization: Bearer $PLUSVIBE_API_KEY"