[ 入门 ]
如何使用 Jev：
第一次 API 调用。
更新于 2026 年 10 月 16 日 · Jev Hub
[ Sponsors ]Launch price
These products help pay for Jev Hub. Want yours up here?
四种发出第一次调用的方式
TypeSafe AI 在它的quick start (opens in a new tab)里记录了四种方式，挑一个适合你的：
- Playground。 粘贴一段输入，加一个问题，直接在浏览器里看结果。不用写代码，是验证想法最快的方式。打开 Playground (opens in a new tab)。
- HTTP API。 向
https://api.typesafe.ai/v1/systemone发一个 POST 请求，带上你的 key 作为 Bearer token。 - Python SDK。
pip install typesafe-sdk（Python 3.10 及以上）。客户端默认从环境变量读取TYPESAFE_API_KEY，默认调用jev-latest。 - Agent skill。 如果是编程 agent 在写接入代码，TypeSafe 发布了一个 skill 教它用这个 API（
npx skills add typesafe-ai/skills --skill typesafe-ai）。
下面的步骤用 API 和 SDK 各演示一遍，例子是对一封邮件分类。
第一步：写问题
一次请求有三部分：要评估的输入（state）、model，以及一组 questions。每个问题属于三种类型之一：
- Choice：从你定义的一组选项里选一个，以“选项名 → 描述”的形式给出。
- Score：把输入放到一个你用文字描述的有序量表上。
- Noul：返回一个是非陈述为真的概率。
TypeSafe 的 Choice 文档 (opens in a new tab)里有两个细节能省不少调试时间：你起的问题 ID（下面的 category）模型是看不到的，所以完整的问题必须写进 instructions；选项名和描述都会一起发给模型，所以描述要写得能清楚区分每个选项。
{
"model": "jev-latest",
"state": "From: Dana Lee <dana@acme.io>\nSubject: Invoice #4471 charged twice\nBody: Our card was charged twice for March. Can you refund the duplicate today? Our finance close is tomorrow.",
"questions": {
"category": {
"type": "choice",
"instructions": "What kind of email is this?",
"criteria": {
"needs_reply": "A person expecting a response from us",
"updates": "Notifications, receipts, product updates",
"promotions": "Marketing and newsletters",
"spam": "Unwanted or suspicious mail"
}
},
"needs_human": {
"type": "noul",
"instructions": "Does this email involve money, legal risk or an upset customer?"
}
}
}第二步：调用 API
带上你的 key 发送请求。key 在 TypeSafe 的控制台里获取，步骤见 quick start。
curl -X POST https://api.typesafe.ai/v1/systemone \
-H "Authorization: Bearer $TYPESAFE_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json第三步：读懂响应
每个答案都放在你起的问题 ID 下面。以下数值仅作示例，结构以 TypeSafe 的 API 为准。
{
"model": "jev-1.13.0",
"answers": {
"category": {
"type": "choice",
"choice": "needs_reply",
"confidence": 0.84,
"probabilities": { "needs_reply": 0.91, "updates": 0.05, "promotions": 0.03, "spam": 0.01 }
},
"needs_human": { "type": "noul", "noul": 0.88 }
},
"usage": { "input_tokens": 212, "output_tokens": 31 }
}choice是被选中的选项，probabilities给出每个选项各自的概率。confidence把这组概率的形状压缩成一个 0 到 1 的数字：概率全部集中在一个选项上时为 1，平均分布时为 0。Score 类型的答案也带score、一份等级说明和一个置信度。noul是该陈述为真的概率，Noul 类型的答案不带置信度。usage报告输入 token 数，这是计费依据。
第四步：把置信度变成规则
这才是 Jev 真正派上用场的地方。TypeSafe 的置信度指南 (opens in a new tab)建议分三档处理：置信度高就自动执行，中间就谨慎处理或要求二次确认，低就转交人工或更强的模型。文档把 0.5 作为下限，并建议阈值要和做错的代价成正比——不可逆的操作应该设更高的门槛，只读操作可以放低。它也建议先保守一点，再用自己的数据去调。
from typesafe_sdk import Choice, Noul, TypeSafeClient
client = TypeSafeClient() # reads TYPESAFE_API_KEY from the environment
response = client.system_one(
state=email_text,
questions={
"category": Choice(
instructions="What kind of email is this?",
criteria={
"needs_reply": "A person expecting a response from us",
"updates": "Notifications, receipts, product updates",
"promotions": "Marketing and newsletters",
"spam": "Unwanted or suspicious mail",
},
),
"needs_human": Noul(instructions="Does this email involve money, legal risk or an upset customer?"),
},
)
category = response.answers["category"]
if category.confidence < 0.5:
route_to_human(email_text) # the model is genuinely unsure
elif category.choice == "spam":
archive(email_text)
else:
label(email_text, category.choice)第五步：把费用压下来
- 把问题批量发送。 同一个输入的多个问题放进一次请求，输入只会被读一次。
- 只发决策需要的内容。 输入长度是影响费用最大的因素。一封邮件的标题和前几百个词通常就够判断类别了。
- 先估算。 费用计算器（英文站）可以根据用量、输入长度和每条问题数估算月度账单。
调用 Jev 的其他方式
除了 TypeSafe 自己的 API，Jev 还可以通过 Vercel AI Gateway、OpenRouter 和 LiteLLM 调用。
从哪个场景开始
挑一个人工反复在做的决策：这张工单该给哪个团队、这条线索值不值得打电话、这条内容是不是垃圾信息。使用场景（英文站）列出了每种场景该问的问题和大致费用。想知道 Jev 和语言模型的区别，可以读 Jev 对比 ChatGPT 和 Claude（英文）。