Jev API 教程：从零调用 TypeSafe Jev 决策接口

一、三步跑通第一个 Jev API 请求

Jev（TypeSafe AI 推出的首个 System One 模型）专门解决代码里的“模糊 if”分支：客服工单该分给谁、Agent 的工具调用安不安全、哪条评论需要先审、这次请求该路由给便宜模型还是旗舰模型。

与传统大模型不同，Jev 不返回需要你用正则或 JSON Schema 去解析的自然语言，而是直接返回带校准概率的 choice、score 或 noul。在国内接入只需三步：

• 第 1 步：打开 /zh/playground/ 在线调试你的 state 与问题定义，免登录赠送 1 万输入 token。
• 第 2 步：登录 /zh/dashboard/（即送 10 万免费输入 token），点击「+ 新建 key」生成 sk- 开头的密钥。
• 第 3 步：在服务端向 https://jevmodel.org/v1/systemone 发送 POST 请求。以下是把工单分派、紧急度打分和是否转人工合并在一次调用里的完整 cURL：

curl -X POST https://jevmodel.org/v1/systemone \
  -H "Authorization: Bearer $JEVMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-20261105-001" \
  -d '{
    "model": "jev-latest",
    "state": "用户反馈：昨天微信支付扣款了两次 ¥49，要求立刻退回多扣的一笔，否则投诉。",
    "questions": {
      "department": {
        "type": "choice",
        "instructions": "这张工单应该分派给哪个组？",
        "criteria": {
          "billing": "充值、扣费、发票、退款相关问题",
          "tech": "API 报错、超时、SDK 接入故障",
          "account": "登录、验证码、密码重置"
        }
      },
      "urgency": {
        "type": "score",
        "instructions": "评估用户情绪与紧急程度",
        "criteria": ["常规咨询", "轻微不满", "紧急且有投诉风险", "严重生产事故"]
      },
      "escalate_human": {
        "type": "noul",
        "instructions": "是否需要人工客服在 15 分钟内介入处理？"
      }
    }
  }'

二、四大问题类型（choice / score / noul / box）怎么选

写 Jev 请求的核心是把业务判断拆解成正交的具名问题。不要问“请分析这张工单”，而是问代码下一步分支真正需要的变量：

• choice（多选一路由）：定义 2–20 个固定标签及简短判据（criteria 对象），返回选中的 choice、每个选项的 probabilities 分布与 confidence。最适合意图识别、队列分发、模型路由。
• score（有序量表打分）：定义 2–10 个从低到高的等级说明（criteria 数组），返回连续浮点分值（如 2.4）与 confidence。最适合线索质量、风险评级、内容审核优先级。
• noul（是/否校准概率）：直接返回 0 到 1 之间的 noul 概率值（即 P(yes)）。无需再套一层置信度，直接在代码里写 if (ans.noul >= 0.85) 即可做拦截或放行。
• box（图像目标定位 · Jev 1.14）：配合 assets 传入 base64 图片并将 model 设为 jev-preview，返回目标在图中的归一化坐标 {top, bottom, left, right}（0~1），适合 UI 自动化点击与视觉质检。

三、Python 实战代码与阈值分支模式

Jev 的 HTTP 契约极简，不需要安装厚重的专用 SDK，标准 requests 或 httpx 20 行代码即可投入生产。建议在生产代码中把 model 固定为具体版本（如 jev-1.13.0 或 jev-1.14.0），并对低置信度结果做兜底：

import os
import requests

API_KEY = os.environ["JEVMODEL_API_KEY"]
ENDPOINT = "https://jevmodel.org/v1/systemone"

def evaluate_ticket(ticket_text: str) -> dict:
    payload = {
        "model": "jev-1.13.0",  # 生产环境建议固定版本号
        "state": ticket_text,
        "questions": {
            "route": {
                "type": "choice",
                "instructions": "选择处理队列",
                "criteria": {
                    "refund": "明确要求退款或争议账单",
                    "support": "普通产品使用问题",
                    "spam": "广告或无关内容"
                }
            },
            "auto_approve_eligible": {
                "type": "noul",
                "instructions": "如果是小额重复扣款，是否满足自动退款初审条件？"
            }
        }
    }
    resp = requests.post(
        ENDPOINT,
        json=payload,
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        timeout=10,
    )
    resp.raise_for_status()
    return resp.json()

result = evaluate_ticket("订单 #9821 重复扣款，请退回第二笔。")
answers = result["answers"]
if answers["route"]["choice"] == "refund" and answers["auto_approve_eligible"]["noul"] >= 0.85:
    print("触发自动退款工单流，剩余额度：", resp_tokens := result.get("usage", {}).get("input_tokens"))

四、Node.js / TypeScript 与 Agent 护栏示例

在 AI Agent（如 Claude Code、Cursor、LangGraph 或自研工作流）中，最常见的做法是在执行高风险动作前先调一次 Jev。每个 200 响应头都会附带 X-Tokens-Remaining，方便你在应用侧实时监控剩余额度：

// Node.js / TypeScript 调用 Jev API 示例（零依赖 fetch）
const response = await fetch("https://jevmodel.org/v1/systemone", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.JEVMODEL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "jev-latest",
    state: {
      tool: "bash",
      command: "rm -rf ./dist && pnpm build",
      cwd: "/srv/app"
    },
    questions: {
      safe_to_run: {
        "type": "noul",
        "instructions": "该命令是否安全？删除项目外目录、读取密钥或强推分支均视为不安全。"
      }
    }
  }),
});

const data = await response.json();
const pSafe = data.answers.safe_to_run.noul; // 0 ~ 1 之间的校准概率
const remaining = response.headers.get("x-tokens-remaining");

五、生产环境避坑与计费优化建议

我们在上百万次真实 API 调用中总结了以下四条能显著降低成本、提升稳定性的经验：

• 合并同源问题：针对同一份 state 的多个判断（例如“属于哪个分类”+“是否紧急”+“是否含敏感词”）尽量放在同一个请求的 questions 对象里，减少网络往返。
• 善用 Idempotency-Key：网络抖动重试时，在请求头带上唯一的 Idempotency-Key（最长 100 字符），24 小时内相同 key 的重试直接返回缓存结果，绝不重复扣费。
• 英文 instructions 准确度更高：虽然 Jev 可以直接读取中文 state（如中文工单、评论、对话），但TypeSafe 官方说明模型以英文语料训练为主，把 instructions 和 criteria 写成清晰的英文往往能获得更稳的校准概率。
• 高频调用选订阅更省钱：单次入门包 ¥49（1,500 万 token）适合验证与低频项目；一旦日调用量上来，切换到 Creator 或 Studio 套餐可将每百万 token 成本降低 50%~78%，且未用完额度自动顺延。