对账 API 参考 | PayAPIKey

安全边界

PayAPIKey 托管接口不接收中转站管理员 Token、渠道 Key、Cookie 或会话。原生 API 读取必须在你控制的本地 connector/sidecar 中完成；托管端只接收去敏后的计费元数据。

接口一览

POST/api/v1/reconcile

对三本规范账生成汇总、毛利和差异项。

POST/api/v1/normalize

把 One API 字段族的日志响应转换为规范账。

GET/api/v1/connectors

读取支持状态、资源路径、字段映射和限制。

GET/api/v1/connectors/{connectorId}/manifest

读取单个连接器的能力、安全边界与机器映射契约。

GET/api/v1/examples/reconciliation

取得可直接运行的规范输入示例。

GET/openapi.json

取得 OpenAPI 3.1 机器可读契约。

POST /api/v1/reconcile

请求体必须是规范 ReconciliationInput。downstreamUsage 必填；上游或支付账可暂缺，但报告会标记完整性不足。

字段	类型	说明
`version`	string	可选；输入 schema 版本。
`currency`	string	报告币种，默认 USD。不会自动换汇。
`period`	object	可选 start/end 结算区间。
`downstreamUsage`	array	必填，下游消费收入记录。
`upstreamCharges`	array	可选，上游实际成本记录。
`payments`	array	可选，支付与钱包入账记录。

JSON

{
  "currency": "USD",
  "period": { "start": "2026-07-01T00:00:00Z", "end": "2026-08-01T00:00:00Z" },
  "downstreamUsage": [{
    "requestId": "req_01",
    "occurredAt": "2026-07-10T08:00:00Z",
    "model": "example-model",
    "channelId": "channel_7",
    "status": "success",
    "chargedAmount": "0.024",
    "currency": "USD",
    "tokens": { "input": 1200, "output": 300, "cacheRead": 500 }
  }],
  "upstreamCharges": [{
    "requestId": "req_01",
    "occurredAt": "2026-07-10T08:00:00Z",
    "model": "example-model",
    "status": "success",
    "costAmount": "0.016",
    "currency": "USD"
  }],
  "payments": []
}

记录字段

downstreamUsage[]

字段	类型	说明
`requestId`	string	必填；用于请求级匹配，必须尽量稳定且唯一。
`occurredAt`	date-time	必填，ISO 8601。
`model / channelId`	string	模型与渠道维度。
`status`	enum	success \| failed \| pending \| refunded
`chargedAmount`	number \| decimal string	必填；客户已扣金额。推荐十进制字符串。
`refundAmount / expectedCharge`	number \| decimal string	可选退款额与价格快照应收额。
`tokens`	object	input, output, cacheRead, cacheWrite, reasoning, media

upstreamCharges[]

字段	类型	说明
`requestId`	string	建议提供；与下游 requestId 精确匹配。
`upstreamId`	string	上游账单或请求标识。
`occurredAt / model`	date-time / string	必填。
`status`	enum	success \| failed \| pending \| refunded
`costAmount`	number \| decimal string	必填；上游实际成本。推荐十进制字符串。
`refundAmount / currency`	number \| decimal string / string	可选退款额与币种。

payments[]

字段	类型	说明
`transactionId`	string	必填；支付交易标识。
`occurredAt`	date-time	必填。
`status`	enum	settled \| pending \| failed \| refunded \| chargeback
`amount`	number \| decimal string	必填；捕获金额。推荐十进制字符串。
`feeAmount / refundAmount`	number \| decimal string	处理费与退款。
`creditedAmount`	number \| decimal string	实际发放到钱包的额度，用于资金核对。

POST /api/v1/normalize

接收 New API、One API 或 one-hub 的原生日志响应，并转换为规范输入。connector 必须是支持的 ID；logs 可以是数组或常见分页响应。

JSON

{
  "connector": "new-api",
  "currency": "USD",
  "quotaPerUnit": 500000,
  "logs": { "data": [{ "id": 1, "request_id": "req_01", "created_at": 1783670400, "model_name": "example-model", "quota": 12000 }] }
}

quotaPerUnit 必须读取当前部署的 /api/status.data.quota_per_unit；这里只是示例值，不能跨站点硬编码。

先在本地去敏

规范化器会拒绝 Key、Cookie、会话以及 prompt、content、messages 等正文类字段。渠道响应尤其可能含 Key；只保留 ID、模型、Token 和金额等计费元数据。

响应、限制与错误

200 成功响应使用 { data: ... } 包装。
400 JSON 或账本字段无效；details 最多返回 50 条校验信息。
413 请求体超过 2 MB。
415 Content-Type 不是 application/json。
每本账最多 5,000 条；金额可用有限非负 JSON 数字或规范十进制字符串；系统不会自动换汇。
公开接口允许跨域 JSON 调用，但不应从浏览器暴露中转站管理员凭据。

下载 OpenAPI 3.1 JSON

规范化与对账 API