可观测性

每次调用都可追踪：一个 request id 贯穿响应 Header、控制台日志与账单。

Request ID

每个响应都带 X-Request-Id，形如 req_01JABC...（ULID）。错误响应的 body 里也有同一个值。

curl -i https://heiyutv.com/api/v1/chat/completions \
  -H "Authorization: Bearer sk-gw-XXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-opus-5","messages":[{"role":"user","content":"hi"}]}'

HTTP/1.1 200 OK
X-Request-Id: req_01JABCDEF0123456789ABCDEF

你也可以自己传入 X-Request-Id：只要是 req_<ULID> 格式，网关会原样沿用， 方便把你自己的链路 id 和我们的日志对齐。格式不合法则忽略并另发一个。

报障时请带上它。有 request id 我们能直接定位到那一次调用；没有的话只能按时间范围翻。

限流余量

每个响应都带当前窗口的限流状态，不需要额外接口去查：

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Window: 60

Window 单位是秒。触发限流时返回 429 ERR_RATE_LIMITED，详见错误码。

控制台

• Logs · 每次请求一行：模型、token 拆分、耗时、状态、本次费用。 顶部搜索框直接粘 request id
• Billing · 账户流水与余额变动
• 视频生成 · 异步任务的进度、结果链接与计费明细

用量接口

控制台的数据来自这几个接口。它们走控制台会话（Cookie），不是 sk-gw- Bearer key——所以适合在浏览器里用，不适合接进服务端看板：

GET /api/v1/usage/balance
GET /api/v1/usage/summary?range=24h
GET /api/v1/usage/by-model
GET /api/v1/usage/events/recent

range 目前只接受 24h，其他值返回 400 ERR_BAD_RANGE。

关于 /metrics

/metrics 是运维侧的 Prometheus 端点，服务于平台自身的监控， 不属于客户 API，也不保证其指标名与标签的稳定性——它会随内部实现变化。 请以上面的 request id、控制台与用量 API 为准。