概觀
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: Bearer $JEVMODEL_API_KEY key 綁定帳戶 token 餘額,可在控制台撤銷。不要把 key 寫進前端程式或提交到版本庫——外洩後立即撤銷並新建。線上體驗使用已登入的瀏覽器工作階段,不需要 key。
HTTP 端點
向評估端點送出帶 Bearer 驗證的 JSON 請求內容:
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 -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 | 必填。序列化後最長 1,000,000 字元。 |
questions | object | 必填,1–8 個問題名到型別化定義的對映。名稱為識別符:字母、數字與 _,最長 64 字元。 |
assets | object | 可選(實驗性)。最多 4 張 PNG/JPEG 圖片,以引用名為鍵,並在 state、instructions 或 criteria 中寫出該引用名。見圖像與 Box。 |
每個問題需要 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。 |
box | 不使用 — 僅 instructions。 | 回傳歸一化邊緣(top/bottom/left/right,0–1)與 confidence 的 box。實驗性;需 jev-preview。 |
序列化 criteria 每題最長 2,000 字元。驗證失敗在預留 token 前回 422——錯誤請求不計費。
圖像與 Box(實驗性)
Jev 1.14 支援將 PNG/JPEG 圖片作為判斷輸入——這是圖像理解,不是圖像生成。在 assets 中以引用名附加圖片,然後在 state、問題的 instructions 或 criteria 中寫出該引用名;引用會在該位置解析為圖片。圖像與 Box 請求需要預覽模型——將 model 設為 jev-preview。
{
"model": "jev-preview",
"state": "Shipment photo attached as img-1.",
"assets": {
"img-1": { "type": "image", "format": "jpg", "data_base64": "/9j/4AAQSkZJRg…" }
},
"questions": {
"damage_visible": {
"type": "noul",
"instructions": "Is there visible damage to the package in img-1?"
},
"damage_region": {
"type": "box",
"instructions": "Locate the damaged area in img-1"
}
}
} assets把引用名映射到{ "type": "image", "format": "png|jpg", "data_base64": "…" }——最多 4 張,編碼後每張約 4 MB。- 每個 asset 必須被引用,且每次引用都計費——圖像與文字一樣計入
usage.input_tokens。 box只接受instructions,且總是回傳一個框——當目標可能不在圖中時,搭配一個「X 是否可見」的 noul 問題。- 這是 opt-in 的實驗性功能:請求攜帶 assets 或 box 問題時,代理會自動附加上游 opt-in 標頭。不支援 multipart 上傳——請發送 base64。
音訊和影片仍不支援——請先轉換為文字或結構化資料。
回應 JSON
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((state + question).length / 4)(state 按每個問題各計一次)。
模型與限制
jev-latest 為目前預設且實際提供的模型——model 欄位選填。體驗頁中展示的 Laya 變體即將推出,尚未透過此端點開放。
| 限制 | 數值 |
|---|---|
| 每次請求問題數 | 8 |
| 問題名 | 識別符 ≤ 64 字元 |
序列化 state | 1,000,000 字元 |
每題 instructions | 1,800 字元 |
| Choice 選項數 / Score 級數 | 2–20 選項,2–10 級 |
序列化 criteria | 每題 2,000 字元 |
| 限流 | 每 key 120 次 / 分鐘 |
每次請求圖片數(assets) | 4 |
| 圖片格式 / 大小 | base64 編碼的 PNG 或 JPEG,每張 ≤ 約 4 MB |
| 圖片尺寸 | 每邊 256–1,568 px |
以上為本 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 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 工具頁。
從體驗到 API
先在線上體驗裡搭好場景——請求預覽展示應用應送出的完整 JSON,Copy API example 給出對應 cURL。答案滿意後在控制台建 key,把瀏覽器工作階段換成 Bearer 驗證。
延伸閱讀:Jev 使用教學完整走完第一次呼叫,Jev API 範例有每種問題類型的生產寫法。