Jev API 文档：端点、请求体与响应字段

概览

Jev 把你传入的一段 state——工单、聊天记录、工具调用、任何文本或 JSON——对一组类型化问题求值，返回代码可直接分支的结构化答案。它不生成文本。

一次请求最多可问 8 个问题；它们一起求值并共享 state 的输入成本。请求体与 TypeSafe SystemOne API 相同——迁移现有集成只需换掉 base URL 和 Bearer key。

POST https://jevmodel.org/v1/systemone —— 唯一的决策端点。
CORS 开放（access-control-allow-origin: *），任何来源都能调用。即便如此，key 仍应放在服务端。
在线体验通过浏览器会话发送完全相同的请求体——预览的内容就是你要发送的内容。

认证

每次 API 调用都需要 jevmodel.org 的 API key。在控制台 → API keys 创建；key 以 sk- 开头，只在创建时显示一次。请存为环境变量，例如 JEVMODEL_API_KEY。

Authorization 请求头

Authorization: Bearer $JEVMODEL_API_KEY

key 绑定账户 token 余额，可在控制台吊销。不要把 key 写进前端代码或提交到仓库——泄露后立即吊销并新建。在线体验使用已登录的浏览器会话，不需要 key。

HTTP 端点

向评估端点发送带 Bearer 认证的 JSON 请求体：

HTTP 请求

POST /v1/systemone HTTP/1.1
Host: jevmodel.org
Authorization: Bearer $JEVMODEL_API_KEY
Content-Type: application/json
Idempotency-Key: ticket-4821-run-1   # optional

Idempotency-Key 可选（最长 100 字符）。使用相同 key 的重试复用原始计费记录，重试不会对同一输入重复扣费。

完整 cURL 示例

curl -X POST https://jevmodel.org/v1/systemone \
  -H "Authorization: Bearer $JEVMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "The customer has been billed twice and wants a refund today.",
    "questions": {
      "route": {
        "type": "choice",
        "instructions": "Which queue should own this ticket?",
        "criteria": {
          "billing": "Payments, refunds, invoices",
          "technical": "Product errors and usage problems",
          "sales": "Pricing, upgrades, new business"
        }
      },
      "escalate": {
        "type": "noul",
        "instructions": "Does this need a human right now?"
      },
      "urgency": {
        "type": "score",
        "instructions": "How urgent is this for the customer?",
        "criteria": ["routine", "soon", "urgent", "critical"]
      }
    }
  }'

请求体

一个包含 state 和 questions 映射的 JSON 对象：

请求体

{
  "model": "jev-latest",
  "state": "The customer has been billed twice and wants a refund today.",
  "questions": {
    "route": {
      "type": "choice",
      "instructions": "Which queue should own this ticket?",
      "criteria": {
        "billing": "Payments, refunds, invoices",
        "technical": "Product errors and usage problems",
        "sales": "Pricing, upgrades, new business"
      }
    },
    "escalate": {
      "type": "noul",
      "instructions": "Does this need a human right now?"
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is this for the customer?",
      "criteria": ["routine", "soon", "urgent", "critical"]
    }
  }
}

字段	类型	说明
`model`	string	可选；默认 `jev-latest`。
`state`	string、object 或 array	必填。序列化后最长 8,000 字符。
`questions`	object	必填，1–8 个问题名到类型化定义的映射。名称为标识符：字母、数字和 `_`，最长 64 字符。

每个问题需要 type 和 instructions（最长 1,800 字符），告诉模型要判断什么。criteria 提供答案空间——choice 和 score 必填，noul 可选。

问题类型

选择你的应用能直接使用的答案形态。

类型	Criteria	答案
`noul`	可选的 `true` / `false` 标签说明。	`noul` —— 答案为“是”的概率，0 到 1。
`choice`	2–20 个选项键到说明的对象。	选中的 `choice`、`probabilities` 分布和 `confidence`。
`score`	有序的 2–10 级数组。	数值型 `score`（可为小数）和 `confidence`。

