Partner API 个端点
完成密钥、组、请求和事务的 Partner API 请求和响应示例。
Partner API 个端点
基本网址：
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 而不是用当前价格来替代。通过 Claude/OpenAI 兼容的批处理 API 执行的请求显式标记为 request_mode: "batch" 并包括他们的协议、批处理作业 ID、 custom_id，以及快照的模型门批量价格乘数。
延迟使用稳定的业务/合作伙伴名称： gateway_overhead_ms, upstream_first_token_ms， 和 e2e_first_token_ms。 E2E 第一个令牌值是从模型门请求开始到第一个真实内容令牌测量的，不包括客户端网络/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 永远不会暴露。
对于同步和本机异步请求， 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_..."审核事件记录成功的合作伙伴管理变更，包括请求 ID、操作、目标、源 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 是平均完整模型门请求持续时间（duration_ms）在选定的时间段内完成的请求。它不是端到端第一令牌延迟、上游第一令牌延迟或网关开销。 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 错误页面。
商业凭证主体规则
对于企业 Partner API 令牌，仅接受经过验证的组织所有者。通过 Partner API 创建的密钥使用该所有者作为计费所有者和凭据主体。员工-负责人分配在 Web 面板中执行。 group_id提供时，必须标识企业帐户拥有的活动组；无效值返回 HTTP 422 并且永远不会退回到未分组的键。请求历史响应可能包括 principal_user_id 独立于计费所有权来识别凭证主体。