TypeSafe 的 API

HTTP 评估端点

请求正文包含三个顶层字段。state 为必填项，可以是字符串、对象或文本数组。model 也是必填项；文档示例使用 jev-latest。questions 是带类型 Question 对象的映射，各键由你指定，匹配的答案会以同一 id 返回。该键不会发送给底层模型，也不参与推理。

最小的 Noul 如下：{"state": "救命！我的付款已经连续 3 天失败了。", "model": "jev-latest", "questions": {"is_urgent": {"type": "noul", "instructions": "这是否表达了紧迫性？"}}}。Choice 会添加从选项名称到说明的 criteria 映射。Score 会添加按顺序排列的等级 criteria 数组。三者都包含 type 和 instructions，并各自采用不同结构的 criteria。

从 https://console.typesafe.ai/settings/keys. 获取 API 密钥。若直接调用 HTTP，请根据 retry-after 处理 429。Jev 1.13 的速率限制为每秒 250,000 个令牌、每分钟 1,200 个请求，且可能随时调整。SDK 默认采用退避策略重试。使用同一个 Bearer 令牌调用 GET /v1/models 可列出模型。

官方 SDK

Python：pip install typesafe-sdk。从 typesafe_sdk 导入 TypeSafeClient。使用 with TypeSafeClient() as client: client.system_one(state, questions)。Noul、Choice 和 Score 等构造器已包含在包中，无需手写 JSON 的 type 字段。默认模型为 jev-latest。需要 Python 3.10 或更高版本。

JavaScript：npm install @typesafe-ai/sdk。从 "@typesafe-ai/sdk" 导入 { TypeSafeClient }。客户端连接的是同一端点。运行环境要求 Node.js 20+。代码仓库见 https://github.com/typesafe-ai/typesafe-sdk-js.。两个 SDK 都提供 models.list()，用于获取别名目录。

https://console.typesafe.ai/playground 的演练场是登录后使用的控制台，并非公开嵌入组件。将文本粘贴为 state，添加一个 Noul，例如“这条消息是否表达了紧迫性？”，然后在同一次调用中加入更多问题。这是在接入生产密钥前体验并行评估的最快方式。

第一次 curl 调用

使用 curl -X POST https://api.typesafe.ai/v1/systemone，并设置 Authorization: Bearer $TYPESAFE_API_KEY 和 Content-Type: application/json。正文中将 state 设为一条 Stripe Connect 失败消息，model 设为 jev-latest，questions.urgency 使用 noul 类型，instructions 为“这条消息是否表达了紧迫性？”。这就是快速入门示例。还可加入名为 department 的 Choice，设置 billing / technical / sales 条件；再加入名为 frustration 的 Score，设置有序等级，无需进行第二次往返调用。

出现问题时，先阅读 jaggedness，不要急着给指令添加更多说明文字。字面理解问题需要在指令和判定标准中明确写出确切条件；数学问题应交给代码计算；生成任务则应换用其他模型。即使要求 Jev 通过串联 Choice 写一个段落，API 仍会返回类型化载荷，但速度很慢，效果也很差。应使用正则表达式或生成式模型提出候选项，再让 Jev 选择。

Cloudflare Workers AI 将 typesafe/jev 列为目录名称。这是第三方收录，不能取代 api.typesafe.ai。Steam 上没有 Jev 应用。密钥应保存在 TypeSafe 的控制台中；Awesome Jev 上的社区 SDK 除非跟进 github.com/typesafe-ai 组织，否则都应视为非官方项目。

错误、重试与 ID

当每秒令牌数或每分钟请求数超限时，文档规定返回 429 Too Many Requests。请遵循 retry-after。官方 SDK 已内置退避重试。若自行封装 HTTP，遇到 429 时不要持续轰炸端点，否则只会一直困在同一个限流窗口内。

问题 ID 用于你的追踪记录，不会参与推理。即使在循环中生成 item_0 到 item_n，每项仍会各自得到一个 Noul。同一请求中的键必须唯一；重复使用键会在映射中静默覆盖原问题。

身份验证使用控制台生成的 Bearer TypeSafe API 密钥。api.typesafe.ai 不使用 Cookie 会话。请在控制台轮换密钥，而不是给本 wiki 发邮件。演练场的登录限制与此不同：它是浏览器控制台，并非另一套 HTTP API。

复制一次快速入门 curl 后，就应从代码库中删除并改用 SDK。SDK 会负责重试和带类型的构造器。原始 HTTP 仅供没有官方客户端的语言使用。无论采用哪种方式，都会将 Bearer 密钥和相同的 JSON 正文发送至 POST /v1/systemone。

GET /v1/models 会列出你的账户可使用的别名。即使 jev-1.13.0 可用于 POST /v1/systemone，该列表也可能不显示它。不要把此列表当成版本化 ID 的允许列表；它只是别名目录，版本化 ID 应保存在你自己的配置中。

切勿提交 TYPESAFE_API_KEY。若密钥泄露，请在控制台中轮换。contact@jevai.wiki 并非处理密钥泄露的正确邮箱，请使用 TypeSafe 自己的渠道。

Python 3.10 和 Node.js 20 是文档规定的最低版本。官方客户端不支持更旧的运行环境。