已验证读取契约契约复核日期: 2026-07-10
安全边界
PayAPIKey 托管接口不接收中转站管理员 Token、渠道 Key、Cookie 或会话。原生 API 读取必须在你控制的本地 connector/sidecar 中完成；托管端只接收去敏后的计费元数据。
支持范围
模式
已验证读取契约
字段族
one-api-compatible
授权方式
系统访问令牌
能力
请求级用量 · 异步任务退款 · 渠道元数据 · 当前定价快照 · 充值订单元数据 · 可选余额刷新
凭据边界
Authorization 与 New-Api-User 只能存在于本地 connector/sidecar，不得进入 PayAPIKey 托管请求或代码仓库。
读取流程
- 1在中转站所在网络中运行本地 connector/sidecar，并使用最小权限账号调用原生接口。
- 2在本地剔除敏感字段，只将 logs 响应与 connector ID 提交到 /api/v1/normalize。
- 3合并上游账单和支付结算导出，再调用 /api/v1/reconcile。
原生资源
| 用途 | 方法与路径 | 权限 | 说明 |
|---|---|---|---|
| 实例状态与额度换算 | GET /api/status | 公开实例元数据 | 读取 data.quota_per_unit 与版本；不得跨站点硬编码 500000。 |
| 用量日志 | GET /api/log/?type=2&p=1&page_size=100&start_timestamp={unix}&end_timestamp={unix} | 管理员 | 从 p=1 开始，page_size 最大 100；固定结束水位、重叠时间窗并按事件 ID 去重。 |
| 退款日志 | GET /api/log/?type=6&p=1&page_size=100&start_timestamp={unix}&end_timestamp={unix} | 管理员 | 主要确认异步任务退款，不能代表所有同步预扣冲正都具备独立退款日志。 |
| 渠道列表 | GET /api/channel/?p=1&page_size=100 | 管理员 | 仅在本地使用 ID 与名称；上传前删除所有含 Key 字段。 |
| 当前定价 | GET /api/pricing | 视部署配置而定 | 当前状态不是历史价格；采集时保存带生效时间和版本的本地快照。 |
| 充值订单 | GET /api/user/topup?p=1&page_size=100 | 管理员或授权用户 | TopUp.money 未可靠携带币种；需与支付渠道导出本地联查，不能猜币种。 |
| 刷新渠道余额 | GET /api/channel/update_balance | 管理员 | 有副作用，可能触发上游请求，不应高频轮询。 |
本地请求头（示意）
Authorization: Bearer $NEW_API_ACCESS_TOKEN
New-Api-User: $NEW_API_USER_ID字段映射
映射在 connector/sidecar 或 /api/v1/normalize 中完成。历史记录没有 request_id 时会生成合成 ID，但这不能保证请求级上游匹配。
| 源字段 | 规范字段 | 说明 |
|---|---|---|
request_id / requestId | downstreamUsage[].requestId | 尽量使用管理员日志接口；部分 self 日志视图会重写展示用 ID。 |
created_at | downstreamUsage[].occurredAt | Unix 秒时间戳会转换为 ISO 8601 UTC 时间。 |
user_id / username | downstreamUsage[].userId | — |
token_id / token_name | downstreamUsage[].tokenId | — |
model_name | downstreamUsage[].model | — |
channel / channel_id | downstreamUsage[].channelId | — |
quota | downstreamUsage[].chargedAmount | 这里只是下游计费单位，不是供应商成本；必须除以当前部署的 /api/status.data.quota_per_unit。 |
prompt_tokens | downstreamUsage[].tokens.input | — |
completion_tokens | downstreamUsage[].tokens.output | — |
other.cache_tokens / cached_tokens | downstreamUsage[].tokens.cacheRead | — |
other.cache_write_tokens / cache_creation_tokens | downstreamUsage[].tokens.cacheWrite | — |
other.reasoning_tokens | downstreamUsage[].tokens.reasoning | — |
已知限制
- quota 与 used_quota 是下游计费/额度计数，不是供应商账单成本。
- 没有保存历史快照时，当前定价接口无法还原旧请求当时的价格。
- 缓存、推理、媒体和异步任务元数据会随适配器与版本变化。
- 支付结算、手续费、退款与拒付必须以支付服务商导出为准。