如何使用 Jev API

Jev 只暴露一个端点。你发送一个 state 和一组问题；它返回带概率的类型化答案。发起第一次调用所需的一切都在这里。

1. 端点

每个请求都是向 https://api.typesafe.ai/v1/systemone 发起的 POST，用 Bearer token 鉴权。官方 SDK 会从 TYPESAFE_API_KEY 环境变量读取你的 key。

curl

curl -X POST https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "Customer: I was charged twice and I am furious.",
    "questions": {
      "topic": {
        "type": "choice",
        "instructions": "What is the issue about?",
        "criteria": { "billing": "money problems", "bug": "broken product" }
      },
      "urgent": {
        "type": "noul",
        "instructions": "Escalate to a human now?"
      }
    }
  }'

2. 请求体

三个字段：

model——jev-latest，或者当你要微调阈值时锁定一个版本，例如 jev-1.13.0。
state——上下文，可以是字符串、JSON 对象或文本数组。与你的问题合计最多约 64k token。
questions——从问题名到问题对象的映射。它们全部在一次往返中被评估。

3. 三种问题类型

choice——挑一个选项

给出一个最多 255 个带标签选项的 criteria 映射。Jev 返回胜出的 key、每个选项的概率，以及一个置信度。

"topic": {
  "type": "choice",
  "instructions": "What is the primary issue?",
  "criteria": {
    "billing": "billing or payment problem",
    "bug": "the product is broken",
    "account": "login or access"
  }
}

score——在量表上定位

给出一个由 2–10 个等级描述组成的有序 criteria 数组。Jev 返回一个（可能带小数的）score 外加完整分布。

"severity": {
  "type": "score",
  "instructions": "How urgent is this?",
  "criteria": [
    "routine",
    "handle today",
    "urgent",
    "critical, about to churn"
  ]
}

noul——已校准的是/否

无需 criteria——只要 instructions。Jev 返回 noul，一个 0 到 1 之间的概率。

"escalate": {
  "type": "noul",
  "instructions": "Escalate to a human immediately?"
}

4. 响应

你会拿回解析出的 model、一个 answers 映射，以及 token 用量：

{
  "model": "jev-1.13.0",
  "answers": {
    "topic":    { "type": "choice", "choice": "billing",
                  "confidence": 1.0,
                  "probabilities": { "billing": 1.0, "bug": 0.0, "account": 0.0 } },
    "severity": { "type": "score", "score": 3.0, "confidence": 1.0,
                  "legend": { "0": "routine", "3": "critical, about to churn" },
                  "probabilities": { "0": 0.0, "3": 1.0 } },
    "escalate": { "type": "noul", "noul": 0.8 }
  },
  "usage": { "input_tokens": 434, "output_tokens": 75 }
}

由于类型是固定的，你可以用普通代码对结果做分支判断——if (answers.escalate.noul > 0.7)——无需解析、无需正则，也不会有响应格式错乱的风险。

5. 限制与最佳实践

速率限制：250,000 tokens/second 和 1,200 requests/minute。
上下文：state + 所有问题最多 64k token；state + 单个最长问题最多 32k。
如果你的阈值很重要，就在生产环境锁定版本——jev-latest 可能会改变行为。
把多个问题批量放进一次调用，而不是分多次；它们并行运行并共享 state 成本。
用 confidence 自动处理简单情形，只把不确定的路由给人工或更大的模型。

想要更省事的入口？

官方 Jev 访问需要 waitlist。如果你想要一个更简单、托管式的调用 Jev 方式——更高的演示额度、现成的端点、无需 waitlist——留下你的邮箱，告诉我们你想做什么。我们在动手之前先摸清需求。

想在写任何代码之前先看看它？本页的每个示例都在 playground 里实时运行。如需官方 key 与完整文档，请见 docs.typesafe.ai。

▶ 在 playground 里运行查看价格