附录 B API 速查表
信息截至 2026-09-21，早期访问阶段细节可能变动，以 docs.typesafe.ai 为准。
端点与鉴权
| 项 |
值 |
| 决策端点 |
POST https://api.typesafe.ai/v1/systemone |
| 模型列表 |
GET https://api.typesafe.ai/v1/models |
| 鉴权 |
Authorization: Bearer $TYPESAFE_API_KEY |
| 模型取值 |
jev-1.13.0（钉版本）/ jev-latest（稳定别名）/ jev-preview（尝鲜） |
请求骨架
{
"model": "jev-latest",
"state": /* 字符串 | 对象 | 数组 */,
"questions": {
"<问题ID>": {
"type": "noul | choice | score",
"instructions": "判别标准式自然语言",
"criteria": [ /* score: 有序等级数组 */ ]
// 或 { /* choice: 选项名→描述 */ }
// noul 无此字段
}
}
}
- 问题 ID 自定、不发给模型；同 state 的多个问题并行求值、一次返回。
- state 为对象时，instructions 可用反引号路径引用字段，如
`ticket.body`。
响应字段（按类型）
| 类型 |
字段 |
含义 |
| noul |
noul |
命题为真的概率（0~1）；无 confidence |
| choice |
choice |
胜出选项（必在 criteria 内） |
| choice |
probabilities |
全部已定义选项的概率分布 |
| choice |
confidence |
对判断本身的把握（0~1） |
| score |
score |
概率加权连续分（等级 0 起） |
| score |
legend |
等级图例 |
| score |
probabilities |
各等级概率分布 |
| score |
confidence |
同上 |
限制
| 项 |
值 |
| state + 最长问题 |
≤ ~32K token（约 150K 字符） |
| 整个请求 |
≤ ~64K token |
| Choice 选项数 |
≤ 255（实践建议 ≤ 20，超则分层） |
| Score 等级数 |
2~10 |
| 输入模态 |
仅文本（图像暂未支持） |
| 限速（早期访问，动态） |
250,000 tokens/s · 1,200 请求/min |
价格与延迟
| 项 |
值 |
| 输入 |
$0.042 / 百万 token（$42 / 十亿） |
| 输出 |
免费 |
| 一次 ~300 token 调用 |
≈ $0.0000126 |
| 端到端延迟 |
70~500ms，多数 ~100ms（实测，美西） |
| 官方宣称上界（自报） |
快 193.6 倍 / 便宜 444.6 倍（workflow 评测，基线 GPT-6 Astra 与 Fable 5.1 均值） |
错误码
| HTTP |
含义 |
处理 |
| 401 |
key 无效 |
检查 TYPESAFE_API_KEY |
| 422 |
请求校验失败（缺 criteria、等级越界等） |
对照本表检查请求体 |
| 429 |
触发限速 |
指数退避重试 |
| 529 |
服务过载 |
指数退避重试（官方支持） |
调用为纯函数（无状态、无副作用）——重试与缓存均无风险。
SDK 与集成速查
| 环境 |
安装 |
关键入口 |
| Node ≥ 20 |
npm install @typesafe-ai/sdk |
client.systemOne({state, questions})；noul/choice/score 构造器；答案在 result.nouls/choices/scores |
| Python ≥ 3.10 |
pip install typesafe-sdk |
TypeSafeClient / AsyncTypeSafeClient；Noul / Choice / Score 类 |
| LangChain |
pip install langchain-typesafe |
TypeSafeClassifier；ModelRouterMiddleware；AutoModeMiddleware(tools=[...]) |
| Vercel AI SDK 7 |
npm i ai @ai-sdk/typesafe-ai |
experimental_evaluate；Noul→boolean、noul→probability、置信度在 providerMetadata.typesafe.confidence；Gateway 模型 ID typesafe-ai/jev |
| Agent 技能 |
claude plugin marketplace add typesafe-ai/skills |
或 npx skills add typesafe-ai/skills --skill typesafe-ai |
设计准则备忘（详见第 3 章）
- Noul：命题方向 = 高概率是"是"；0.5 = 拿不准；多闸门一次问。
- Choice：选项写具体情形；永远留 other；选项可判别；≤20 超则分层。
- Score：等级写具体情形不写程度副词；一维一个；方向一致极端在前。
- 通用：instructions 写判别标准；可计算条件代码先行；组合与权重留在代码。