API 参考

非官方中文翻译 · 内容以英文原文 ↗ 为准 · 同步于 2026-10-15

针对一份 state 对一组带类型的 questions 进行评估，并按题目返回结构化的 answers，每个 question 对应一个 answer。入门介绍请从 primitives 开始。

评估接口

http

POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer <API_KEY>
Content-Type: application/json

请求体

每个请求的顶层结构。questions 映射中的每个条目都是你命名的带类型的问题。

state string | object | array · 必填：待评估的内容。文本可用普通字符串，结构化数据（对象/数组）可用于聊天记录、记录或你应用的当前状态等场景。格式与最佳实践见 State。
model string · 必填：处理该请求的模型。使用 "jev-latest"，即 TypeSafe 的旗舰模型。可用模型与别名见 Models。
questions map<string, Question> · 必填：一组带类型的 Question 对象映射。每个键由你命名，答案会以同样的键返回。
- ‹question id› Question：由你选择的键。对应的 Answer 会以这个 id 返回。该键不会发送给底层模型，也不参与推理。

json

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "Does this convey urgency?"
    }
  }
}

请求规则

以下规则适用于所有请求：

规则	限制
请求体大小	最多 32 MiB，请求头不计入。
编码	UTF-8 JSON，不带字节顺序标记（BOM）。
嵌套层级	`state`、`instructions` 和 `criteria` 中每一项最多 64 层嵌套的对象和数组。深度更大的内容请自行扁平化。
数字	仅限有限数。`NaN`、`Infinity` 以及无法表示的极大数字（例如 `1e400`）会被拒绝。请将标识符和精确的大数作为字符串发送。

超过 32 MiB 的请求体会返回 413；其他违规情况会返回 400。

压缩

你可以通过 Content-Encoding: gzip（或 x-gzip）或 zstd 压缩请求体。当运行环境支持 zstd 时，SDK 会对 1 KiB 及以上的请求体使用 zstd 压缩。请只使用一层压缩，并保持 zstd 的窗口大小不超过 8 MiB。32 MiB 的限制同时适用于压缩后与解压后的请求体。不支持的 Content-Encoding 或超过一层压缩会返回 415；压缩后的请求体格式错误会返回 400。

题型

Question 的类型由其 type 字段决定。每个问题都包含 type 和 instructions，大多数类型还会接受 criteria；每个类型的文档说明了它支持的字段。

instructions 属性可以是字符串、对象或数组。你可以把一道较长的问题拆分为结构化对象，将额外上下文或需要引用的数据放进单独字段。问题放在一个字段中，数据放在其他字段里，并使用与引用嵌套 state 值相同的方式，用反引号按字段名引用数据：

json

"instructions": {
  "potential_duplicate": {
    "name": "John Smith",
    "location": "Oakland, California",
    "last_employer": "Google"
  },
  "question": "Is the resume for the same person as `potential_duplicate`?"
}

详见在问题中使用结构化数据。

Noul（是非题）

是一道判断题。返回答案为“是”的概率。

type "noul" · 必填
instructions string | object | array · 必填：要评估的判断题。对象形式可以将问题放在一个字段，把需要引用的数据放在其他字段；见在问题中使用结构化数据。
criteria object：对“是”和“否”的可选描述。
- true string | object | array：表示“是”（值接近 1）的含义。
- false string | object | array：表示“否”（值接近 0）的含义。

json

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "Does this convey urgency?",
      "criteria": {
        "true": "Explicitly time-sensitive",
        "false": "No urgency expressed"
      }
    }
  }
}

Choice（选择题）

从你定义的选项集合中选出一个选项。返回所选选项以及完整的概率分布。

type "choice" · 必填
instructions string | object | array · 必填：模型应决策的内容。对象形式可以将问题放在一个字段，把需要引用的数据放在其他字段；见结构化指令与判定标准。
criteria map<string, string | object | array | null> · 必填：选项到评分说明的映射；当某个选项无需额外说明时使用 null。每个 Choice 最多 255 个选项。
- ‹option› string | object | array | null：由你选择的键。该选项的描述。

json

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "criteria": {
        "billing": "Payments, invoicing, refunds",
        "technical": "Bugs, outages, integrations",
        "sales": "Pricing, upgrades, new accounts"
      }
    }
  }
}

Score（打分题）

