Эндпоинты Partner API

Базовый URL:

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

Все запросы требуют:

Authorization: Bearer mg_partner_...
Accept: application/json

Все денежные значения и лимиты передаются десятичными строками JSON. Не преобразуйте их в двоичные числа с плавающей точкой.

Общие правила банковской интеграции

Все внешние временные отметки — UTC RFC3339. Эндпоинты коллекций используют limit (1–100) и непрозрачный cursor; не разбирайте и не создавайте содержимое курсоров самостоятельно. Запросы POST, PATCH и DELETE требуют Idempotency-Key; после тайм-аута повторяйте ту же операцию с тем же ключом. Записи идемпотентности хранятся 7 дней. Ответы содержат X-Request-ID и Cache-Control: no-store; все ошибки — JSON. При ограничении частоты возвращается HTTP 429 с Retry-After и заголовками X-RateLimit-*. Неизвестные поля тела/query отклоняются.

Машиночитаемый контракт OpenAPI 3.1 поставляется в resources/contracts/partner-api.openapi.yaml.

Создать API-ключ

Запрос

curl -X POST https://p-api.model-gate.com/api/v1/partner/keys \
  -H "Authorization: Bearer mg_partner_..." \
  -H "Idempotency-Key: operation-unique-001" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Telegram user 123",
    "group_id": "GROUP_PUBLIC_ID",
    "rpm_limit": 30,
    "concurrency_limit": 2,
    "spend_limit": "20.0000000000",
    "usage_price_basis": "official_price",
    "usage_price_multiplier": "0.900000"
  }'

Ответ — 201

{
  "data": {
    "public_id": "KEY_PUBLIC_ID",
    "group_id": "GROUP_PUBLIC_ID",
    "name": "Telegram user 123",
    "key_prefix": "mg_live_ab12",
    "key": "mg_live_ab12...",
    "status": "active",
    "rpm_limit": 30,
    "concurrency_limit": 2,
    "spend_limit": "20.0000000000",
    "usage": "0.0000000000",
    "total_spent": "0.0000000000",
    "usage_price_basis": "official_price",
    "usage_price_multiplier": "0.900000",
    "effective_usage_price_basis": "official_price",
    "effective_usage_price_multiplier": "0.900000"
  }
}

Полное значение key возвращается только после создания или перевыпуска.

Получить список API-ключей

Запрос

curl https://p-api.model-gate.com/api/v1/partner/keys \
  -H "Authorization: Bearer mg_partner_..."

Ответ — 200

{
  "data": [
    {
      "public_id": "KEY_PUBLIC_ID",
      "group_id": "GROUP_PUBLIC_ID",
      "name": "Telegram user 123",
      "status": "active",
      "spend_limit": "20.0000000000",
      "usage": "3.2500000000",
      "total_spent": "1.1400000000"
    }
  ]
}

Список упорядочен от новых к старым и использует непрозрачный курсор. Передайте limit=1..100; если meta.has_more истинно, используйте meta.next_cursor как следующий cursor.

Получить один API-ключ

Запрос

curl https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID \
  -H "Authorization: Bearer mg_partner_..."

Ответ — 200

{
  "data": {
    "public_id": "KEY_PUBLIC_ID",
    "group_id": "GROUP_PUBLIC_ID",
    "name": "Telegram user 123",
    "status": "active",
    "rpm_limit": 30,
    "concurrency_limit": 2,
    "spend_limit": "20.0000000000",
    "usage": "3.2500000000",
    "total_spent": "1.1400000000",
    "effective_usage_price_basis": "official_price",
    "effective_usage_price_multiplier": "0.900000"
  }
}

Обновить API-ключ

PATCH заменяет только поддерживаемые изменяемые значения. Для удаления ключа из группы передайте пустой group_id. Для наследования настроек расчёта передайте null для базы и коэффициента уровня ключа.

Запрос

curl -X PATCH https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID \
  -H "Authorization: Bearer mg_partner_..." \
  -H "Idempotency-Key: operation-unique-001" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated user name",
    "group_id": "GROUP_PUBLIC_ID",
    "rpm_limit": 60,
    "concurrency_limit": 4,
    "spend_limit": "40.0000000000",
    "usage_price_basis": null,
    "usage_price_multiplier": null
  }'

Ответ — 200

