← 获取 Jev

API 参考

你买的是通用 Decision API。给 `/v1/decide` 传一个 `state` 和带类型的 `questions`,拿回校准过的 `answers`——拿它做什么由你决定。下面的现成端点只是常见场景的可选 shortcut,你不用等我们替你加。

调用多个决策模型(Clef / OpenAI Decisions)?看多模型 API →

鉴权

所有端点用同一个 Bearer key。在定价页创建(登录、预付一小笔余额)。key 形如 jv_live_…。把它留在服务端、放进环境变量,别提交到代码库或暴露在前端。

Authorization: Bearer jv_live_your_key_here
Content-Type: application/json

核心 API —— /v1/decide

这才是产品本体。一次调用:一个 state 加带类型的 questions,拿回校准过的 answers。下面的一切(以及每个现成 API)都只是它加上一组固定的问题。

POST https://jevtypesafeai.com/api/v1/decide

请求体

  • model —— jev-latest(默认),或钉住某版本如 jev-1.13.0。box 问题及其它视觉功能需要 jev-1.14.0(或 jev-preview)。我们绝不替你改动模型。可选。
  • state —— 要评估的输入:字符串、对象或数组。必填。
  • questions —— 「名字 → 带类型问题」的映射(choice、score、noul 或 box),一次往返并行评估。必填。
  • assets —— 可选,「引用名 → 图片」的映射,用于视觉请求(见下)。字段名沿用 TypeSafe 原生命名;我们整体转发请求体——包括官方未来新增的任何字段——原样不动。

三种问题类型

每个问题恰好是其中之一。一次调用可任意混用。

choice —— 选出一个选项

一个 criteria 映射,最多 255 个带标签选项。Jev 返回胜出的 choice、每个选项的 probability,以及 confidence。

"route": {
  "type": "choice",
  "instructions": "Where should this ticket go?",
  "criteria": {
    "billing": "payments, refunds, invoices",
    "bug": "the product is broken",
    "account": "login or access"
  }
}
// → { "type":"choice", "choice":"billing", "confidence":0.99,
//     "probabilities": { "billing":0.99, "bug":0.0, "account":0.01 } }

score —— 在有序刻度上打分

一个有序的 criteria 数组,2–10 个由低到高的具体等级描述。Jev 返回(可能带小数的)score、每级 probabilities、legend 和 confidence。

"urgency": {
  "type": "score",
  "instructions": "How urgent is this message?",
  "criteria": ["routine, no rush", "today", "urgent", "critical, about to churn"]
}
// → { "type":"score", "score":2.97, "confidence":1.0,
//     "probabilities": { "0":0.0, "3":1.0 } }

noul —— 校准过的是/否

只要 instructions。Jev 返回 noul——答案为「是」的校准 0–1 概率。非常适合门控与护栏。

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

提示:state 可以是字符串、对象或数组——只发决策需要的上下文。有两个输入预算:state 加全部问题合计最多 64k tokens,且 state 加最长的单个问题最多 32k tokens。要把两者都提到 ~262k,发 TypeSafe-Danger-Zone-Long-Context: true 头(单 token 价格不变)。超过该上限上游模型会返回 max_tokens_exceeded——请精简 state 或拆分请求,我们不会替你截断。

视觉与进阶功能Preview

上游 TypeSafe 的预览功能,按请求通过官方 TypeSafe-Danger-Zone-* 头自行开启。你发头、你选 model,我们都原样转发、不加任何东西——字段名和 header 名都用 TypeSafe 原生命名,没有我们自己的便利包装。属预览期:形状与限制可能变动。

图片Preview

把每张图片放进顶层 assets 映射,用一个引用名作 key,再从 state、某问题的 instructions 或 criteria 里引用这个名字。走 HTTP 时每个 asset 是 { "type":"image", "data_base64":"…", "format":"png"|"jpg"|"jpeg" }(官方 SDK 则用 multipart part)。必须带 TypeSafe-Danger-Zone-Images: true 头——不带会被拒。图片按普通 input token 计费。Jev 1.13 和 1.14 都接受图片。

box —— 在图片里定位目标Preview

box 问题返回所描述目标的位置:一个 box,含 top/bottom/left/right,均为从左上角起算的 0–1 比例值,另加 confidence。它永远返回一个框(没有「没找到」)——配一个 noul 判断目标是否真的存在。box 需要 model: "jev-1.14.0"(或 jev-preview)以及图片头。

# Images + Box are opt-in: send this header or the request is rejected.
#   TypeSafe-Danger-Zone-Images: true

