API 参考

System One 通过 HTTP 提供结构化选择、评分和是非概率。本参考覆盖托管决策 API 及控制台账户端点。独立的 System One SDK 同样是完整的接入方式，拥有自己的适配器与凭据要求。TypeScript 应用可从托管 SDK 快速开始入手，也可以直接使用下面的 HTTP 示例。

常见问题

Q: 什么是 System One API？
A: System One API 是托管决策 API，提供 Choice、Score、Noul（是否判断）。使用 API 密钥鉴权，为智能体返回类型化决策结果。

Q: 错误码与幂等在哪里？
A: 见 /docs/api/ 下的错误码、幂等键与版本控制页面。

基础地址与认证

在 System One 控制台创建 API 密钥。将它保存在集成工具的密钥字段或服务端，不要放入浏览器代码、共享文档或截图。在控制台管理和撤销密钥。请求使用你账户的积分。

API 使用主应用地址，而不是文档站地址。POST /v1/systemone 使用 System One Bearer 密钥，请求体可以是决策 questions 或抽取 fields；GET /v1/models 公开可读。/api/system-one/* 的账户端点使用浏览器登录会话。直连提供方的 API 密钥不能代替 System One 账户密钥。准确的认证要求见其他端点。

下文的 YOUR_API_KEY、YOUR_MODEL_ID 和 YOUR_OPERATION_KEY 都是占位符，并非可用凭据或模型名。用选定的 ID 替换模型占位符，详见选择模型。

GET /v1/models

获取当前模型列表。该接口公开可读；调用方携带的 Bearer 会被忽略，不会因此返回 401。

curl 'https://system-one.dev/v1/models' \
  -H 'Accept: application/json'

JSON 响应是包含 models 数组的对象，不是 data 数组。不要假定条目数量或顺序固定。

当前可用模型、价格和限制请查看 Playground 模型选择器及旁边的 模型信息 按钮。当前模型均接受文本和 JSON；当 capabilities.inputs 包含 image 且存在 limits.images 时，该条目还接受图片。不支持图片的模型会拒绝带图片的请求。模型列表可能变化，集成时应允许选择新增条目，而不是内置永久不变的目录。获取模型列表不消耗决策积分，单独限制为每个哈希 IP 每分钟 60 次请求。已上架模型的公开 HTML 页面位于 /zh-CN/models 与 /en/models。这些页面把请求规则和网关上限链到本节。

开发者说明

公开模型页只展示零售信息：价格、请求大小、输入和 Choice／Score 限制。公开 slug、能力字段、网关上限，以及 state／instructions／问题 ID 规则写在这里。

公开 slug

HTML 页面为 /zh-CN/models/<slug> 与 /en/models/<slug>。已发布 slug：jev、clef-flash、clef、clef-omni、decider-v1-1、clairic。请求里填写 GET /v1/models 返回的完整 name。除非该 slug 同时也是目录条目可接受的名称，否则不要把公开 slug 当作模型 ID 发送。Clairic 的公开名称是 clairic；在开放 API 调用之前，它不会出现在 GET /v1/models。

能力

读取所选目录条目的 capabilities.inputs 和 capabilities.questions。当前模型接受 text 和 json；带 image 的条目还接受图片。问题类型为 choice、score 和 noul。不要从模型名称推断能力。

网关上限

以下是服务上限。所选模型的 limits 可以更严。大小按 1024 进制：64KB = 65,536 字节，13MB = 13,631,488 字节，4MB = 4,194,304 字节，8MB = 8,388,608 字节。

State、instructions 与问题 ID

以所选条目的 limits.requiresInstructions、questionNameLength 和 questionNamePattern 为准。

• 要求说明的模型：state 不可为 null。每个问题必须提供非空字符串、对象或数组 instructions。ID 仅允许 A–Z、a–z、0–9、_、. 和 -。Score 标准不可为 null；Noul criteria 必须省略或为仅含 true／false 键的对象。不支持额外的问题字段。
• 其他模型：state 可为 null，instructions 可省略或为 null。问题 ID 不可为空白。

完整 HTTP 契约见请求字段和限制与费用。

POST /v1/systemone

替换 YOUR_MODEL_ID，将以下请求体保存为 request.json：

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

使用你的密钥和唯一操作键（例如 UUID）发送请求。在发送前保存操作键与请求，只有恢复同一操作时才复用它们。

curl --include 'https://system-one.dev/v1/systemone' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_OPERATION_KEY' \
  --data-binary @request.json

替换占位符后，这段 shell 示例会发起真实请求，可能产生费用。响应是普通 JSON，不是流式输出。操作键可选，但不提供时重复发送会发起新的评估。在工具中启用重试前，请阅读幂等与重试。

Windows PowerShell 请使用 curl.exe 和 PowerShell 引号语法，或采用 SDK 快速开始。本文对应的兼容快照为 typesafe-2026-09-18，它不是模型 ID 或用于选择版本的请求头。

请求字段

以下输入方式适用于当前的模型选项，但仍须遵守所选模型的限制。

建议使用不超过 100 个字符的问题 ID，仅包含字母、数字、点、下划线或连字符。选项名必须为非全空白字符串，最多 128 个字符。使用其他问题名称前，请检查所选模型的名称规则。只使用已说明的字段，不要假定所有模型都支持 null 值或额外字段。

模型专属限制与可空输入

HTTP 结构区分「字段必填」和「值可为 null」。state 必须存在；原生结构还可以表示 null state、省略或 null 的 instructions、省略或 null 的 Noul criteria。这些形式并非每个模型都接受。要求说明的模型需要非空字符串、对象或数组；输入更严格的模型会拒绝 null state、null 评分档位描述及 null Noul criteria。所选模型接受时，Choice 和 Noul 的描述值可以为 null；其他描述也可以包含嵌套 JSON。

请读取所选条目的 limits.minChoiceOptions、questionNameLength、questionNamePattern 和 requiresInstructions，不要将某一模型的规则硬编码给所有模型。有些模型接受一个 Choice 选项，有些至少需要两个。不支持的扩展字段可能被拒绝，包括额外的问题字段，以及 Noul 中除 true、false 外的键。HTTP 结构或独立 SDK 适配器接受某种形式，不代表每个托管模型都支持。Core SDK 的校验也比原生 TypeSafe 结构更严格，参阅 SDK 类型与适配器。

省略 model 时必须存在公开配置返回的服务默认模型，否则在扣费前返回 422；显式值优先。托管 ID 与别名来自目录，HTTP 提供方收到原样 ID，不按前缀改写。为可复现性与请求恢复应保存所选模型；校验失败不会自动切换模型。

通过 Fetch 发送图片

对目录中声明图片能力的条目，可发送 PNG（image/png）、JPEG（image/jpeg）和 WebP（image/webp）。网关上限为 4 张，单张解码后 4MB（4,194,304 字节），合计 8MB（8,388,608 字节），完整 UTF-8 JSON 最高 13MB（13,631,488 字节）；所选 limits.bytes 与 limits.images 可更严格。Data URL 使用真实 base64 字节，对象形式为 { mediaType, base64 }，不是提供方内部的 content_type。不能按模型 ID 推断能力。不支持远程文件 URL、服务端下载、音频或视频。

systemOneAdapter@0.7.0 不会编码 evaluate() 的图片。托管决策图片请使用标准 Fetch，不要通过该适配器的 evaluate() 传图片或修改其能力标记。Clairic 图片请改用 extract()。将示例保存为 hosted-image.mts，设置 SYSTEM_ONE_API_KEY，并将 SYSTEM_ONE_MODEL 设置为目录中已上架、支持图片的 name（例如 clef 或 clef-flash）。使用 Node.js 22.18+ 执行 node --env-file=.env hosted-image.mts ./receipt.png，提供真实 PNG 文件。无需安装 SDK。

import { readFile } from 'node:fs/promises';

const apiKey = process.env.SYSTEM_ONE_API_KEY;
const model = process.env.SYSTEM_ONE_MODEL;
const imagePath = process.argv[2];
if (!apiKey || !model || !imagePath) {
  throw new Error('Set System One credentials/model and supply a PNG file path.');
}
const operation = {
  idempotencyKey: crypto.randomUUID(),
  body: JSON.stringify({
    model,
    state: '',
    images: [{ mediaType: 'image/png', base64: (await readFile(imagePath)).toString('base64') }],
    questions: {
      receipt: { type: 'noul', instructions: '图片是否展示了一张收据？' },
    },
  }),
};
const response = await fetch('https://system-one.dev/v1/systemone', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': operation.idempotencyKey,
  },
  body: operation.body,
});
const responseText = await response.text();
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${response.headers.get('X-System-One-Error-Code') ?? 'unknown'}`);
}
console.log({ credits: response.headers.get('X-System-One-Credits'), responseText });

每次执行都创建新的计费操作。本示例只在内存中保留操作；需要恢复的真实应用应在首次发送前持久保存键与完整正文。重试复用同一正文、图片及数组顺序和键，不要重新读取已修改文件或生成 UUID。图片 base64 计入积分费用与幂等标识。图片表示无效、模型不支持及大小超限均在扣费前拒绝；普通上游失败会返还预扣积分。图片发送给模型服务，不作为独立图片上传存储；回显内容可能进入响应缓存。参阅数据与隐私。

原生 TypeSafe 模式是独立契约，继续保留原始扩展字段和 64KB HTTP 上限。本次升级不声明该提供方支持图片，也不改变其可空输入或响应精度。

JSON 精度

重复对象键会被拒绝，包括转义解码后同名的键；超出受支持有限范围的数字也会被拒绝。幂等比较保留精确十进制差异：9007199254740993 不等于 9007199254740992，1e-400 不等于零；等价数字写法则视为同一值。这并不会使 JavaScript number 具备任意精度：已发生舍入的值无法通过序列化恢复原始数字。需要精确数字请求标识时，请保留原始 JSON 文本；模型计算和 SDK 规范化与这种标识是不同的概念。

限制与费用

所选模型可能有更严格的限制。发送有效的 UTF-8 JSON，不要使用重复对象键。同一账户的 API 密钥和 Playground 请求共享限流，重放尝试也计入次数。默认决策限制为每分钟 120 次。API 认证另有每 IP 每分钟 600 次尝试的限制；模型发现另有每账户每分钟 60 次的限制。适用窗口请以响应头为准，429 响应也会给出相应信息。

积分 = 问题数 × max(1, ceil(解析后完整规范化请求 UTF-8 字节数 / 所选模型的 pricing.bytesPerBlock)) × pricing.creditsPerBlock。计费衡量紧凑的解析后请求，包括实际模型、上下文、问题和标准，而非仅消息或原始排版空白。精确十进制幂等比较与计费大小计算相互独立。假设单价为 2 积分，三个问题且完整请求在一个计费块以内，则费用为 6 积分。这只是计算示例，不是模型报价。新操作前请查看当前 pricing 字段；进行中的操作沿用原价格，调价或下架后成功操作的同键重放仍免费。详见积分与计费。

计费大小包含完整图片 base64 字符串及其媒体类型，不是仅计算解码后的像素或文本。图片顺序与表示形式也参与请求标识。模型的完整正文字节上限同样适用于纯文本请求。

阅读结果

以下响应仅展示答案结构，并非真实输出记录。ACTUAL_MODEL_ID 代表服务返回的模型名称，不是可复制到请求中的模型 ID。

{
  "model": "ACTUAL_MODEL_ID",
  "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 }
}

答案名称与问题名称一一对应。Choice 返回选项名；Score 可以是小数；noul 表示为真的概率，范围为 0 到 1。Confidence 是独立的模型统计值，不一定等于所选选项的概率。详见决策类型。

返回的 model 可能与请求中指定的模型 ID 不同。比较结果时应同时记录两者。Token 用量等可选信息可能缺失；缺失或为 null 的计数表示未知，不是零。允许响应包含额外字段，但不要把它们当作计费信息。

Choice 答案包含 type、choice、probabilities 和 confidence；Score 包含 type、score、probabilities、confidence 和 legend。概率键对应选项或从零开始的评分档位。分数是档位的概率加权值，允许模型数值精度带来的偏差。不要擅自舍入返回值，也不要补造缺失的 usage、warnings 或 rounding 字段。

成功响应不会向正文添加 System One 的 billing、request_id 或 replayed 字段。模型返回同名字段时，应视为模型数据，而非 System One 计费信息。Core SDK 配合 systemOneAdapter 将 Noul 规范化为 { type: 'boolean', probability }，将 token 用量转成驼峰命名，并不返回全部原始字段。需要完整 HTTP 访问时，使用 Fetch 或官方 TypeSafe 客户端的 withResponse()。该客户端的快捷 requestId 是 TypeSafe 跟踪 ID；System One 请求 ID 必须显式读取 X-Request-Id。

响应头

费用、请求 ID 和重放状态应读取这些响应头及控制台用量记录，而不是响应体中的同名字段。响应使用 Cache-Control: no-store，它与显式的 24 小时幂等窗口相互独立。模型服务响应仅转发文档指定的跟踪、限流头，以及 Content-Type 和 Retry-After；不转发 Cookie、认证、重定向地址或任意其他响应头，含敏感信息的头值会被省略。

浏览器访问与 CORS

/v1/* 支持无需认证的 OPTIONS 预检，状态为 204，设置 Access-Control-Allow-Origin: *，允许方法为 GET, POST, OPTIONS，允许请求头为 Authorization, Content-Type, Idempotency-Key。上表中的跟踪、积分、限流、重试、重放与错误分类头向浏览器 JavaScript 开放。这是 Bearer 认证，不是跨源 Cookie 认证：没有启用 Access-Control-Allow-Credentials。支持 CORS 不代表可以安全地将长期账户密钥嵌入公开浏览器代码。

控制台账户端点不继承这套跨源规则。应从已登录的应用源携带会话 Cookie 调用；浏览器修改请求必须携带与应用完全相同的 Origin（协议、主机和端口，不含路径）。Bearer 密钥不能替代会话，Origin 头也不能替代认证。

抽取

请求体包含 fields 时，此端点抽取类型化值，而不是回答决策问题。一次请求发送 { model, state, fields }，可选 images、reference_date 和 options。认证、计费、退款和校验仍在此端点上。字段数量不影响价格。公开抽取模型名是 clairic。TypeScript SDK 以 client.extract() 暴露同一契约，见 Clairic 抽取。

{
  "model": "clairic",
  "state": "发票 INV-2291\n销方：北风供应\n开票日期：2026-09-02\n应付合计：1080.00",
  "fields": {
    "invoice_number": { "type": "text" },
    "total": { "type": "number", "decimals": 2 }
  }
}

决策请求体使用 questions，不是抽取请求。抽取模型拒绝 questions；决策模型拒绝 fields。不要把 fields 传给 SDK 的 evaluate()。

其他端点

这些路径以 https://system-one.dev 为起点，不是以 /v1 基础地址为起点。

公开配置

GET /api/system-one/config 返回不含凭据的 JSON 对象：

API 密钥管理

GET /api/system-one/keys 返回 { keys: [...] }，按创建时间倒序，最多 100 条记录。每条包含 id、name、prefix、createdAt、lastUsedAt 和 revokedAt。时间戳为 Unix 毫秒；未设置的 lastUsedAt 和 revokedAt 为 null。列表永远不返回完整密钥。

创建时设置 Content-Type: application/json，正文准确填写 { "name": "Server" }。名称去除首尾空白后须为 1–64 个字符，不含控制字符。未知字段会被拒绝；创建密钥的正文上限为 4,096 字节。成功返回 HTTP 201，结构如下（值仅为示例）：

{
  "key": {
    "id": "example-key-id",
    "name": "Server",
    "prefix": "so_live_example_",
    "createdAt": 1790985600000
  },
  "secret": "YOUR_NEW_API_KEY"
}

secret 是完整密钥，只在创建响应中显示一次。关闭结果前请安全保存。若创建响应丢失，先列出密钥并撤销不需要的条目，再创建替代密钥；密钥创建不提供决策请求式的幂等重放。前缀只用于识别密钥，不能认证请求。

密钥归属于账户并使用账户余额；创建请求不接受更窄的权限范围或单密钥限额。所有密钥与 Playground 共享账户决策限额。每账户最多 20 个有效密钥，创建尝试每账户每分钟最多 10 次。DELETE /api/system-one/keys/:id 返回 { "ok": true }，即使自己的密钥此前已撤销也是如此。未知密钥或他人账户的密钥返回 404 key_not_found。已撤销密钥不能认证新请求或重放。

用量响应

GET /api/system-one/usage 为已登录账户返回 { balance, summary, daily, requests }，覆盖该账户所有 API 密钥及 Playground：

窗口从今天之前第 29 天的 UTC 零点开始，包含今天。响应没有分页游标。未知的 token 计数及未设置的指标、错误码可为 null。任一成功请求的输入或输出 token 计数未知时，相应汇总值为 null，而不是不完整的总数；无数据的汇总也可能为 null。不要将 null 转成零。失败或处理中的记录不表示成功答案；成功重放不会额外创建评估记录。

会话 Playground 请求

POST /api/system-one/playground 接受与 /v1/systemone 相同的 JSON 正文及可选 Idempotency-Key，返回相同的决策、错误结构和计费响应头。认证区别是必须具有登录会话并通过同源检查。会话与 API 密钥共享账户的幂等范围。请将这些会话端点保留在已登录的应用源上，不要把会话 Cookie 复制给其他服务。

提交的内容会由模型服务处理以生成答案。请仅发送任务必需的信息，并阅读隐私说明。请求或费用有疑问时，将请求 ID 提供给 support@system-one.dev，不要发送 API 密钥。