Partner API

Автоматизация ключей, групп, лимитов, истории запросов и async-результатов с учётом в десятичных строках.

Partner API предназначен для банков, ботов, панелей перепродавцов, внутренних систем выдачи ресурсов и других доверенных межсерверных интеграций. Версия 10.5.0 — первый машинный контракт для банковской интеграции.

Базовый URL

https://p-api.model-gate.com

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

Authorization: Bearer mg_partner_...

Каждый ответ — JSON, включая 404, 405, 429 и 500, и содержит X-Request-ID. Ответы используют Cache-Control: no-store; хост Partner не использует браузерные PHP-сеансы. Все внешние временные отметки — UTC RFC3339 (YYYY-MM-DDTHH:MM:SSZ).

Все операции POST, PATCH и DELETE требуют уникального заголовка Idempotency-Key. Model Gate хранит зашифрованный результат 7 дней, чтобы повтор того же запроса вернул первоначальный результат без нового изменения. Использование ключа для другого метода, пути или тела возвращает HTTP 409.

Запросы Partner защищены поминутным ограничением аккаунта PARTNER_API_RATE_LIMIT_PER_MINUTE (по умолчанию 600). Ответы содержат X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset; HTTP 429 также включает Retry-After.

Создайте или обновите ключ Partner API в профиле Model Gate. Полный Bearer-токен показывается один раз при создании или обновлении; Model Gate хранит только его SHA-256 и отображаемый префикс. Сразу сохраните токен в серверном менеджере секретов; при потере перевыпустите его.

Профиль содержит отдельный API IP allowlist. Если список не пуст, запросы Partner API должны исходить с разрешённого точного IPv4/IPv6 или префикса CIDR. Организационные правила API Business применяются дополнительно к личным. Источник, отклонённый любым действующим списком, получает HTTP 403 с error.type = ip_not_allowed.

В Business ключ Partner API доступен только подтверждённому владельцу организации. Пользователи-сотрудники и делегированное назначение ключей Business управляются в веб-панели, где можно проверить групповые права выполнения. Поэтому созданные Partner ключи Business используют владельца и для списания, и как пользователя ключа. Переданный group_id должен указывать активную группу аккаунта; неизвестная или замороженная группа отклоняется с HTTP 422, а не приводит к незаметному созданию ключа без группы.

Десятичные значения

Денежные поля и поля использования всегда представлены строками JSON:

{
  "spend_limit": "100.0000000000",
  "usage": "12.3456789000",
  "remaining": "87.6543211000",
  "usage_price_multiplier": "0.900000"
}

Используйте десятичную арифметику произвольной точности. Никогда не преобразуйте эти значения во float.

Возможности

Создавать, перечислять, обновлять, перевыпускать, замораживать, размораживать и удалять API-ключи.
Настраивать расчёт суммы использования каждого ключа.
Создавать группы и управлять ими.
Перемещать ключи между группами.
Читать использование ключей и групп.
Читать завершённую историю запросов ключа по времени завершения, страницами по 1–100 строк, с детализацией токенов и цены. Подробная история хранится API_REQUESTS_HOT_RETENTION_DAYS (по умолчанию 7 дней); для длительной финансовой сверки используется журнал транзакций баланса.
Читать текущий баланс аккаунта и его транзакции с курсорной навигацией.
Читать аудит управляющих действий Partner с курсорной навигацией.
Опрашивать результаты асинхронного инференса.

Полные примеры запросов и ответов см. в разделе Все эндпоинты Partner API.

Недавние записи истории содержат principal_user_id, если пользователь ключа ещё существует, отдельно от владельца списания компании.

Машиночитаемый контракт

Контракт OpenAPI 3.1 входит в каждый выпуск как resources/contracts/partner-api.openapi.yaml. Используйте его вместе с этими страницами Partner API как контракт банковской интеграции. Неизвестные JSON-поля и параметры query отклоняются, а не игнорируются.