{
  "data": {
    "public_id": "KEY_PUBLIC_ID",
    "spend_limit": "40.0000000000",
    "usage": "3.2500000000",
    "effective_usage_price_basis": "user_price",
    "effective_usage_price_multiplier": "1.000000"
  }
}

Удалить API-ключ

Запрос

curl -X DELETE https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID \
  -H "Authorization: Bearer mg_partner_..." \
  -H "Idempotency-Key: operation-unique-001" \

Ответ — 200

{"data":{"deleted":true}}

Заморозить и разморозить ключ

Запрос заморозки

curl -X POST https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID/freeze \
  -H "Authorization: Bearer mg_partner_..." \
  -H "Idempotency-Key: operation-unique-001" \

Ответ заморозки

{"data":{"public_id":"KEY_PUBLIC_ID","status":"frozen"}}

Запрос разморозки

curl -X POST https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID/unfreeze \
  -H "Authorization: Bearer mg_partner_..." \
  -H "Idempotency-Key: operation-unique-001" \

Ответ разморозки

{"data":{"public_id":"KEY_PUBLIC_ID","status":"active"}}

Разморозка требует подтверждённого email владельца.

Перевыпустить ключ

Запрос

curl -X POST https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID/rotate \
  -H "Authorization: Bearer mg_partner_..." \
  -H "Idempotency-Key: operation-unique-001" \

Ответ — 200

{
  "data": {
    "public_id": "KEY_PUBLIC_ID",
    "status": "active",
    "key_prefix": "mg_live_cd34",
    "key": "mg_live_cd34..."
  }
}

Сбросить использование ключа

Запрос

curl -X POST https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID/reset-usage \
  -H "Authorization: Bearer mg_partner_..." \
  -H "Idempotency-Key: operation-unique-001" \

Ответ — 200

{
  "data": {
    "public_id": "KEY_PUBLIC_ID",
    "usage": "0.0000000000",
    "total_spent": "1.1400000000"
  }
}

Сброс использования не меняет расходы за весь период или баланс аккаунта.

Получить использование ключа

Запрос

curl https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID/usage \
  -H "Authorization: Bearer mg_partner_..."

Ответ — 200

{
  "data": {
    "key_id": "KEY_PUBLIC_ID",
    "usage": "3.2500000000",
    "total_spent": "1.1400000000"
  }
}

Получить лимит расходов и оставшуюся квоту

Запрос

curl https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID/spent-limit \
  -H "Authorization: Bearer mg_partner_..."

Ответ — 200

{
  "data": {
    "key_id": "KEY_PUBLIC_ID",
    "spend_limit": "20.0000000000",
    "usage": "3.2500000000",
    "remaining": "16.7500000000"
  }
}

Нулевой spend_limit означает отсутствие лимита, а remaining равно null.

Получить последние запросы ключа

Подробная история — данные оперативного хранения с периодом API_REQUESTS_HOT_RETENTION_DAYS (по умолчанию 7 дней). Метаданные ответа сообщают действующее окно хранения. Для более длительной финансовой сверки используйте транзакции баланса.

limit необязателен, по умолчанию равен 10 и должен быть целым от 1 до 100. Завершённые запросы упорядочены по finished_at от новых к старым. Если meta.has_more равно true, передайте meta.next_cursor как непрозрачный параметр query before для следующей более старой страницы. Не разбирайте и не создавайте курсоры самостоятельно.

При наличии снимка тарифов ответ содержит сохранённые пользовательские и официальные цены за миллион токенов. pricing_snapshot.usage_price выводится из сохранённых базы, коэффициента и исторических тарифов, чтобы расчёт лимита оставался объяснимым после изменения цен. Старые запросы без снимка возвращают pricing_snapshot.available: false; сегодняшние цены не подставляются. Claude/OpenAI-совместимые пакетные запросы помечаются request_mode: "batch" и включают протокол, ID пакетного задания, custom_id и сохранённый коэффициент цены пакета.

Задержки используют стабильные имена Business/Partner: gateway_overhead_ms, upstream_first_token_ms и e2e_first_token_ms. E2E-время первого токена измеряется от начала запроса Model Gate до первого настоящего токена содержимого и не включает клиентские сеть/TLS. Partner API выдаёт только явное имя e2e_first_token_ms; внутренняя колонка хранения остаётся api_requests.first_token_ms.

Запрос

curl "https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID/requests?limit=10" \
  -H "Authorization: Bearer mg_partner_..."

