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 文件

概觀

驗證

HTTP 端點

請求內容

問題類型

回應 JSON

計費

模型與限制

錯誤與重試

給 agent 用的 MCP server

從體驗到 API

用你的 key 呼叫 Jev。