什么时候使用 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 权限不足。
http
Authorization: Bearer bot-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json通用请求参数
| 参数 | 位置 | 是否必填 | 取值 | 说明 |
|---|---|---|---|---|
| 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 API 参数
用户 BOT 面向一个账号，只能读取 owner 自己的状态、额度、日志和设置。
| 方法 | 接口 | Query 参数 | JSON Body | 用途 |
|---|---|---|---|---|
| GET | /api/v1/bot/user/me | 无 | 无 | 查看 owner 和当前 BOT KEY 脱敏信息。 |
| GET | /api/v1/bot/user/status | 无 | 无 | 检查账号状态和 BOT KEY 可用性。 |
| GET | /api/v1/bot/user/quota | 无 | 无 | 查询 token、coding、image 余额和窗口刷新时间。 |
| GET | /api/v1/bot/user/overview | 无 | 无 | 读取用户 Panel 首页概览。 |
| GET | /api/v1/bot/user/usage | page, limit, ledger_type, billing_plan, query, request_model/model_name/model, from, to | 无 | 查询账单和用量流水。 |
| GET | /api/v1/bot/user/key/list | page, limit | 无 | 列出用户 API KEY 脱敏信息。 |
| POST | /api/v1/bot/user/key/toggle | 无 | {"id":"api_key_uuid","status":"active"} 或 {"id":"api_key_uuid","status":"disabled"} | 启用或禁用一个用户 API KEY。 |
| GET | /api/v1/bot/user/model/list | page, limit, query, status | 无 | 查询用户可见模型；status 可为 active 或 disabled。 |
| GET | /api/v1/bot/user/route/list | window, capability, query | 无 | 查询可调用模型路由和健康指标；window 支持 24h、7d、30d。 |
| GET | /api/v1/bot/user/request/list | page, limit, query, model_name/model, protocol, billing_plan, status, from, to | 无 | 查询用户自己的请求日志；query 支持请求 ID、Trace ID、日志 ID、owner 用户 ID 或 owner 邮箱模糊匹配；返回会隐藏上游内部信息。 |
| GET | /api/v1/bot/user/request/trace | query（必填） | 无 | 按 request_id、trace_id 或 request log id 查询单条链路。 |
| GET | /api/v1/bot/user/setting | 无 | 无 | 读取扣费偏好设置。 |
| POST | /api/v1/bot/user/setting/update | 无 | {"preferred_billing":"coding","fallback_enabled":true} | 更新 LLM 扣费偏好；preferred_billing 只能是 coding 或 token。 |
| POST | /api/v1/bot/user/redeem | 无 | {"code":"REDEEM-CODE"} | 为当前 owner 兑换兑换码；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、image_generation、tokenmp_gateway。
- route window 支持 24h、7d、30d；空值或非法值会按 24h 处理。
重点参数详解
下面是 BOT 最常用参数的实际填写方式。客服机器人优先使用 query、request_id、trace_id、user_id 这类稳定字段，不要让用户提交密钥或内部配置。
| 参数 | 适用接口 | 示例 | 说明 |
|---|---|---|---|
| query | request/list、request/trace、usage | req_abc123、trace_abc123、thesumwai@gmail.com、账单流水 ID、glm-5 | 模糊搜索请求 ID、Trace ID、request log id、用户 ID、owner 邮箱、ledger id、模型名或 reason；trace 接口中必填。 |
| model_name / model | request/list、usage | glm-5、glm-4.5、gpt-4o:fast | 按请求模型名过滤；request_model、model_name、model 在 usage 中都可作为模型过滤别名。 |
| ledger_type | usage | charge,recharge,plan_grant | 逗号分隔用量流水类型；客服常用 charge 查扣费，recharge 查充值，plan_* 查兑换码套餐到账。 |
| billing_plan | usage、request/list | coding、token、image | 按扣费计划过滤；图片生成用 image，普通文本模型通常是 coding 或 token。 |
| status | request/list、model/list | success、failed、pending；active、disabled | 请求日志状态使用 success/failed/pending；模型列表状态使用 active/disabled。 |
| from / to | usage、request/list | from=2026-05-01&to=2026-05-24 | 按时间范围过滤；YYYY-MM-DD 的 to 会包含当天整天，因为服务按次日 00:00 做排他上界。 |
| window | route/list | 24h、7d、30d | 路由健康统计窗口；用于回答某模型最近 24 小时或 7 天的成功率、耗时、可用路由。 |
| capability | route/list | chat、responses、messages、image | 按模型能力过滤路由列表；具体能力名称以平台模型配置为准。 |
| user_id | admin/user/*、admin/request/list | 550e8400-e29b-41d4-a716-446655440000 或 446655 | 管理 BOT 的 detail/quota/usage 需要完整用户 ID；request/list 和 user/request 支持用户 ID 片段模糊匹配。 |
| code | user/redeem | BETATEST、WELCOME-2026 | 兑换码明文。服务会 trim 并标准化；为空会返回 400 INVALID_PARAM 或 404 NOT_FOUND。 |
用户 BOT 可复制示例
下面示例假设已设置 TOKENMP_BASE_URL=https://api.tokenmp.cn 和 TOKENMP_BOT_KEY=bot-...。
bash
# 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。
| HTTP | error_code | 说明 |
|---|---|---|
| 404 | NOT_FOUND | 兑换码不存在，或提交后为空。 |
| 409 | REDEEM_CODE_INACTIVE | 兑换码已禁用或删除。 |
| 409 | REDEEM_CODE_EXPIRED | 兑换码已过期。 |
| 409 | REDEEM_CODE_EXHAUSTED | 兑换次数已用完。 |
| 409 | REDEEM_CODE_ALREADY_REDEEMED | 当前用户已经兑换过该兑换码。 |
| 409 | REDEEM_CODE_PLAN_DOWNGRADE | 兑换会降级当前套餐，因此被拒绝。 |
bash
curl -sS "https://api.tokenmp.cn/api/v1/bot/user/redeem" \
-H "Authorization: Bearer $TOKENMP_BOT_KEY" \
-H "Content-Type: application/json" \
--data '{"code":"BETATEST"}'设置更新示例
preferred_billing 控制 LLM 请求优先使用 coding 还是 token；fallback_enabled=true 表示首选计划额度不足时允许自动切换到另一个 LLM 计费计划。图片生成不受该设置影响。
bash
# 优先使用 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 参数
管理 BOT 可查询全站数据，只应在内部监控和运营机器人中使用。
| 方法 | 接口 | Query 参数 | JSON Body | 用途 |
|---|---|---|---|---|
| GET | /api/v1/bot/admin/me | 无 | 无 | 查看 admin owner 和当前 BOT KEY 脱敏信息。 |
| GET | /api/v1/bot/admin/status | 无 | 无 | 检查平台状态和安全配置摘要。 |
| GET | /api/v1/bot/admin/overview | 无 | 无 | 读取全站概览指标。 |
| GET | /api/v1/bot/admin/usage | days | 无 | 读取全站趋势；days 只能是 1、7、15，默认 7。 |
| GET | /api/v1/bot/admin/model/list | page, limit, query, status | 无 | 列出全站模型目录。 |
| GET | /api/v1/bot/admin/route/list | window, capability, query | 无 | 读取路由工作台聚合数据。 |
| GET | /api/v1/bot/admin/request/list | page, limit, query, user_id, model_name/model, provider_id, protocol, billing_plan, status, from, to | 无 | 查询全站请求日志；query 支持用户邮箱/用户 ID 模糊匹配，user_id 支持用户 ID 片段模糊过滤；会包含管理侧内部排障字段。 |
| GET | /api/v1/bot/admin/request/trace | query（必填） | 无 | 按请求 ID 或 Trace ID 查询全站链路。 |
| GET | /api/v1/bot/admin/user/detail | user_id（必填） | 无 | 查询指定用户资料。 |
| GET | /api/v1/bot/admin/user/quota | user_id（必填） | 无 | 查询指定用户额度。 |
| GET | /api/v1/bot/admin/user/usage | user_id（必填）, page, limit, ledger_type, billing_plan, query, request_model/model_name/model, from, to | 无 | 查询指定用户用量流水。 |
| GET | /api/v1/bot/admin/user/request | user_id（必填）, page, limit, query, model_name/model, provider_id, protocol, billing_plan, status, from, to | 无 | 按必填 user_id 片段模糊查询匹配用户的请求日志，并展示管理侧内部字段；query 也可匹配用户邮箱/用户 ID。 |
管理 BOT 可复制示例
下面示例假设已设置 TOKENMP_ADMIN_BOT_KEY=bot-...。管理 BOT 会看到更多内部排障字段，请只在内部系统中使用。
bash
# 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。