{
  "model": "jev-1.14.0",                       // box requires jev-1.14.0 / jev-preview
  "state": { "photo": "kitchen-1" },           // reference the image by name
  "assets": {
    "kitchen-1": { "type": "image", "data_base64": "<base64 png/jpg>", "format": "jpg" }
  },
  "questions": {
    "mug": { "type": "box", "instructions": "the coffee mug in `photo`" }
  }
}
// → "answers": { "mug": { "type":"box",
//      "box": { "top":0.25, "bottom":0.82, "left":0.44, "right":0.84 },  // 0–1 fractions, top-left origin
//      "confidence":0.92 } }

长上下文

发 TypeSafe-Danger-Zone-Long-Context: true 头把两个输入预算都提到 ~262k tokens,单 token 价格不变。我们只转发这个头,绝不替你设置。

示例请求

curl https://jevtypesafeai.com/api/v1/decide \
  -H "Authorization: Bearer $JEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "Customer: I was charged twice and nobody has replied for 3 days.",
    "questions": {
      "route":    { "type": "choice", "instructions": "Where should this go?",
                    "criteria": { "billing": "money", "bug": "broken", "account": "login" } },
      "urgency":  { "type": "score",  "instructions": "How urgent is this?",
                    "criteria": ["routine", "today", "urgent", "critical"] },
      "escalate": { "type": "noul",   "instructions": "Escalate to a human now?" }
    }
  }'
测试你的 key —— 用你的 key 把这个请求原样打一次到线上端点:
把上面的请求发到 https://jevtypesafeai.com/api/v1/decide(带你的 key),会计一次极小的决策费用(≈ $0.00003)。key 只留在你的浏览器里。生产环境请把它放在服务端。

响应

你会拿回解析后的 model、按你的问题名索引的 answers 映射,以及 usage 块。因为每个答案类型由请求固定,你用普通代码直接分支——无需解析、无需正则。

{
  "model": "jev-1.13.0",
  "answers": {
    "route":    { "type": "choice", "choice": "billing", "confidence": 0.99,
                  "probabilities": { "billing": 0.99, "bug": 0.0, "account": 0.01 } },
    "urgency":  { "type": "score", "score": 3.0, "probabilities": { "0": 0.0, "3": 1.0 } },
    "escalate": { "type": "noul", "noul": 0.94 }
  },
  "usage": { "input_tokens": 62, "cost_usd": 0.000026, "credits_remaining_usd": 4.999974 }
}

错误码

  • 400 —— 请求校验失败;error 字段说明原因。
  • 401 —— API key 缺失、无效或已吊销。
  • 402 —— 余额不足(code: "insufficient_credits")。
  • 403 —— 账户未激活。
  • 404 —— 未知的应用端点。
  • 413 —— 请求体过大(~32 MiB 上限,含图片)。
  • 415 —— 不支持的 Content-Encoding(可用 identity、gzip、deflate、zstd)。
  • 502 —— 上游 Jev 错误;带退避重试。

最佳实践

  • 有合适的应用端点就用它;只有需要自定义决策时才用 /decide。
  • 把 state 精简到决策需要的内容——按 input token 付费。
  • 生产环境钉住模型版本,避免阈值漂移。
  • 把 jv_live_ key 留在服务端。
  • 请求体可用 gzip 或 zstd 压缩(Content-Encoding)——官方 SDK 默认就会压。

现成 API

可选的 shortcut。有合适的就按示例传普通字段、省去自己写问题——拿回干净带类型的结果和 usage 块。没有合适的就用上面的 /v1/decide,你永远不受我们的 preset 限制。字段错误返回 400,并附 expects 示例。

邮件

POST /api/v1/email/triage— 邮件分诊

对收到的邮件分类:类别、优先级、是否垃圾、是否需要回复、路由到哪个团队。

# request
{"subject":"Charged twice","body":"I was charged twice and need this fixed today."}

# response
{"category":"billing","priority":"urgent","spam":false,"needs_reply":true,"route_to":"finance","confidence":0.96}

客服工单

POST /api/v1/support/triage— 工单分诊

路由支持工单:团队、问题类型、严重度、紧急度、是否立即升级。

# request
{"subject":"App is down","body":"Production dashboard returns 500 for all users since 10am."}

# response
{"team":"technical","issue_type":"outage","severity":"critical","urgency":"now","escalate":true,"confidence":0.99}

Agent

POST /api/v1/agent/risk— Agent 风险门控

对 Agent 将要执行的工具调用做门控:allow / confirm / block、0–1 风险分、风险类别。

# request
{"goal":"Clean up the build directory","tool":"bash","arguments":"rm -rf ./dist && aws s3 sync ./build s3://prod --delete","context":"CI deploy step"}

# response
{"action":"block","risk":0.84,
 "categories":["destructive","irreversible","external_side_effect","data_exposure"],"confidence":0.6}

编程 Agent

POST /api/v1/context/filter— 上下文过滤

