API Reference

API 参考

网关暴露四条路由，均监听 listen（默认 :7863）。/v1/* 走鉴权（Authorization: Bearer ${api_key}，api_key 为空时关闭鉴权）；/healthz 无需鉴权。

路由	方法	鉴权	说明
/v1/chat/completions	POST	✅	OpenAI 兼容对话（流式 / 非流式）
/v1/models	GET	✅	模型列表（CN + Global 双前缀）
/status	GET	✅	池与调度状态
/healthz	GET	❌	存活探针（带 X-Service 头）

服务标识：ServiceName = "workbuddy2api"。

---

POST /v1/chat/completions

OpenAI 兼容请求体，支持流式与非流式：

{
  "model": "deepseek-r1",
  "messages": [
    { "role": "user", "content": "hi" }
  ],
  "stream": false
}

请求体改写（网关侧）

网关在转发前对请求体做一组规范化改写：

改写	说明
强制流式	出站 stream: true（客户端非流式也如此），非流式响应由本地聚合
角色归一	developer → system
tool_choice 归一	规范化 tool_choice 格式
推理注入	DeepSeek 系模型：thinking.type=enabled + reasoning_effort 默认 high（disabled 时删除 effort 字段）
effort 降级	模型不支持的推理档位自动降级
reasoning 回填	多轮 assistant reasoning_content 一致性回填
指纹脱敏	features.sanitize_blacklist_fingerprints 开启时的出站请求体清洗
提示词替换	prompt.mode=custom 时用网关提示词替换所有 system/developer

响应

• 非流式：本地将上游 SSE 聚合为单个 OpenAI 响应，content / reasoning_content / tool_calls 合并；
• 流式：SSE 帧按规范白名单重建转发，data: [DONE] 保证恰好一个，tool_call 的 name 缺位回填；上游空流时返回错误帧 {"error":{"message":"empty upstream stream","type":"upstream_error"}}。

错误响应

错误按 Error-Handling 分类，经 applyErrorPolicy 套用惩罚后，返回形如：

{ "error": { "message": "...", "type": "..." } }

请求体上限

server.max_body_mb（默认 8MB），超限返回 413 request_body_too_large。

---

GET /v1/models

返回当前可用模型。响应为两族模型名列表：

{
  "object": "list",
  "data": [
    { "id": "cn:deepseek-r1", "object": "model", "created": 0, "owned_by": "..." },
    { "id": "global:gpt-5.4", "object": "model", "created": 0, "owned_by": "..." }
  ]
}

• CN：动态探测（1h 正缓存 / 5min 负缓存），失败回退静态表；cn: 前缀；
• Global：FetchGlobalModels 探测（1h TTL + 5min 负缓存），无 global 账号时不发起探测；global: 前缀；
• 两族只需模型名（无倍率）。

---

GET /status

池与调度状态（需要鉴权）。结构：

{
  "accounts": [
    {
      "uid": "...",
      "realm": "cn",
      "nickname": "...",
      "credits": 12345,
      "cooling": false,
      "cool_kind": "soft_rate",
      "cool_remaining_sec": 300,
      "until": "...",
      "reason": "...",
      "soft_streak": 1,
      "rate_limited_models": [
        { "model": "deepseek-r1", "until": "...", "reset_at": "...", "reason": "..." }
      ],
      "disabled": false,
      "disabled_reason": "",
      "success_count": 12,
      "err_total": 3,
      "last_success": "...",
      "last_err": "...",
      "in_flight": 1,
      "breaker_fails": 0,
      "breaker_until": ""
    }
  ],
  "total": 10,
  "healthy": 8,
  "cooling": 2,
  "disabled": 0,
  "in_flight_full": 0,
  "realm_totals": {
    "cn":  { "total": 6, "healthy": 5, "cooling": 1, "disabled": 0, "in_flight_full": 0 },
    "global": { "total": 4, "healthy": 3, "cooling": 1, "disabled": 0, "in_flight_full": 0 }
  },
  "sticky_sessions": 3,
  "redis_mode": "noop"
}

字段说明：

字段	含义
accounts[].uid	账号 UID（脱敏取前 8 位）
accounts[].realm	cn / global
accounts[].credits	当前积分
accounts[].cooling / cool_kind / cool_remaining_sec	冷却状态 / 类型（hard_credit / soft_rate）/ 剩余秒
accounts[].soft_streak	连续软冷却次数（退避指数）
accounts[].rate_limited_models	限额台账：仍被 6004 限流的模型（见 Pool-Mechanism），到期即消失
accounts[].disabled / disabled_reason	是否永久禁用及原因（运维可见）
accounts[].success_count / err_total / last_success / last_err	成功率观测
accounts[].in_flight / breaker_fails / breaker_until	运行态：在途请求 / 熔断失败计数 / 熔断截止
total / healthy / cooling / disabled / in_flight_full	全池五类计数；in_flight_full 是 healthy 中已达在途上限的子集
realm_totals.{cn,global}	按 realm 分组的同五类计数
sticky_sessions	当前会话粘性绑定数
redis_mode	redis / noop（是否启用 Redis 镜像）

---

GET /healthz

存活探针，无鉴权。响应：

{
  "healthy": true,
  "total": 10,
  "service": "workbuddy2api",
  "realm_servable": { "cn": true, "global": true }
}

• 响应头带 X-Service: workbuddy2api；
• healthy = 池存在至少一个「对任意模型可服务」的账号（healthy 或模型豁免形态，且未占满在途名额）；
• realm_servable.{cn,global} = 各域是否可服务（与 chat 真实可达性同口径，避免「全账号 healthy 但都占满」时误报 200）；
• 探活不考虑请求模型上下文：6004 模型级冷却中的账号至少还剩触发模型之外的模型可用，计入可服务。