API 总览

基址与版本

对外承诺兼容的是 /v1/...。

/api/... 是网页端自己在用的，随时可能改，不要对它编程。

认证

按应用签发密钥（key_id 与 secret），在开发者控制台创建。

/v1 的每个请求都要签名，四个头缺一不可：

X-Api-Key: ak_xxxxxxxxxxxx
X-Timestamp: <Unix 秒>
X-Nonce: <一次性随机串>
X-Signature: <签名>

签名是用 secret 对「方法 + 路径 + 规范化 query + 时间戳 + nonce + 请求体 SHA-256」做的 HMAC-SHA256。时间戳过期或 nonce 重复都会被拒——这是为了让截获的 请求没法重放。

警告

/v1 不接受 Authorization: Bearer，直接发 bearer 会返回 401。需要用单个 token 的简单认证，走 MCP 端点。

权限（scope）挂在应用上，不在密钥上——密钥是可轮换的凭据， 权限是应用的属性。换密钥不影响权限。

幂等

花钱的接口（开通、续费）要求 Idempotency-Key 头，8~100 位 [A-Za-z0-9-_.:]。

重试用同一个 key，服务端会返回第一次的结果而不是再扣一次钱。

配额

每个响应都带用量：

X-RateLimit-Limit:     600
X-RateLimit-Remaining: 594
X-RateLimit-Reset:     1756512060

自动化派发的配额单位不一样

派发按设备台次计，不按请求数——一次请求最多派 200 台， 按请求数记会把压力少算 200 倍。超限时响应里的 unit 字段会写明。

设备标识

对外一律使用我方 device_id（整数）。上游的设备编号不会下发。

请求里混入不属于你的 device_id 时，整个请求返回 404， 不会告诉你是哪一台——否则这个接口就成了枚举别人设备的工具。