Ответ — 200

{
  "data": [
    {
      "request_id": "01KZ...",
      "key_id": "KEY_PUBLIC_ID",
      "group_id": "GROUP_PUBLIC_ID",
      "model": "claude-opus-4.7",
      "endpoint": "messages",
      "method": "POST",
      "status": "succeeded",
      "status_code": 200,
      "is_stream": false,
      "request_mode": "batch",
      "batch": {
        "protocol": "claude",
        "job_id": "msgbatch_01K...",
        "custom_id": "request-1",
        "price_multiplier": "0.5"
      },
      "tokens": {
        "input": 120,
        "output": 45,
        "cached": 0,
        "cache_write": 0,
        "reasoning": 0,
        "total": 165
      },
      "cost": "0.0000345",
      "usage_cost": "0.00345",
      "official_base_cost": "0.000345",
      "currency": "USD",
      "usage_pricing": {
        "basis": "official_price",
        "base_field": "official_base_cost",
        "base_amount": "0.000345",
        "multiplier": "10",
        "usage_cost": "0.00345",
        "formula": "round(base_amount * multiplier, 10)"
      },
      "pricing_snapshot": {
        "available": true,
        "unit": "per_1m_tokens",
        "user_price": {
          "input": "0.2",
          "output": "1",
          "cache_read": "0.02",
          "cache_write": "0.25",
          "reasoning": "1"
        },
        "official_price": {
          "input": "1",
          "output": "5",
          "cache_read": "0.1",
          "cache_write": "1.25",
          "reasoning": "5"
        },
        "usage_price": {
          "input": "10",
          "output": "50",
          "cache_read": "1",
          "cache_write": "12.5",
          "reasoning": "50"
        }
      },
      "duration_ms": 842,
      "gateway_overhead_ms": 34,
      "upstream_first_token_ms": 156,
      "e2e_first_token_ms": 190,
      "settlement_status": "settled",
      "started_at": "2026-08-05T10:00:00Z",
      "finished_at": "2026-08-05T10:00:00.842Z"
    }
  ],
  "meta": {
    "key_id": "KEY_PUBLIC_ID",
    "limit": 10,
    "returned": 1,
    "order": "finished_at_desc",
    "next_cursor": "eyJ0IjoiMjAyNi0wOC0wNSAxMDowMDowMCIsInAiOiIwMUt...",
    "has_more": true
  }
}

Для следующей более старой страницы:

curl "https://p-api.model-gate.com/api/v1/partner/keys/KEY_PUBLIC_ID/requests?limit=10&before=NEXT_CURSOR" \
  -H "Authorization: Bearer mg_partner_..."

Некорректный курсор before возвращает HTTP 422. Курсор содержит только позицию времени завершения и публичный внешний ID запроса; внутренние числовые ID запросов никогда не раскрываются.

Для синхронных и нативных async-запросов request_mode равно sync или async, объект batch отсутствует. Сохранённый снимок токенных тарифов позволяет воспроизвести историческую базовую стоимость как sum(tokens × snapshotted_rate / 1,000,000). Расчёт округляет выбранную базовую сумму до 10 десятичных знаков, затем вычисляет round(base_amount × multiplier, 10). Определяющими остаются сохранённые поля cost, official_base_cost и usage_cost.

Этот эндпоинт никогда не возвращает исходные тела запросов и ответов.

Получить транзакции баланса

Запрос

curl https://p-api.model-gate.com/api/v1/partner/transactions \
  -H "Authorization: Bearer mg_partner_..."

Ответ — 200

{
  "data": [
    {
      "transaction_id": "TRANSACTION_PUBLIC_ID",
      "type": "debit",
      "source": "api_usage_minute",
      "billing_minute_num": 29769120,
      "amount": "-0.0232000000",
      "request_count": 100,
      "balance_before": null,
      "balance_after": null,
      "api_key_id": null,
      "created_at": "2026-08-05T10:00:00Z"
    }
  ]
}

Платный инференс представлен одной записью кошелька на владельца списания и минуту завершения. transaction_id — долговременный публичный идентификатор записи. request_count — количество запросов минутного списания; billing_minute_num — floor(unix(finished_at)/60). Внутренние значения id / source_id не возвращаются. Агрегатные строки API-использования намеренно возвращают null для balance_before, balance_after и api_key_id; точные сведения о ключе, группе и запросе доступны в истории и минутной детализации панели.

