API 参考

基础地址与认证

使用主应用域名加 /v1，例如 https://your-deployment.example.com/v1，通过 Authorization: Bearer YOUR_API_KEY 提交平台密钥。密钥归属于账户，并使用该账户的积分余额。文档站与推理 API 是不同的服务。

POST /v1/systemone

设置 Content-Type: application/json，并可发送由客户端生成的 Idempotency-Key。请求与响应都是普通 JSON，不提供流式响应。

本页对应契约 typesafe-2026-09-18。在 typesafe-native 模式下，显式提供模型的请求会保留通过验证的原始 UTF-8 JSON 文本，包括排版、键顺序和扩展字段。响应只作检查，不会重建。错误参考与幂等章节说明安全例外及旧缓存行为。

{
  "model": "jev-latest",
  "state": { "message": "同一笔订单被扣款两次。" },
  "questions": {
    "team": {
      "type": "choice",
      "instructions": "选择负责审核的团队。",
      "criteria": { "billing": "付款与退款", "support": "技术支持" }
    },
    "urgency": {
      "type": "score",
      "instructions": "根据有序标准评估紧急程度。",
      "criteria": ["常规审核", "及时回复", "立即由人工处理"]
    },
    "duplicate": {
      "type": "noul",
      "instructions": "消息是否反映了重复扣款？"
    }
  }
}

将请求体保存为 request.json。以下 shell 示例在设置真实地址和密钥后会发起真实请求：

curl "$SYSTEM_ONE_BASE_URL/systemone" \
  -H "Authorization: Bearer $SYSTEM_ONE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-order-001' \
  --data-binary @request.json

Windows PowerShell 请使用 curl.exe 并按 PowerShell 语法读取环境变量，或直接使用 SDK 示例。每次新的逻辑操作都应使用新幂等键；上面的固定键仅用于示意。

请求字段

问题与选项名必须包含非空白字符，最多 128 个字符。原生请求、问题和 Noul 标准对象的扩展字段会被保留，仍需满足大小、深度限制及上游校验。描述可以包含嵌套 JSON。可为 null 的状态、可省略或为 null 的说明，以及可为 null 的 Noul 标准与官方 @typesafe-ai/sdk@0.6.0 声明对齐；省略 State 字段仍然无效，最终接受情况由上游决定。项目 SDK 0.3.0 的输入校验更严格，这些形式请使用原生 HTTP 或官方客户端。

显式模型优先于部署默认值。省略模型时，网关直接在根 JSON 文本中插入默认值，不重新序列化既有数值。别名的解析结果可能随时间变化；需要可复现模型版本时，应提供上游支持的固定版本。模型列表不是版本名称的本地白名单。

原生传输会保留 9007199254740993、1e-400 等数字 token，插入默认模型时也不会改变。重复对象键（包括转义后同名）及超出受支持有限范围的数字会被拒绝。Playground 直接从编辑器生成保留精确十进制值的紧凑 JSON。计费使用解析后的规范化请求；幂等比较精确数字，避免不同高精度输入误命中同一缓存。

平台限制

同一账户的 API 密钥和 Playground 共享限流。所有到达账户计数器的尝试，包括重放，都会占用额度。部署者可通过 SYSTEM_ONE_RATE_LIMIT 调整限流。API 认证前还会按哈希化 IP 限制每分钟 600 次尝试。这些是平台边界，不代表所有 Jev 版本或上游的能力。

响应

以下数值仅展示响应结构，并非真实模型输出记录：

{
  "model": "jev1.13.0",
  "answers": {
    "team": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.8, "support": 0.2 },
      "confidence": 0.6
    },
    "urgency": {
      "type": "score",
      "score": 1.5,
      "probabilities": { "0": 0.1, "1": 0.3, "2": 0.6 },
      "confidence": 0.3,
      "legend": { "0": "常规审核", "1": "及时回复", "2": "立即由人工处理" }
    },
    "duplicate": { "type": "noul", "noul": 0.8 }
  },
  "usage": { "input_tokens": 120, "output_tokens": 0 }
}

model 表示上游解析出的模型名称，上面的版本和数值仅为示例。TypeSafe 原生 Choice 必须包含 type、choice、probabilities 和 confidence。Score 必须包含 type、score、probabilities、confidence 和 legend。分布键需匹配请求，分数需在校验容差内符合标准的概率加权结果。详见决策原语。

TypeSafe 响应保留 Fetch 实际收到的 JSON 文本、状态及扩展字段。缺失的 usage、token 计数、warnings 和 rounding 不会被添加；缺失或为 null 的 token 计数在账本中保持未知。示例中的零代表明确提供的数值，不是缺省值。校验可采用 Jev 两位小数的显示容差，但不会改变数值或插入 rounding。

成功正文不再添加平台 billing、request_id 或 replayed。上游可以自行返回这些同名字段；应将其保留为上游数据，不能用于平台记账。平台积分与标识均从下表的响应头读取。

项目 SDK 0.3.0 将 Noul 映射为 { type: 'boolean', probability }，将用量转为驼峰命名，可能补充自身默认值，也不会暴露全部原始字段。使用 Fetch 或官方客户端的 withResponse() 获取 HTTP 头；官方客户端的快捷 requestId 是 TypeSafe 跟踪 ID，不是平台账本 ID。请显式读取 X-Request-Id。

响应头

响应设置 Cache-Control: no-store。显式服务端幂等缓存具有独立的 24 小时规则。

只转发 Content-Type、Retry-After 及指定的跟踪、限流头，不转发上游 Cookie、跳转、认证或任意其他头。平台安全与 CORS 头仍由平台控制。OpenRouter 显式适配 /decisions 并标记 openrouter-adapted，不承诺 TypeSafe 字节保真。旧缓存按幂等章节说明标记 legacy-cache。

GET /v1/models

需要 平台 Bearer 密钥。网关使用运营者凭据读取已配置的 TypeSafe 上游，返回真实 { "models": [...] } 正文，包括各模型的 name、description、release_date 及扩展字段。不会虚构 OpenAI 风格的 { "data": [...] } 列表，也不再提供匿名能力元数据。

curl "$SYSTEM_ONE_BASE_URL/models" \
  -H "Authorization: Bearer $SYSTEM_ONE_API_KEY" \
  -H 'Accept: application/json'

此认证请求读取实时列表，不预扣积分、不创建决策记录，使用独立的每账户每分钟 60 次限制。上游未配置时返回 503，OpenRouter 部署返回 501 model_listing_not_supported。有效版本 ID 不一定出现在列表中。Playground 直接输入模型名，不依赖这个受保护端点。

其他端点

浏览器管理端点使用现有 Better Auth 会话，不能用 Bearer 密钥代替。修改操作必须携带与应用配置完全一致的 Origin。每个账户最多 20 个有效密钥，密钥创建每分钟最多 10 次。已撤销或未知的密钥无法认证。

原生上游错误、稳定分类响应头及安全替换例外见错误参考。启用重试前请阅读幂等规则。