Jev /v1/systemone

POST /v1/systemone 是 cc-router 的 Jev（System One）决策模型入口。Jev 是一类结构化决策模型：请求给出一段状态 state 和一组问题 questions，响应按问题逐个返回结构化答案 answers，不生成对话文本。

cc-router 把多家上游的 Key 聚合在独立的虚拟模型 model-jev 下：协议原样透传、不做翻译，但和对话入口一样享有多订阅调度、失败切换、冷却、限额与请求日志。

适用版本：cc-router v6.3.0 及以上。四个入口的对比见 接口总览。

Jev 不能给 Claude Code、Codex 这类对话工具用。它面向的是你自己的代码、Agent 框架，或任何能发 HTTP 请求的程序。

快速接入

配置项	填写
接口地址	http://127.0.0.1:23456/v1/systemone（写完整路径）
鉴权	Authorization: Bearer <token>，x-api-key: <token> 也可以
模型名	model-jev（可带 anthropic/ / openai/ 前缀），也可以直接写上游的真实模型名

命令行验证：

curl http://127.0.0.1:23456/v1/systemone \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <cc-router token>" \
  -d '{
  "model": "model-jev",
  "state": "Hello World",
  "questions": {
    "says_hello": {
      "type": "noul",
      "instructions": "Does the state text contain a greeting?"
    }
  }
}'

cc-router 的「虚拟模型」页有 model-jev 卡片，可以直接复制已填好地址与令牌的 curl 示例；「接入指南 → 通用接入方式」里也有 Jev 接入卡片。

Python（httpx）：

import httpx

resp = httpx.post(
    "http://127.0.0.1:23456/v1/systemone",
    headers={"Authorization": "Bearer <cc-router token>"},
    json={
        "model": "model-jev",
        "state": "用户说：上周买的耳机坏了，我要退款。",
        "questions": {
            "refund": {"type": "noul", "instructions": "Is the user asking for a refund?"},
        },
    },
    timeout=60,
)
print(resp.json()["answers"])

---

协议定位

客户端 (System One)                        cc-router                              上游
───────────────────        ──────────────────────────────────────         ──────────────
POST /v1/systemone ───────►│ 校验：JSON 对象 + model 是字符串       │
                           │   ↓                                  │
                           │ 只在 model-jev 的订阅里调度            │──► 选订阅 / 改写 model
                           │   ↓                                  │◄── 上游响应
                           │ 原样返回（只恢复 model 字段）          │
◄─────────── HTTP 响应 ─────│                                      │

和三个对话入口不同，/v1/systemone 不经过 Anthropic Messages 那条调度 pipeline，也不做任何协议翻译：

• 请求体除了 model 字段可能被改写，其余逐字节转发给上游。
• 响应体除了 model 字段可能被恢复，其余原样返回给客户端。
• 路由由路径决定：进了这个入口就固定走 model-jev，与请求体里写什么模型名无关。

---

请求

字段

cc-router 只做最小校验，其余字段交给上游校验（各家上游的校验规则本就不同）：

字段	cc-router 是否校验	说明
请求体整体	是	必须是 JSON 对象，否则返回 400
model	是	必须是字符串，否则返回 400 缺少 model 字段
state	否	待判断的状态，原样转发
questions	否	问题集合，键是问题 ID，值包含 type 与 instructions 等，原样转发
其他字段	否	原样转发

只支持非流式。stream: true 各家上游的处理不一致（有的报 400，有的忽略），不要依赖它。

model 的改写规则

每条 System One 订阅有一个可选的 Jev 模型槽。cc-router 按命中的那条订阅决定实际发给上游的 model：

客户端写的 model	订阅配置了 Jev 模型	订阅没配 Jev 模型
model-jev（或 anthropic/model-jev / openai/model-jev）	改写成配置的模型	改写成该接入点的示例模型（如 clef-flash、jev-latest）
上游的真实模型名（如 jev-preview）	改写成配置的模型	原样透传

改写过 model 时，响应里的 model 会恢复成客户端写的名字（例如仍回显 model-jev）；没改写时透传上游返回的具体版本名（例如 jev-latest 会被上游解析成 jev-1.13.0）。