Получить текущий баланс

curl https://p-api.model-gate.com/api/v1/partner/balance \
  -H "Authorization: Bearer mg_partner_..."

{"data":{"balance":"1234.5678900000","currency":"USD","as_of":"2026-08-28T07:00:00Z"}}

Используйте этот эндпоинт после уведомлений account.balance_low, чтобы сверить текущий кошелёк аккаунта без ключа Model API.

Получить журнал действий Partner

curl "https://p-api.model-gate.com/api/v1/partner/audit-events?limit=100" \
  -H "Authorization: Bearer mg_partner_..."

События аудита фиксируют успешные управляющие изменения Partner с ID запроса, действием, объектом, исходным IP, статусом, безопасными метаданными и временем UTC. Секреты, Bearer-токены, открытые API-ключи, ключи идемпотентности, отпечатки запросов и тела повторного воспроизведения не сохраняются в метаданных аудита. Используйте cursor для следующих страниц и необязательный фильтр action.

Создать группу

Запрос

curl -X POST https://p-api.model-gate.com/api/v1/partner/groups \
  -H "Authorization: Bearer mg_partner_..." \
  -H "Idempotency-Key: operation-unique-001" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Telegram bot A",
    "description": "Keys created by bot A",
    "rpm_limit": 100,
    "concurrency_limit": 20,
    "spend_limit": "1000.0000000000",
    "usage_price_basis": "official_price",
    "usage_price_multiplier": "0.900000"
  }'

Ответ — 201

{
  "data": {
    "public_id": "GROUP_PUBLIC_ID",
    "name": "Telegram bot A",
    "status": "active",
    "spend_limit": "1000.0000000000",
    "usage": "0.0000000000",
    "total_spent": "0.0000000000",
    "usage_price_basis": "official_price",
    "usage_price_multiplier": "0.900000"
  }
}

Получить список групп

Запрос

curl https://p-api.model-gate.com/api/v1/partner/groups \
  -H "Authorization: Bearer mg_partner_..."

Ответ

{"data":[{"public_id":"GROUP_PUBLIC_ID","name":"Telegram bot A","status":"active","usage":"0.0000000000"}]}

Получить или обновить группу

Запрос получения

curl https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID \
  -H "Authorization: Bearer mg_partner_..."

Ответ получения

{"data":{"public_id":"GROUP_PUBLIC_ID","name":"Telegram bot A","spend_limit":"1000.0000000000","usage":"12.0000000000"}}

Запрос обновления

curl -X PATCH https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID \
  -H "Authorization: Bearer mg_partner_..." \
  -H "Idempotency-Key: operation-unique-001" \
  -H "Content-Type: application/json" \
  -d '{"name":"Telegram bot A production","status":"active","spend_limit":"2000.0000000000","usage_price_basis":"user_price","usage_price_multiplier":"1.200000"}'

Ответ обновления

{"data":{"public_id":"GROUP_PUBLIC_ID","name":"Telegram bot A production","spend_limit":"2000.0000000000","usage_price_basis":"user_price","usage_price_multiplier":"1.200000"}}

Удалить группу

Непустая группа не удаляется. Сначала переместите или удалите все входящие в неё API-ключи; иначе API вернёт HTTP 409 с group_not_empty.

Запрос

curl -X DELETE https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID \
  -H "Authorization: Bearer mg_partner_..." \
  -H "Idempotency-Key: operation-unique-001" \

Ответ

{"data":{"deleted":true}}

Ключи отвязываются в соответствии с поведением внешнего ключа БД. Проверьте состав группы до удаления.

Сбросить использование группы

Запрос

curl -X POST https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID/reset-usage \
  -H "Authorization: Bearer mg_partner_..." \
  -H "Idempotency-Key: operation-unique-001" \

Ответ

{"data":{"public_id":"GROUP_PUBLIC_ID","usage":"0.0000000000","total_spent":"8.5000000000"}}

Получить состав группы

Запрос

curl https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID/members \
  -H "Authorization: Bearer mg_partner_..."

Ответ

{"data":[{"public_id":"KEY_PUBLIC_ID","name":"Telegram user 123","status":"active","usage":"3.2500000000","total_spent":"1.1400000000"}]}

Добавить ключ в группу

Запрос