序列化 criteria 每题最长 2,000 字符。校验失败在预留 token 前返回 422——错误请求不计费。

响应 JSON

200 响应就是模型输出本身：解析出的模型、按问题名返回的答案和用量。下面的数值是示意——实际输出以真实请求为准。

200 响应示例

{
  "model": "jev-latest",
  "answers": {
    "route": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.93, "technical": 0.05, "sales": 0.02 },
      "confidence": 0.93
    },
    "escalate": {
      "type": "noul",
      "noul": 0.12
    },
    "urgency": {
      "type": "score",
      "score": 1.4,
      "confidence": 0.88
    }
  },
  "usage": { "input_tokens": 136, "output_tokens": 18 }
}

answers 以你的问题名为键——只读你问的字段。
choice 按选中标签分支，需要完整分布时查看 probabilities。
noul 是 P(yes)——阈值由你的代码决定。
usage.input_tokens 是这次调用实际扣费量；输出 token 免费。

计费

API 只对输入 token 计费——输出免费。每次调用先按预估预留，再按模型报告的 usage.input_tokens 结算。上游失败时预留全额自动退回。

登录即送 100,000 免费输入 token；付费包 $9.90 起，永不过期。
余额不足在调用 Jev 前返回 402。
每个 200 响应的 X-Tokens-Remaining 是结算后余额。
自行估算：ceil(JSON.stringify({state, questions}).length / 4)。

模型与限额

jev-latest 是当前默认且实际提供的模型——model 字段可选。体验页里展示的 Laya 变体即将上线，暂未通过此端点开放。

限额	数值
每次请求问题数	8
问题名	标识符 ≤ 64 字符
序列化 `state`	8,000 字符
每题 `instructions`	1,800 字符
Choice 选项数 / Score 级数	2–20 选项，2–10 级
序列化 `criteria`	每题 2,000 字符
限流	每 key 120 次 / 分钟

以上为本 API 校验器的限制；上游模型可能还有自己的上下文上限。

错误与重试

错误返回带机器可读 type 和人类可读 message 的 JSON 包：

错误响应

{
  "error": {
    "type": "invalid_request_error",
    "message": "At most 8 questions per request."
  }
}

状态码	类型	原因	是否扣费
`401`	`authentication_error`	key 缺失、无效或已吊销。	否
`402`	`insufficient_credits`	预估输入 token 超过余额。	否
`422`	`invalid_request_error`	请求体未通过校验——见 `message`。	否
`429`	`rate_limit_error`	本分钟超过 120 次。	否
`502`	`upstream_error`	Jev 未能完成调用。	否——已退款

429 和 502 用指数退避重试——限流窗口按分钟计，短暂等待通常足够。重试时带上 Idempotency-Key，重复请求会按同一计费记录结算而非重复扣费。

给 agent 用的 MCP server

jevmodel.org 在 https://jevmodel.org/mcp 提供远程 MCP server（Streamable HTTP）。暴露四个工具——jev_decide（完整 state+questions 契约）、jev_noul、jev_choice、jev_score——Claude Code、Cursor、Cline 等编码 agent 无需手写 HTTP 即可调用 Jev。

Claude Code

claude mcp add --transport http jev https://jevmodel.org/mcp \
  --header "Authorization: Bearer $JEVMODEL_API_KEY"

与本 API 相同的 Authorization: Bearer sk-… key 和同一个 token 余额——tools/call 只对输入 token 计费。
initialize、ping、tools/list 无需认证；只有 tools/call 使用你的 key。
GET /mcp 返回给 agent 和人看的 JSON 发现卡片。

Claude Code、Cursor 的接入命令以及配套的 agent skill（判断方法手册）在 Agent 工具页。

Agent 工具指南

从体验到 API

先在在线体验里搭好场景——请求预览展示应用应发送的完整 JSON，Copy API example 给出对应 cURL。答案满意后在控制台建 key，把浏览器会话换成 Bearer 认证。

延伸阅读：Jev 使用教程完整走完第一次调用，Jev API 示例有每种问题类型的生产写法。

Jev API 文档

概览

认证