B2BB2B LLM

Partner API конечных точек

Полные примеры запросов и ответов Partner API для ключей, групп, запросов и транзакций.

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-* заголовки. Неизвестные поля тела/запроса отклоняются.

Машиночитаемый контракт 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"}}

Для разморозки требуется подтвержденный адрес электронной почты владельца.

Поворот клавиши

Запрос

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 как непрозрачный before параметр запроса для получения следующей более старой страницы. Не анализируйте и не создавайте курсоры самостоятельно.

Ответ содержит неизменяемые пользовательские и официальные ставки за миллион токенов для запросов, выполненных после миграции. 059_request_pricing_audit_snapshot.sql. Он также вычисляет pricing_snapshot.usage_price из сохраненного базиса, множителя и исторических ставок без сохранения другого набора ставок. Это делает независимую оценку лимита использования доступной для аудита после изменения каталожных цен. Исторические запросы, созданные до возврата миграции 059 pricing_snapshot.available: false вместо замены текущих цен. Запросы, выполняемые через пакетные API, совместимые с Claude/OpenAI, явно помечаются значком request_mode: "batch" и укажите их протокол, идентификатор пакетного задания, custom_idи моментальный множитель цены партии Model Gate.

В Latency используются стабильные имена компаний/партнеров: 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. Курсор содержит только позицию времени окончания и общедоступный идентификатор внешнего запроса; внутренние числовые идентификаторы запросов никогда не раскрываются.

Для синхронных и собственных асинхронных запросов: 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.

Получение списка событий аудита партнеров

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

События аудита фиксируют успешные изменения управления партнерами с идентификатором запроса, действием, целью, исходным IP-адресом, статусом, безопасными метаданными и меткой времени в формате UTC. Секреты, токены-носители, открытый текст 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

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

Основные правила бизнес-учетных данных

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