按你定义的评分标准对 state 评级。返回一个跨档位按概率加权的值。

type "score" · 必填
instructions string | object | array · 必填：模型应打分的内容。对象形式可以将问题放在一个字段，把需要引用的数据放在其他字段；见在问题中使用结构化数据。
criteria array<string | object | array> · 必填：按顺序排列的档位描述数组。Score 至少需要两个档位，API 最多接受 10 个。

json

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "frustration": {
      "type": "score",
      "instructions": "How frustrated is the customer?",
      "criteria": ["Calm", "Frustrated", "Very angry"]
    }
  }
}

响应体

每个问题对应一个答案，按你提供的相同 id 返回。

model string · 必填：执行此次评估的模型。
answers map<string, Answer> · 必填：每个问题对应的 Answer，使用你在 questions 中相同的 id 作为键。
- ‹question id› Answer：你在 questions 中选择的相同 id。
usage object · 必填：本次请求的 token 用量。
- input_tokens integer
- output_tokens integer

json

{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.95
    }
  },
  "usage": { "input_tokens": 296, "output_tokens": 20 }
}

答案类型

每个答案都带有一个与对应问题匹配的 type。部分答案类型还会带有一个介于 0 到 1 之间的 confidence；每个类型的文档列出了其答案包含的字段。详见 Confidence。

Noul（是非题）答案

type "noul" · 必填
noul number · 必填：判断题的答案，取值范围 0（否）到 1（是）。

json

{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.95
    }
  },
  "usage": { "input_tokens": 307, "output_tokens": 20 }
}

Choice（选择题）答案

type "choice" · 必填
choice string · 必填：概率最高的选项。
probabilities map<string, number> · 必填：每个选项到其概率的映射（浮点数之和为 1）。
- ‹option› number：你在 criteria 中定义的某个选项。
confidence number · 必填：模型的确定性，由概率推导得出。

json

{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.88, "technical": 0.12, "sales": 0.0 },
      "confidence": 0.81
    }
  },
  "usage": { "input_tokens": 318, "output_tokens": 34 }
}

Score（打分题）答案

type "score" · 必填
score number · 必填：跨档位按概率加权的答案；可能落在档位之间。
legend map<string, string> · 必填：每个档位编号到其描述的反向映射。
probabilities map<string, number> · 必填：每个档位（字符串键）到其概率的映射（浮点数之和为 1）。
- ‹level› number：档位索引，以字符串键的形式与 legend 对应。
confidence number · 必填：模型的确定性，由概率推导得出。

json

{
  "model": "jev-1.13.0",
  "answers": {
    "frustration": {
      "type": "score",
      "score": 1.05,
      "legend": { "0": "Calm", "1": "Frustrated", "2": "Very angry" },
      "probabilities": { "0": 0.0, "1": 0.95, "2": 0.05 },
      "confidence": 0.92
    }
  },
  "usage": { "input_tokens": 304, "output_tokens": 18 }
}

错误

错误使用标准的 HTTP 状态码，响应体为一个 JSON，用于描述具体出了什么问题。

状态码	含义
`400 Bad Request`	请求体违反了请求规则，例如 UTF-8 编码无效、嵌套层级过深、数字不是有限值，或者压缩后的请求体格式错误。`max_tokens_exceeded` 表示请求长度超出了模型的上下文长度。
`401 Unauthorized`	缺少 API key 或者 API key 无效。请检查 `Authorization` 请求头。
`413 Payload Too Large`	请求体大小超过 32 MiB。参见请求规则。
`415 Unsupported Media Type`	请求体使用了不支持的 `Content-Encoding`，或者使用了多层压缩。参见压缩。
`422 Unprocessable Entity`	请求体校验失败，例如缺少必填字段，或者 question 格式错误。响应体会标明出错的字段。
`429 Too Many Requests`	已超出限流（rate limit）。请退避并短暂等待后重试。
`529 Overloaded`	TypeSafe 暂时过载。请短暂等待后重试。

处理限流

当你收到 429 Too Many Requests 或 529 Overloaded 响应时，应当采用指数退避策略重试，而不是立即重试。如果你使用我们的客户端 SDK 并沿用其默认的重试策略，SDK 会自动处理这一逻辑，无需额外处理。

本文档由 Mintlify 构建并托管，Mintlify 是一个面向开发者的文档平台。