API 参考

这一页是 systemone 端点的完整参考，字段与官方 API 文档一一对应（2026-09-22 核验）。官方 SDK 的类型定义也由此生成。

端点与鉴权

POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer <你的 API Key>
Content-Type: application/json

只有一个端点。所有题型、所有判断都走它。

请求体

字段	类型	说明
model	string	jev-latest / jev-preview / jev-1.13.0
state	string | object | array	给模型的上下文；对象/数组会按官方规则序列化
questions	object	命名问题集合，值见下

每个问题的公共字段：

字段	类型	说明
type	"choice" | "score" | "noul"	题型，见能力总览
instructions	string	问题本身（自然语言）
criteria	见各题型	Choice：选项映射（≤255）；Score：有序等级数组（2–10）；Noul：可选 {true, false} 判据

尺寸限制（官方）：单请求 ≤ 64k token；state + 最长的单个问题 ≤ 32k token。

一次请求同时问三种题型

{
  "model": "jev-latest",
  "state": "Hi, my Stripe integration keeps failing for 3 days. Please refund my subscription.",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this",
      "criteria": { "billing": "Payment or subscription issues", "technical": "Bugs or integration problems" }
    },
    "frustration": {
      "type": "score",
      "instructions": "How frustrated the customer appears",
      "criteria": ["Calm", "Frustrated but civil", "Very angry"]
    },
    "asks_refund": {
      "type": "noul",
      "instructions": "The customer explicitly requests a refund"
    }
  }
}

响应体

{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "technical",
      "probabilities": { "technical": 0.85, "billing": 0.15 },
      "confidence": 0.78
    },
    "frustration": {
      "type": "score",
      "score": 1.0,
      "legend": { "0": "Calm", "1": "Frustrated but civil", "2": "Very angry" },
      "probabilities": { "0": 0.0, "1": 1.0, "2": 0.0 },
      "confidence": 1.0
    },
    "asks_refund": { "type": "noul", "noul": 0.91 }
  },
  "usage": { "input_tokens": 412, "output_tokens": 67 }
}

• answers 的键与请求 questions 一一对应
• Noul 没有 confidence；数值为官方文档示例口径的示意
• usage 是唯一计费依据（输出免费）

错误码与重试

状态码	含义	处理
401	鉴权失败	检查 Key 与 Authorization 头，不要重试
422	请求校验失败	对照请求表修正结构，不要重试
429	限流	指数退避重试；官方限流 250k token/s + 1200 req/min（可能调整）
529	服务过载	指数退避重试；持续失败应熔断降级

本站建议

官方两个 SDK 都内置 RetryPolicy（次数、可重试状态码、退避曲线可配）。直接用 HTTP 时，对 429/529 做“1s → 2s → 4s”起步的退避并加抖动（jitter），并对单请求设总超时。

支持的客户端

• 官方 Python SDK：pip install typesafe-sdk → Python 指南
• 官方 JavaScript/TS SDK：npm i @typesafe-ai/sdk → JavaScript 指南
• Agent Skill（Claude Code / Codex 等环境的官方技能包）：见开源生态的 typesafe-ai/skills

相关页面

快速开始 · 能力边界 · 应用场景