curl -X POST https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID/members \
  -H "Authorization: Bearer mg_partner_..." \
  -H "Idempotency-Key: operation-unique-001" \
  -H "Content-Type: application/json" \
  -d '{"key_id":"KEY_PUBLIC_ID"}'

Ответ

Ответ содержит обновлённый список ключей группы:

{"data":[{"public_id":"KEY_PUBLIC_ID","name":"Telegram user 123","status":"active"}]}

Удалить ключ из группы

Запрос

curl -X DELETE https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID/members/KEY_PUBLIC_ID \
  -H "Authorization: Bearer mg_partner_..." \
  -H "Idempotency-Key: operation-unique-001" \

Ответ

{"data":{"removed":true}}

Получить использование группы

Запрос

curl https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID/usage \
  -H "Authorization: Bearer mg_partner_..."

Ответ

{"data":{"group_id":"GROUP_PUBLIC_ID","usage":"12.0000000000","total_spent":"8.5000000000","usage_reset_at":"2026-08-01T00:00:00Z"}}

Получить статистику группы

from и to принимают только UTC RFC3339 с окончанием Z (допускается до 6 знаков дробной секунды). Статистика считается только по агрегатам завершённых запросов с привязкой к finished_at; текущая незавершённая минута намеренно исключена, поэтому результаты могут отставать на интервал минутной агрегации.

average_duration_ms — средняя полная длительность запроса Model Gate (duration_ms) по завершённым запросам выбранного периода. Это не E2E-задержка первого токена, не задержка первого токена поставщика и не накладная задержка шлюза. Partner API предоставляет только это явное имя показателя.

Запрос

curl "https://p-api.model-gate.com/api/v1/partner/groups/GROUP_PUBLIC_ID/stats?from=2026-08-01T00:00:00Z&to=2026-08-05T23:59:59Z" \
  -H "Authorization: Bearer mg_partner_..."

Ответ

{
  "data": {
    "group_id": "GROUP_PUBLIC_ID",
    "requests": 120,
    "errors": 3,
    "input_tokens": 50000,
    "output_tokens": 12000,
    "cached_tokens": 8000,
    "cache_write_tokens": 1200,
    "reasoning_tokens": 2000,
    "cost": "8.5000000000",
    "average_duration_ms": "842.50",
    "from": "2026-08-01T00:00:00Z",
    "to": "2026-08-05T23:59:59Z"
  }
}

Получить асинхронный результат

Запрос

curl https://p-api.model-gate.com/api/v1/requests/01KZ... \
  -H "Authorization: Bearer mg_partner_..."

Ответ во время обработки

{
  "data": {
    "request_id": "01KZ...",
    "status": "processing",
    "created_at": "2026-08-05T10:00:00Z",
    "started_at": "2026-08-05T10:00:00Z",
    "completed_at": null,
    "expires_at": "2026-08-06T10:00:00Z"
  }
}

Ответ после завершения

{
  "data": {
    "request_id": "01KZ...",
    "status": "completed",
    "response_status": 200,
    "response_headers": {"Content-Type":"application/json"},
    "response": {"id":"resp_example","status":"completed"},
    "completed_at": "2026-08-05T10:00:05Z",
    "expires_at": "2026-08-06T10:00:00Z"
  }
}

Общие ошибки

Неверный ключ Partner API — 401

{"error":{"type":"invalid_token","message":"Invalid Partner API key"}}

Ресурс не найден — 404

{"error":{"type":"not_found","message":"API key not found"}}

Некорректный запрос — 422

{"error":{"type":"invalid_request","message":"limit must be an integer from 1 to 100"}}

JSON-тела изменяющих запросов Partner API ограничены 1 МиБ.

Конфликт идемпотентности — 409

Тот же Idempotency-Key использован для другого запроса. Для новой логической операции создайте новый ключ.

Ограничение частоты — 429

Ответ содержит error.code = partner_rate_limit_exceeded и Retry-After. Повторяйте только после указанной задержки.

Метод не разрешён — 405

Хост Partner возвращает JSON-ошибку и HTTP-заголовок Allow; он никогда не переключается на HTML-страницу ошибки.

Правила пользователей ключей Business

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

Точный перечень маршрутов Partner API

Таблица описывает контракт PartnerBearer на хосте Partner API, не опрос Images. Подписи публичных вебхуков и сеансы портала — отдельные механизмы. PHP Router подавляет тела GET-ответов для HEAD; ниже перечислены только канонические методы API.