兼容适配契约复核日期: 2026-07-10
安全边界
PayAPIKey 托管接口不接收中转站管理员 Token、渠道 Key、Cookie 或会话。原生 API 读取必须在你控制的本地 connector/sidecar 中完成；托管端只接收去敏后的计费元数据。
支持范围
模式
兼容适配
字段族
one-hub
授权方式
访问令牌
能力
请求级用量 · 渠道元数据 · 当前价格记录 · 支付订单元数据
凭据边界
凭据只能放在本地 sidecar，并删除所有渠道 Key；连接器应固定到部署的 one-hub revision。
读取流程
- 1在中转站所在网络中运行本地 connector/sidecar，并使用最小权限账号调用原生接口。
- 2在本地剔除敏感字段，只将 logs 响应与 connector ID 提交到 /api/v1/normalize。
- 3合并上游账单和支付结算导出，再调用 /api/v1/reconcile。
原生资源
| 用途 | 方法与路径 | 权限 | 说明 |
|---|---|---|---|
| 实例状态 | GET /api/status | 公开实例元数据 | 可用时读取额度换算和部署版本。 |
| 用量日志 | GET /api/log/?log_type=2&page=1&size=100&start_timestamp={unix}&end_timestamp={unix} | 管理员 | 使用 log_type、page/size 与 data.total_count；异步或批量日志需预留 1–5 分钟延迟。 |
| 渠道列表 | GET /api/channel/?page=1&size=100 | 管理员 | 规范化前删除所有含 Key 字段。 |
| 当前价格记录 | GET /api/prices?type=db | 视部署配置而定 | 采集时保存版本化快照；接口只代表当前状态。 |
| 支付订单 | GET /api/payment/order?page=1&size=100 | 管理员 | 仅用于钱包订单联查；现金结算仍以支付服务商导出为准。 |
本地请求头（示意）
Authorization: Bearer $ONE_HUB_ACCESS_TOKEN字段映射
映射在 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 | — |
channel_id / channel.name | downstreamUsage[].channelId | — |
metadata.cached_read_tokens / cached_tokens | downstreamUsage[].tokens.cacheRead | — |
metadata.cached_write_tokens | downstreamUsage[].tokens.cacheWrite | — |
metadata.reasoning_tokens | downstreamUsage[].tokens.reasoning | — |
已知限制
- 日志可能延迟写入，直接以当前时刻作为游标会漏掉迟到记录。
- 当前价格不能证明历史请求实际使用的费率。
- 退款语义与字段仍与具体发行版绑定。