对 Agent 历史里的一条旧上下文决定 keep / truncate / drop,对抗上下文膨胀。

# request
{"task":"Fix the failing payment webhook test","item":"Tool call: read_file('README.md') -> 4000 tokens of project overview from 30 steps ago"}

# response
{"action":"drop","relevance":"minor","redundant":true,"confidence":0.53}

LLM 路由

POST /api/v1/model/route— 模型路由

按提示词复杂度选择模型档位;传入 models[] 可直接返回具体模型名。

# request
{"prompt":"Summarize this 2-sentence email in one line.","models":["fast-mini","balanced","frontier"]}

# response
{"recommended_tier":"fast","complexity":"simple","recommended_model":"fast-mini","confidence":0.78}

RAG 检索

POST /api/v1/rag/relevance— RAG 相关性

判断一段召回的文本是否真的回答了查询——用于重排与过滤。

# request
{"query":"How do I rotate my API key?","passage":"To rotate a key, open Settings > API keys, click Revoke on the old key, then Create new key. Update your environment variable."}

# response
{"relevant":true,"relevance":"direct answer","supports_claim":true,"confidence":1.0}

销售

POST /api/v1/leads/qualify— 线索评级

对进来的销售线索评级:是否合格、ICP 匹配、分层、是否在购买期、路由。

# request
{"lead":"Jane Doe, VP Eng at Acme (500 employees). 'We're evaluating decision APIs to replace a brittle rules engine — hoping to pick something this quarter.'"}

# response
{"qualified":true,"icp_match":"ideal","segment":"mid_market","buying_now":true,"route":"sales","confidence":0.83}

内容审核

POST /api/v1/content/moderate— 内容审核

审核用户文本:allow / review / block、各类别标记、命中的违规项。

# request
{"text":"You're an idiot and I'll find where you live."}

# response
{"action":"block",
 "flags":{"toxicity":true,"harassment":true,"violence":true,"sexual":false,
   "self_harm":false,"spam":false,"fraud":false,"pii":false},
 "violation_types":["toxicity","harassment","violence"],"confidence":0.69}

内容

POST /api/v1/content/classify— 内容分类

给任意帖子打标签:主题、格式、开头钩子、语气、互动潜力。

# request
{"text":"I quit my $200k job to sell candles. Here's what nobody tells you about starting a business 🧵"}

# response
{"topic":"business","format":"listicle","hook_style":"bold_claim","tone":"inspirational","engagement_potential":"very high","confidence":0.82}

社媒

POST /api/v1/social/post-analyze— 社媒帖子分析

评估帖子的钩子、是否制造悬念、是否有实据,以及传播潜力。

# request
{"post":"Most people fail at cold email because they lead with themselves. I sent 1,000 and the ones that worked all did the opposite. Here's the exact template."}

# response
{"hook":"scroll-stopping","opens_loop":true,"has_evidence":true,"format":"how_to","viral_potential":"high","confidence":0.66}

广告

POST /api/v1/ads/analyze— 广告分析

给广告打标签:钩子类型、认知阶段、是否有明确 offer、CTA、阻力。

# request
{"headline":"Stop losing leads to slow follow-up","primary_text":"Our AI replies to every inbound lead in 60 seconds so you never lose a deal to a competitor again.","cta":"Start free trial"}

# response
{"hook_type":"problem","awareness_stage":"problem_aware","has_clear_offer":true,"has_cta":true,"friction":"low","confidence":0.72}

SEO

POST /api/v1/seo/page-relevance— SEO 页面相关性

判断一个页面是否该内链到另一个页面,以及两者的关系。

# request
{"source":"Blog: 'How calibrated confidence scores work in decision models'","target":"Docs: 'noul — a calibrated yes/no question type'"}

# response
{"should_link":true,"relevance":"related","relationship":"narrower","confidence":0.62}

计费

  • 预付额度,在 Core 决策 API 和所有现成工作流 API 之间通用。
  • 标准额度 $0.42 / 1M input tokens,更大的额度包费率更低。output token 免费。
  • 每个响应都含 cost_usd 和 credits_remaining_usd。
  • 额度永不过期。

API key 已包含

  • 即时、自助、免配置。
  • Core /v1/decide 决策 API。
  • 邮件、客服、Agent、RAG、销售、SEO、广告等现成 API。
  • 一个 API key、一个余额,通用于所有工作流。
  • 批量工作流 + 可复制的 curl / Python / JS 示例。
  • 新的 Jev 场景会持续做成现成端点。

独立服务. JevTypeSafeAI.com 与 TypeSafe AI 无从属或背书关系。

获取 API key →▶ 免费试用 Jev
Jev API 中文文档 — 应用层端点 + 决策原语 · Jev by TypeSafe AI