BOT KEY 适用场景
BOT KEY 面向客服机器人、监控脚本和自动化任务。它不依赖网页登录态，网页退出登录不会影响已创建的 BOT KEY。
BOT KEY 明文以 bot- 开头，只在创建成功时显示一次。请保存到服务端环境变量或密钥管理器，不要写入浏览器存储、公开日志、工单截图或 Prompt。
- 用户 BOT：只能查询当前 owner 自己的数据，适合客户反馈机器人。
- 管理 BOT：只有 active admin owner 才能查询全站数据，适合内部运营或监控机器人。
- 7 天滑动过期：每次成功调用会刷新最后使用时间，连续 7 天无操作后自动失效。
如何鉴权
所有 BOT API 都使用 Bearer BOT KEY，不使用网页登录 JWT。
如果返回 401，通常是 BOT KEY 缺失、错误、被禁用或超过 7 天未使用；如果返回 403，通常是当前 BOT KEY 权限不足。
Authorization: Bearer bot-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json创建与管理 BOT KEY
BOT KEY 的创建、列表、启停、重置和删除都通过登录用户的 Panel 管理接口完成，调用这些接口时使用网页登录 JWT，不使用 bot- BOT KEY。普通用户只能创建用户 BOT；管理员可以选择 user 或 admin scope。
创建和重置响应中的 key 是完整 BOT KEY 明文，只展示一次；列表、启停和删除响应只返回脱敏元数据，不会再次返回明文。请立即保存到服务端环境变量或密钥管理器，丢失后只能重置或重新创建。
不要把完整 BOT KEY 写入前端代码、localStorage、公开日志、Prompt、截图或工单。管理接口需要用户登录态；BOT 业务接口才使用 Authorization: Bearer bot-...。
| 接口 | 请求 body | 返回与说明 |
|---|---|---|
| GET /api/v1/user/keys/bot/list?page=1&limit=20 | 无 | 分页列出当前账号的 BOT KEY 元数据，包括 id、name、scope、status/is_active、last_used_at、created_at、updated_at；不返回 key 明文或 key_hash。 |
| POST /api/v1/user/keys/bot/create | {"name":"客服机器人","scope":"user"} 或 {"name":"运维机器人","scope":"admin"} | 创建 BOT KEY 并返回元数据和一次性 key 明文（bot-...）。admin scope 仅管理员可用；普通用户传 admin 会被拒绝或降为 user，以后端校验为准。 |
| POST /api/v1/user/keys/bot/toggle | {"id":"bot_key_uuid","status":"active"} 或 {"id":"bot_key_uuid","status":"disabled"} | 启用或停用指定 BOT KEY。停用后现有机器人调用 BOT API 会返回 401，重新启用后可继续使用同一个 key。 |
| POST /api/v1/user/keys/bot/reset | {"id":"bot_key_uuid"} | 轮换指定 BOT KEY，旧 key 立即失效；响应返回新的 bot- 明文且同样只显示一次。 |
| POST /api/v1/user/keys/bot/delete | {"id":"bot_key_uuid"} | 删除指定 BOT KEY。删除后不可恢复，调用端必须改用其他 key 或重新创建。 |
分页与时间筛选
| 参数 | 位置 | 是否必填 | 取值 | 说明 |
|---|---|---|---|---|
| page | query | 否 | 正整数 | 列表页码，默认 1。 |
| limit | query | 否 | 1-100 | 每页数量，默认 20；超过 100 会被裁剪为 100。 |
| from | query | 否 | YYYY-MM-DD 或 RFC3339 | 开始时间，用于 usage 和 request 列表。 |
| to | query | 否 | YYYY-MM-DD 或 RFC3339 | 结束时间；YYYY-MM-DD 会按次日 00:00 作为排他上界。 |
账户与概览
用户 BOT 面向一个账号，只能读取 owner 自己的状态、额度、日志和设置。
| 接口 | 说明 |
|---|---|
| /api/v1/bot/user/me | GET — 查看 owner 和当前 BOT KEY 脱敏信息。 |
| /api/v1/bot/user/status | GET — 检查账号状态和 BOT KEY 可用性。 |
| /api/v1/bot/user/quota | GET — 查询 token、coding、image 余额和窗口刷新时间。 |
| /api/v1/bot/user/overview | GET — 读取用户 Panel 首页概览。 |
| /api/v1/bot/user/usage | GET — 查询账单和用量流水。Query: page, limit, ledger_type, billing_plan, query, request_model/model_name/model, from, to。 |
密钥与模型
| 接口 | 说明 |
|---|---|
| /api/v1/bot/user/key/list | GET — 列出用户 API KEY 脱敏信息。Query: page, limit。 |
| /api/v1/bot/user/key/toggle | POST — 启用或禁用一个用户 API KEY。Body: {"id":"api_key_uuid","status":"active"} 或 {"id":"api_key_uuid","status":"disabled"}。 |
| /api/v1/bot/user/model/list | GET — 查询用户可见模型；status 可为 active 或 disabled。Query: page, limit, query, status。 |
| /api/v1/bot/user/route/list | GET — 查询可调用模型路由和健康指标；window 支持 24h、7d、30d。Query: window, capability, query。 |
请求日志
| 接口 | 说明 |
|---|---|
| /api/v1/bot/user/request/list | GET — 查询用户自己的请求日志；query 支持请求 ID、Trace ID、日志 ID、owner 用户 ID 或 owner 邮箱模糊匹配；返回会隐藏上游内部信息。Query: page, limit, query, model_name/model, protocol, billing_plan, status, from, to。 |
| /api/v1/bot/user/request/trace | GET — 按 request_id、trace_id 或 request log id 查询单条链路。Query: query（必填）。 |
设置与兑换
| 接口 | 说明 |
|---|---|
| /api/v1/bot/user/setting | GET — 读取扣费偏好设置。 |
| /api/v1/bot/user/setting/update | POST — 更新 LLM 扣费偏好；preferred_billing 只能是 coding 或 token。Body: {"preferred_billing":"coding","fallback_enabled":true}。 |
| /api/v1/bot/user/redeem | POST — 为当前 owner 兑换兑换码；code 必填。Body: {"code":"REDEEM-CODE"}。 |
常用筛选字段
- ledger_type 支持逗号分隔：charge、recharge、reserve、refund、adjustment、plan_grant、plan_upgrade、plan_renew、plan_replace。
- billing_plan 支持 coding、token、image。
- request status 支持 success、failed、pending。
- protocol 常见值：openai_chat、openai_responses、anthropic_messages。
- route window 支持 24h、7d、30d；空值或非法值会按 24h 处理。
重点参数详解
下面是 BOT 最常用参数的实际填写方式。客服机器人优先使用 query、request_id、trace_id、user_id 这类稳定字段，不要让用户提交密钥或内部配置。
| 参数 | 接口 | 说明与示例 |
|---|---|---|
| query | request/list、request/trace、usage | 模糊搜索请求 ID、Trace ID、request log id、用户 ID、owner 邮箱、ledger id、模型名或 reason；trace 接口中必填。示例：req_abc123、trace_abc123、thesumwai@gmail.com、账单流水 ID、glm-5.1。 |
| model_name / model | request/list、usage | 按请求模型名过滤；request_model、model_name、model 在 usage 中都可作为模型过滤别名。示例：glm-5、glm-4.5、gpt-4o:fast。 |
| ledger_type | usage | 逗号分隔用量流水类型；客服常用 charge 查扣费，recharge 查充值，plan_* 查兑换码套餐到账。示例：charge,recharge,plan_grant。 |
| billing_plan | usage、request/list | 按扣费计划过滤；普通文本模型通常是 coding 或 token，图片生成是 image。示例：coding、token、image。 |
| status | request/list、model/list | 请求日志状态使用 success/failed/pending；模型列表状态使用 active/disabled。示例：success、failed、pending；active、disabled。 |
| from / to | usage、request/list | 按时间范围过滤；YYYY-MM-DD 的 to 会包含当天整天，因为服务按次日 00:00 做排他上界。示例：from=2026-05-01&to=2026-05-24。 |
| window | route/list | 路由健康统计窗口；用于回答某模型最近 24 小时或 7 天的成功率、耗时、可用路由。示例：24h、7d、30d。 |
| capability | route/list | 按模型能力过滤路由列表；具体能力名称以平台模型配置为准。示例：chat、responses、messages、image。 |
| user_id | admin/user/*、admin/request/list | 管理 BOT 的 detail/quota/usage 需要完整用户 ID；request/list 和 user/request 支持用户 ID 片段模糊匹配。示例：550e8400-e29b-41d4-a716-446655440000 或 446655。 |
| code | user/redeem | 兑换码明文。服务会 trim 并标准化；为空会返回 400 INVALID_PARAM 或 404 NOT_FOUND。示例：BETATEST、WELCOME-2026。 |
用户 BOT 可复制示例
下面示例假设已设置 TOKENMP_BASE_URL=https://api.tokenmp.cn 和 TOKENMP_BOT_KEY=bot-...。
# 1. 检查账号和 BOT KEY 状态
curl -sS "$TOKENMP_BASE_URL/api/v1/bot/user/status" \
-H "Authorization: Bearer $TOKENMP_BOT_KEY"
# 2. 查询余额、套餐、窗口剩余额度
curl -sS "$TOKENMP_BASE_URL/api/v1/bot/user/quota" \
-H "Authorization: Bearer $TOKENMP_BOT_KEY"
# 3. 查最近失败请求
curl -sS "$TOKENMP_BASE_URL/api/v1/bot/user/request/list?status=failed&page=1&limit=10" \
-H "Authorization: Bearer $TOKENMP_BOT_KEY"
# 4. 按用户给出的请求 ID 或 Trace ID 定位日志
curl -sS "$TOKENMP_BASE_URL/api/v1/bot/user/request/trace?query=req_abc123" \
-H "Authorization: Bearer $TOKENMP_BOT_KEY"
# 5. 查某个模型最近 7 天路由健康
curl -sS "$TOKENMP_BASE_URL/api/v1/bot/user/route/list?query=glm-5&window=7d" \
-H "Authorization: Bearer $TOKENMP_BOT_KEY"
# 6. 查本月 token 扣费流水
curl -sS "$TOKENMP_BASE_URL/api/v1/bot/user/usage?ledger_type=charge&billing_plan=token&from=2026-05-01&to=2026-05-24" \
-H "Authorization: Bearer $TOKENMP_BOT_KEY"兑换码请求示例
当用户明确提供兑换码时，客服机器人可以用用户 BOT 代为兑换。成功响应的 data 会包含 redeem_code_id、redeem_code_name、token_amount、rewards、ledger 和 redeemed_at。
Coding Plan 兑换会按套餐等级处理：低等级不能覆盖当前更高等级套餐，会返回 REDEEM_CODE_PLAN_DOWNGRADE；高等级兑换低等级时按升级处理；同等级兑换会自动续期。升级时会根据旧套餐剩余价值折算补偿天数，核心规则是同时参考时间剩余比例和月请求剩余比例，折算后补到新套餐上，最终有效期以新套餐默认时长加补偿天数为准。
| HTTP | error_code | 说明 |
|---|---|---|
| 404 | NOT_FOUND | 兑换码不存在，或提交后为空。 |
| 400 | REDEEM_CODE_INACTIVE | 兑换码已禁用或删除。 |
| 400 | REDEEM_CODE_EXPIRED | 兑换码已过期。 |
| 400 | REDEEM_CODE_EXHAUSTED | 兑换次数已用完。 |
| 409 | REDEEM_CODE_ALREADY_REDEEMED | 当前用户已经兑换过该兑换码。 |
| 400 | REDEEM_CODE_PLAN_DOWNGRADE | 兑换会降级当前套餐，因此被拒绝。 |
| 400 | REDEEM_CODE_PLAN_INACTIVE | 兑换码关联的套餐已停用。 |
curl -sS "https://api.tokenmp.cn/api/v1/bot/user/redeem" \
-H "Authorization: Bearer $TOKENMP_BOT_KEY" \
-H "Content-Type: application/json" \
--data '{"code":"REDEEM-CODE"}'设置更新示例
preferred_billing 控制 LLM 请求优先使用 coding 还是 token；fallback_enabled=true 表示首选计划额度不足时允许自动切换到另一个 LLM 计费计划。
# 优先使用 Coding Plan，并允许额度不足时自动切到 Token Plan
curl -sS "https://api.tokenmp.cn/api/v1/bot/user/setting/update" \
-H "Authorization: Bearer $TOKENMP_BOT_KEY" \
-H "Content-Type: application/json" \
--data '{"preferred_billing":"coding","fallback_enabled":true}'
# 优先按 Token 余额扣费，并关闭自动切换
curl -sS "https://api.tokenmp.cn/api/v1/bot/user/setting/update" \
-H "Authorization: Bearer $TOKENMP_BOT_KEY" \
-H "Content-Type: application/json" \
--data '{"preferred_billing":"token","fallback_enabled":false}'平台概览
管理 BOT 可查询全站数据，只应在内部监控和运营机器人中使用。
| 接口 | 说明 |
|---|---|
| /api/v1/bot/admin/me | GET — 查看 admin owner 和当前 BOT KEY 脱敏信息。 |
| /api/v1/bot/admin/status | GET — 检查平台状态和安全配置摘要。 |
| /api/v1/bot/admin/overview | GET — 读取全站概览指标。 |
| /api/v1/bot/admin/usage | GET — 读取全站趋势。Query: days（只能是 1、7、15，默认 7）。 |
模型与路由
| 接口 | 说明 |
|---|---|
| /api/v1/bot/admin/model/list | GET — 列出全站模型目录。Query: page, limit, query, status。 |
| /api/v1/bot/admin/route/list | GET — 读取路由工作台聚合数据。Query: window, capability, query。 |
请求日志
| 接口 | 说明 |
|---|---|
| /api/v1/bot/admin/request/list | GET — 查询全站请求日志；query 支持用户邮箱/用户 ID 模糊匹配，user_id 支持用户 ID 片段模糊过滤；会包含管理侧内部排障字段。Query: page, limit, query, user_id, model_name/model, provider_id, protocol, billing_plan, status, from, to。 |
| /api/v1/bot/admin/request/trace | GET — 按请求 ID 或 Trace ID 查询全站链路。Query: query（必填）。 |
用户管理
| 接口 | 说明 |
|---|---|
| /api/v1/bot/admin/user/detail | GET — 查询指定用户资料。Query: user_id（必填）。 |
| /api/v1/bot/admin/user/quota | GET — 查询指定用户额度。Query: user_id（必填）。 |
| /api/v1/bot/admin/user/usage | GET — 查询指定用户用量流水。Query: user_id（必填）, page, limit, ledger_type, billing_plan, query, request_model/model_name/model, from, to。 |
| /api/v1/bot/admin/user/request | GET — 按必填 user_id 片段模糊查询匹配用户的请求日志，并展示管理侧内部字段；query 也可匹配用户邮箱/用户 ID。Query: user_id（必填）, page, limit, query, model_name/model, provider_id, protocol, billing_plan, status, from, to。 |
管理 BOT 可复制示例
下面示例假设已设置 TOKENMP_ADMIN_BOT_KEY=bot-...。管理 BOT 会看到更多内部排障字段，请只在内部系统中使用。
# 1. 查看平台状态和安全配置摘要
curl -sS "$TOKENMP_BASE_URL/api/v1/bot/admin/status" \
-H "Authorization: Bearer $TOKENMP_ADMIN_BOT_KEY"
# 2. 查看最近 7 天全站用量趋势
curl -sS "$TOKENMP_BASE_URL/api/v1/bot/admin/usage?days=7" \
-H "Authorization: Bearer $TOKENMP_ADMIN_BOT_KEY"
# 3. 按 Trace ID 查全站链路
curl -sS "$TOKENMP_BASE_URL/api/v1/bot/admin/request/trace?query=trace_abc123" \
-H "Authorization: Bearer $TOKENMP_ADMIN_BOT_KEY"
# 4. 查询指定用户额度
curl -sS "$TOKENMP_BASE_URL/api/v1/bot/admin/user/quota?user_id=550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Bearer $TOKENMP_ADMIN_BOT_KEY"
# 5. 用完整用户 ID 或唯一用户 ID 片段查询匹配用户最近失败请求
curl -sS "$TOKENMP_BASE_URL/api/v1/bot/admin/user/request?user_id=446655&status=failed&limit=10" \
-H "Authorization: Bearer $TOKENMP_ADMIN_BOT_KEY"
# 6. 查询某模型全站错误日志
curl -sS "$TOKENMP_BASE_URL/api/v1/bot/admin/request/list?model_name=glm-5&status=failed&from=2026-05-01&to=2026-05-24" \
-H "Authorization: Bearer $TOKENMP_ADMIN_BOT_KEY"
# 7. 按用户邮箱或用户 ID 片段查全站请求
curl -sS "$TOKENMP_BASE_URL/api/v1/bot/admin/request/list?query=thesumwai%40gmail.com&page=1&limit=20" \
-H "Authorization: Bearer $TOKENMP_ADMIN_BOT_KEY"
curl -sS "$TOKENMP_BASE_URL/api/v1/bot/admin/request/list?user_id=446655&page=1&limit=20" \
-H "Authorization: Bearer $TOKENMP_ADMIN_BOT_KEY"客服机器人推荐流程
- 先调用 /api/v1/bot/user/status，确认账号和 BOT KEY 可用。
- 额度问题调用 /api/v1/bot/user/quota，回答余额、套餐和窗口恢复时间。
- 模型问题调用 /api/v1/bot/user/model/list 或 /api/v1/bot/user/route/list。
- 请求报错先用 /api/v1/bot/user/request/list?query=<request_id> 查列表，再用 /api/v1/bot/user/request/trace?query=<trace_id> 定位单条链路。
- 兑换码只在用户明确提供 code 时调用 /api/v1/bot/user/redeem。
安全注意事项
- 不要向用户展示 BOT KEY、API KEY、key_hash、上游 key、JWT secret、数据库 URL 或内部 token。
- 面向客户的机器人默认使用用户 BOT；除非明确用于内部运营，不要接入管理 BOT。
- 用户 BOT 日志响应已隐藏 provider、upstream URL、request_body 和供应商私有错误细节。
- 泄露、离职交接或机器人下线时，应立即禁用或删除对应 BOT KEY。