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 показывает ему не баланс аккаунта, а его остаток (см. «Баланс дочернего ключа»).

Создать ключ

POST/v1/keys
ПараметрТипОписание
labelstringНазвание ключа, до 120 символов.
external_idstringВаш id пользователя, до 128 печатных ASCII-символов. Уникален в аккаунте среди действующих ключей; отозванный ключ его освобождает.
metadataobjectПроизвольный JSON до 2 КБ, возвращается как есть.
spend_limitnumber | nullЛимит расхода ключа, ₽. null — без лимита.
spend_limit_windowstringОкно лимита: total (по умолчанию, за всё время), daily, monthly. Окна обнуляются в 00:00 по Москве (UTC+3) — каждый день или 1-го числа.
allowed_modelsstring[]Разрешённые модели; пусто — все.
allowed_ipsstring[]Разрешённые IP или CIDR, до 50; пусто — любые.
rpm_limitinteger | nullЗапросов в минуту для этого ключа; не больше лимита аккаунта.
max_concurrentinteger | nullОдновременных запросов для этого ключа; не больше лимита аккаунта.
expires_atstring | 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.

Список и чтение

GET/v1/keys

Ключи аккаунта, новые первыми, с лимитами и расходом. Параметры: 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>
GET/v1/keys/{id}

Один ключ в том же формате.

Изменить ключ

PATCH/v1/keys/{id}

Те же поля, что при создании, плюс 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}'

Отозвать ключ

DELETE/v1/keys/{id}

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

Расход ключа

GET/v1/keys/{id}/usage

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 ₽30010
50 ₽1 10050
100 ₽6 600300
300 ₽19 800900
1 000 ₽44 0002 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.

HTTPcauseЧто значит
400invalid_parameterНеверное поле; имя поля — в param.
400limit_above_account_tierrpm_limit или max_concurrent выше лимита аккаунта.
400invalid_idempotency_keyIdempotency-Key не 1–255 печатных ASCII-символов.
400invalid_expires_atexpires_at не дата ISO 8601 с часовым поясом, в прошлом или дальше 10 лет.
401invalid_keyКлюч неверный, отключён или отозван.
401key_expiredСрок действия ключа (expires_at) истёк.
402key_limit_exceededЛимит расхода ключа (total) исчерпан. Поднимите лимит.
402key_window_exhaustedДневной или месячный лимит исчерпан (или его не хватает на этот запрос); Retry-After и details.resets_at — до обнуления.
503key_limit_unavailableНе удалось прочитать расход ключа с лимитом; повторите после Retry-After.
403management_key_requiredКлюч не управляющий.
403key_not_manageableКлюч создан не через API — менять его можно только в кабинете.
403ip_not_allowedIP не входит в белый список управляющего ключа.
403key_count_limitСлишком много активных ключей, созданных через API; отзовите лишние.
404key_not_foundКлюча нет в этом аккаунте.
409external_id_conflictexternal_id уже занят действующим ключом.
409idempotency_key_in_progressПервый запрос с этим Idempotency-Key ещё выполняется; повторите через 5 с.
409key_changedКлюч изменился во время запроса; перечитайте и повторите.
422idempotency_key_reusedIdempotency-Key уже использован с другим телом.
429management_rate_limitedБольше 300 вызовов управления в минуту.
429key_limit_in_flightОстаток лимита занят выполняющимися запросами ключа; повторите после Retry-After.
429key_rpm_limitedПревышен rpm_limit ключа; ждите Retry-After.
429key_concurrency_limitedДостигнут max_concurrent ключа; дождитесь завершения запросов (Retry-After: 1).
429key_rate_limitedПревышен лимит запросов в минуту аккаунта.
429account_concurrency_limitedДостигнут лимит одновременных запросов аккаунта.

Webhook баланса

GET/v1/webhooks/balance
PUT/v1/webhooks/balance

Адрес и порог для событий аккаунта. 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"
Partner API PlusVibe — создание ключей и лимиты по API | PlusVibeAPI