上游地址里带 {model} 占位符的接入点（如 Cloudflare 的 /run/@cf/.../{model}），模型名只允许字母、数字和 . _ : -，且必须以字母或数字开头，否则返回 400。这是为了防止模型名拼进 URL 路径后访问到上游的其他接口。

---

响应

成功时返回上游的标准 System One 响应体，形如：

{
  "model": "model-jev",
  "answers": {
    "says_hello": { "type": "noul", "noul": 0.98 }
  },
  "usage": { "input_tokens": 160, "output_tokens": 0 }
}

• 答案的具体结构由问题的 type 决定，以上游文档为准。
• Cloudflare Clef 的原始响应包在 {result, success, errors, messages} 信封里，cc-router 会拆掉信封，统一成上面的标准形状；success: false 即使是 2xx 也按失败处理。
• usage 计入「数据统计」与「用量小票」（有用量时小票上才出现 model-jev）。

---

错误

cc-router 自己生成的错误采用 TypeSafe 官方的错误体形状：

{ "detail": { "error_type": "invalid_request_error", "message": "缺少 model 字段" } }

状态码	error_type	何时出现
400	invalid_request_error	请求体不是 JSON 对象、缺少 model、模型名含非法字符
401	—	cc-router 的 token 鉴权失败（与其他入口相同，Anthropic 风格错误体）
4xx	上游原样	所有候选订阅都失败，且最后一次失败是「请求本身写错了」：原样返回最后一家的错误
502	api_error	Cloudflare 返回 2xx 但信封里 success: false 或缺少 result
503	overloaded_error	model-jev 没有绑定任何订阅；或全部候选因网络、5xx、鉴权、限流、限额而不可用（message 里附每条订阅的状态摘要）

---

调度

• 只调度 System One 订阅：model-jev 只能绑定接入点为 System One 的订阅；对话类订阅不会被用到，System One 订阅也不会进入其他虚拟模型。
• 调度模式照常生效：顺序 / 轮询 / 会话亲和三种模式都可用，冷却、token 限额也和对话入口一样。
• 4xx 也会换下一家：实测各家上游对同一份请求的接受范围不同（未知模型有的返回 400、有的返回 404），所以某一家返回 4xx 时 cc-router 会继续尝试下一家，并且不冷却这家订阅。401 / 403 / 429 则视为订阅本身的状态问题：401 / 403 会把订阅标记为鉴权失败，429 会让订阅进入限流冷却。
• 会话亲和只认 x-session-id 请求头：不带就按轮询分配。cc-router 不会从请求体推导会话（相同的 state 也是彼此独立的决策）。

与对话入口的隔离

	对话入口（/v1/messages 等）	/v1/systemone
可用虚拟模型	model-fable / opus / sonnet / haiku / fallback	只有 model-jev
收到对方的模型名	对话入口收到 model-jev 直接返回 400	写什么都固定走 model-jev
可绑定的订阅	对话类订阅	System One 订阅
协议翻译	有（/v1/messages 除外）	无
GET /v1/models	列出	不列出 model-jev

内置上游

在 cc-router「添加订阅」里选下面任一厂商的 System One 接入点即可。厂商下拉里带 Jev 标签的就是支持决策模型的厂商。

厂商	说明
TypeSafe	Jev 模型的提供方。模型名手动输入：jev-latest（稳定）或 jev-preview（预览）。鉴权只认 Authorization: Bearer
Cloudflare Clef	Cloudflare 的决策模型，示例模型 clef-flash。可直连或经 AI Gateway：添加订阅时填账户 ID，经 AI Gateway 时还要填网关 ID；API Token 需要 Workers AI 权限（经 AI Gateway 时还需要 AI Gateway 权限）
OpenRouter	选它的 System One 接入点
Ollama	本地 System One 接入点，需要 Ollama 0.35 或更高版本

订阅创建后协议固定，不能在对话接入点和 System One 接入点之间切换，要换请新建订阅。

请求日志与隐私

每次尝试（包括切换到下一家的重试）记一行请求日志，「入口接口」显示 /v1/systemone。日志不记录 state、questions、answers、置信度和费用；上游 422 错误体里回显的整份请求也会在落库前去掉。