Kiro Manager

除登录外，所有接口需要请求头 X-API-Key: 你的密钥。JSON 请求还应发送 Content-Type: application/json。

成功响应为 JSON；失败响应格式为 {"error":"错误说明"}，请同时检查 HTTP 状态码。

获取当前用户本轮最大可提取数量，已综合余额、活动母号库存、预留量和每母号上限。

curl -H "X-API-Key: usr-xxx" /api/my/stock
# {"max":12}

获取你的全部 Key。参数: ?history=1 包含已失效的。created_at 为该记录写入数据库 api_keys 表的时间。

curl -H "X-API-Key: usr-xxx" /api/my/keys
# {"count":5,"active":3,"keys":[{"key":"ksk_...","status":"active","created_at":"2026-07-24 04:48:10"}]}

获取当前认证账号名下最早一条 Key 的数据库创建时间，用于判断账号有效期起点。接口不接收请求体，也不需要提交任何 Key。

查询范围包含当前账号在 api_keys 表中的全部历史状态记录，并按有效的 created_at 取最早时间；不会返回 Key 内容。key_count 为历史记录总数。若账号从未有过 Key，或旧库记录没有可确认的创建时间，created_at 返回 null。

curl -H "X-API-Key: usr-xxx" /api/my/keys/created-at
# {"created_at":"2026-07-20 04:48:10","key_count":5}
# 无 Key 时: {"created_at":null,"key_count":0}

获取当前用户最近 50 条提取订单，包括请求数量、实际交付数量、来源 IP、订单 ID 和创建时间。

curl -H "X-API-Key: usr-xxx" /api/my/purchase-orders
# [{"client_order_id":"0123456789abcdef0123456789abcdef","requested":2,"purchased":2,"created_at":"2026-07-24 04:48:10"}]

查看你的余额和 webhook 配置。

curl -H "X-API-Key: usr-xxx" /api/my/profile
# {"name":"alice","quota":100,"remaining":100,"used_quota":0,"webhook_url":""}

查看系统运行状态、Key 数量、库存和自动检测配置。

curl -H "X-API-Key: usr-xxx" /api/status
# {"keys_active":10,"keys_dead":2,"keys_stock":4,"generating":false,...}

拉取新 Key 并扣除实际出 Key 数量对应的余额。

count: 请求数量。低于最小提取量会直接返回 400，不再自动放大数量；库存不足时仍按实际出 Key 数量扣费。

client_order_id: 必填。32位十六进制字符串，不区分大小写；也可放在 Idempotency-Key 请求头中。

同一用户使用相同订单 ID 和相同 count 重试，会返回第一次成功时完全相同的结果且不会再次扣费；更改 count 会返回 HTTP 409。

# 推荐：客户端生成订单 ID，超时重试时复用
curl -X POST -H "X-API-Key: usr-xxx" -H "Content-Type: application/json" \
  -d '{"count":5,"client_order_id":"0123456789abcdef0123456789abcdef"}' /api/my/purchase
# {"client_order_id":"0123456789abcdef0123456789abcdef","purchased":5,"remaining":95,"keys":[{"key":"ksk_..."}]}

# 也可使用请求头传入幂等键
curl -X POST -H "X-API-Key: usr-xxx" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0123456789abcdef0123456789abcdef" \
  -d '{"count":5}' /api/my/purchase

响应字段：client_order_id 为本次订单号，purchased 为实际出 Key 数量，remaining 为剩余余额，keys 为本次分配的 Key。

使用兑换码充值余额，额度立即加到当前账号的余额上。每张兑换码只能使用一次。

code: 兑换码，形如 KM-XXXXX-XXXXX-XXXXX。大小写、空格、连字符会自动规整，可直接整段粘贴。

curl -X POST -H "X-API-Key: usr-xxx" -H "Content-Type: application/json" \
  -d '{"code":"KM-A2B3C-D4E5F-G6H7J"}' /api/my/redeem
# {"code":"KM-A2B3C-D4E5F-G6H7J","quota":100,"previous_quota":20,"balance":120,"created_by_name":"admin","redeemed_at":"2026-07-25 19:40:09","replayed":false}

响应字段：quota 为本次充值额度，previous_quota 为充值前余额，balance 为充值后余额，created_by_name 为该码的创建人，redeemed_at 为核销时间。

幂等：接口对「同一个账号 + 同一张码」是幂等的，超时重试直接原样重发即可，不会重复充值。重复提交返回 HTTP 200 且 replayed 为 true，此时 quota、redeemed_at 是首次兑换的值，previous_quota 与 balance 相等（本次未改动余额）。

并发安全：同一张码被多个请求同时提交时，只有一次会真正核销，其余按上面的规则返回 replayed 或 409，不存在被重复使用的可能。

# 重复提交同一张已兑换的码
# {"code":"KM-A2B3C-D4E5F-G6H7J","quota":100,"previous_quota":120,"balance":120,"redeemed_at":"2026-07-25 19:40:09","replayed":true}

修改你的 webhook URL。支持 http:// 和 https://；最多安全跟随 3 次重定向，并在每次跳转前重新校验目标地址。

curl -X PUT -H "X-API-Key: usr-xxx" -H "Content-Type: application/json" \
  -d '{"webhook_url":"http://your-server/hook"}' /api/my/webhook

向当前用户已保存的 Webhook URL 推送一条测试消息。

curl -X POST -H "X-API-Key: usr-xxx" /api/my/webhook/test
# {"ok":"true"}

系统会 POST JSON 到你的 webhook URL:

# 新 Key 就绪
{"event":"new_keys_available","event_id":"32位ID","purchase_order_id":"32位ID","message":"新一轮 10 个 Key 已就绪","new_keys":10}
# 自动提取程序必须把 purchase_order_id 原样作为 client_order_id；Webhook 重试时该值不变。

# 全部 Key 失效
{"event":"all_keys_dead","event_id":"32位ID","message":"本轮全部 5 个 Key 已失效","dead":5}