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 в моментна снимка.

Латентността използва стабилни имена на фирми/партньори: gateway_overhead_ms, upstream_first_token_ms, и e2e_first_token_ms. Стойността на първия токен E2E се измерва от началото на заявката за модел 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 обратни извиквания за съгласуване на портфейла на текущия акаунт, без да се изискват идентификационни данни за 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"}}

Мутиращите Partner API JSON тела са ограничени до 1 MiB.

Конфликт на идемпотентност — 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 за идентифициране на принципала на идентификационните данни независимо от собствеността върху фактурирането.