THE INTEGRATION CONTRACT
API 与接入规范
使用现有托管接口。凭据确定租户与权限；浏览器门户不代理、不保存你的 API 凭据。
核心接口
| 方法与路径 | 权限 | 用途 |
|---|---|---|
| POST /tenant/pricing | admin | 发布价目 返回 pricing.hash |
| POST /tenant/credentials | admin | 创建一次性展示的摄入凭据 |
| POST /t/{slug}/ingest/events | ingest / admin | 提交事件数组 凭据必须属于该租户 |
| GET /tenant/status | admin | 查看签发 承诺 TSA 与锚定状态 |
| GET /tenant/events | admin | 定位 pending processed rejected 及拒绝原因 |
| GET /t/{slug}/api/receipt/bundle?stream=…&seq=… | 匿名或相应披露凭据 | 获取单条证据包 |
| POST /tenant/grants | admin | 签发指定流的供应侧审计凭据 |
| POST /tenant/customer-tokens | admin | 按客户身份签发短期令牌 |
| GET /tenant/export | admin | 导出本租户 NDJSON 账本 |
第 6 代输入
外层事件使用 stream、source_event_id、generation、occurred_at_ms 和 input。input 使用 Go 字段名，例如 RequestID、PromptTokens 和 Pricing.ExprHash。它与签名分段中的 snake_case 字段及十进制字符串不是同一输入格式。
第 6 代仅支持 token。价目必须先在同一租户发布。UsageSemantic 明确为 openai 或 anthropic，用来声明真实的计数约定；它不是模型真实性证明。真实金额与 tier 由服务端核算。
当前服务对零值有缺省语义：MultiplierBps 为 0 时按 10000 处理；CostMicroUsd 为 0 时由表达式结果填入。不要将其当作显式零价或零乘数。
重试与错误处理
| 状态 | 处理方式 |
|---|---|
| 200 / success: true | 检查 enqueued 与 ids 并继续观察签发状态 |
| 400 | 修正字段 代际 价目引用或计数口径 不要原样重试 |
| 401 / 403 | 检查凭据类型 过期 撤销 租户归属或停用状态 |
| 413 | 按服务限制缩小批次 保持来源 ID 不变 |
| 网络错误 / 5xx | 退避重试同一事件 不更换来源 ID |
合成流量不应进入真实账本；标记 synthetic 的事件会拒签。HTTP 接收与签发是不同阶段，应查询事件状态确认最终结果。
凭据不能混用
admin 管理本租户；ingest 只交付事件；audit grant 在指定流范围内披露供应侧；customer token 只披露本人客户侧。运营凭据不应交给租户或放在浏览器中。
查阅公开协议与分段 schema