System One 结构化判断

System One 型号不生成自由文本。你提供应用状态和一组问题，它返回结构化答案：条件成立的概率、选中的选项、有序评分、图像中的区域，或从文本中抽取的字段。答案可以直接进入你的业务逻辑。

前提：已创建密钥并把它设置为环境变量 TOKENTOSEA_API_KEY。示例使用 curl、Python requests 或 Node.js 18+。

型号#

型号	厂商	能力	默认上下文
`jev-1.14.0`	TypeSafe	Noul、Choice、Score；实验性图像输入与 Box 定位	请求约 64k token，单个问题约 32k
`jev-1.13.0`	TypeSafe	Noul、Choice、Score；实验性图像输入	同上
`clef`	Cloudflare	Noul、Choice、Score；图像输入	65,536 token
`clef-flash`	Cloudflare	同上，更轻量	24,576 token
`clef-omni`	Cloudflare	同上，另支持音频与视频输入	65,536 token
`clairic`	Cloudflare	字段抽取（研究预览）	65,536 token

全部使用同一个端点：

POST https://api.tokentosea.com/v1/systemone

只支持普通 JSON 响应，不支持流式。
这些型号属于 global 区域，在海外执行节点处理，见区域与数据处理。
不要把这些型号用于 Chat Completions、Messages 或 Responses。
只对输入 token 计费，输出免费。图片、音频与视频计入厂商返回的 usage.input_tokens。价格见各型号页面。

判断原语#

原语	`type`	返回	适合的问题
Noul	`noul`	条件成立的概率 `noul`（0–1）	工单是否与付款有关？图片中是否有图表？
Choice	`choice`	选中的 `choice`、各选项概率 `probabilities` 与 `confidence`	这张工单应交给哪个队列？
Score	`score`	加权评分 `score`（0 到等级数 − 1）、各等级概率与 `confidence`	内容与主题的相关程度？
Box	`box`	归一化边界框 `box: {top, bottom, left, right}`（0–1）与 `confidence`；仅 `jev-1.14.0`，且请求中必须有图片	图片中主要图表在哪里？

问题的字段：

字段	说明
`type`	`noul`、`choice`、`score`、`box`
`instructions`	问题本身，字符串或对象。可以用反引号引用 `state` 中的字段名，例如 `ticket`
`criteria`	Noul 可选 `{"true": "…", "false": "…"}`；Choice 必填，选项 ID 到说明的映射（Jev 1–255 个，Clef 2–255 个）；Score 必填，2–10 个有序等级的数组；Box 不能填写

示例：文本分流（Jev）#

curl https://api.tokentosea.com/v1/systemone \
  -H "Authorization: Bearer $TOKENTOSEA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "jev-1.14.0",
    "state": {"ticket": "我充值成功了，但主站余额还没更新。"},
    "questions": {
      "payment_issue": {
        "type": "noul",
        "instructions": "Does `ticket` report a payment or balance problem?"
      },
      "queue": {
        "type": "choice",
        "instructions": "Which support queue should handle `ticket`?",
        "criteria": {
          "billing": "Payments, balance or charges.",
          "technical": "API usage and technical errors.",
          "other": "Any other issue."
        }
      }
    }
  }'

import os
import uuid

import requests

payload = {
    "model": "jev-1.14.0",
    "state": {"ticket": "我充值成功了，但主站余额还没更新。"},
    "questions": {
        "payment_issue": {
            "type": "noul",
            "instructions": "Does `ticket` report a payment or balance problem?",
        },
        "queue": {
            "type": "choice",
            "instructions": "Which support queue should handle `ticket`?",
            "criteria": {
                "billing": "Payments, balance or charges.",
                "technical": "API usage and technical errors.",
                "other": "Any other issue.",
            },
        },
    },
}
response = requests.post(
    "https://api.tokentosea.com/v1/systemone",
    headers={
        "Authorization": f"Bearer {os.environ['TOKENTOSEA_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json=payload,
    timeout=150,
)
response.raise_for_status()
answers = response.json()["answers"]
print(answers["payment_issue"]["noul"], answers["queue"]["choice"], answers["queue"]["confidence"])

import { randomUUID } from 'node:crypto';

const response = await fetch('https://api.tokentosea.com/v1/systemone', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TOKENTOSEA_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': randomUUID(),
  },
  body: JSON.stringify({
    model: 'jev-1.14.0',
    state: { ticket: '我充值成功了，但主站余额还没更新。' },
    questions: {
      payment_issue: { type: 'noul', instructions: 'Does `ticket` report a payment or balance problem?' },
      queue: {
        type: 'choice',
        instructions: 'Which support queue should handle `ticket`?',
        criteria: { billing: 'Payments, balance or charges.', technical: 'API usage and technical errors.', other: 'Any other issue.' },
      },
    },
  }),
});
const body = await response.json();
if (!response.ok) throw new Error(`${response.status} ${body.error?.code}`);
console.log(body.answers.payment_issue.noul, body.answers.queue.choice, body.answers.queue.confidence);

响应结构（数值仅为示意）：

JSON

{
  "model": "jev-1.14.0",
  "answers": {
    "payment_issue": { "type": "noul", "noul": 0.97 },
    "queue": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.93, "technical": 0.05, "other": 0.02 },
      "confidence": 0.9
    }
  },
  "usage": { "input_tokens": 312 }
}

示例：图像判断与定位（Jev 1.14）#

图片放在顶层 assets 中，并通过一个字符串引用它：引用 ID 必须出现在 state 或问题文本里。平台上游渠道已开启图像能力，示例同时发送 TypeSafe 官方协议中的 TypeSafe-Danger-Zone-Images: true 请求头。

Python

import base64
import os
import uuid
from pathlib import Path

import requests

image = Path("selected-image.png").read_bytes()  # 你明确选定的一张 PNG
reference = str(uuid.uuid4())
payload = {
    "model": "jev-1.14.0",
    "state": {"picture": reference},
    "assets": {
        reference: {"type": "image", "format": "png", "data_base64": base64.b64encode(image).decode()},
    },
    "questions": {
        "present": {"type": "noul", "instructions": "Does `picture` contain a chart?"},
        "region": {"type": "box", "instructions": "The main chart in `picture`."},
    },
}
response = requests.post(
    "https://api.tokentosea.com/v1/systemone",
    headers={
        "Authorization": f"Bearer {os.environ['TOKENTOSEA_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
        "TypeSafe-Danger-Zone-Images": "true",
    },
    json=payload,
    timeout=150,
)
response.raise_for_status()
answers = response.json()["answers"]
present, region = answers["present"]["noul"], answers["region"]
# Box 即使目标不存在也会返回一个框：只有“存在”概率与定位置信度都达到你校准过的阈值时才使用坐标
if present >= 0.8 and region["confidence"] >= 0.6:
    print("图表位置：", region["box"])
else:
    print("未可靠检测到图表", present, region["confidence"])

图片要求：PNG（非动画）或 JPEG；宽和高各 280–1568 像素，面积不超过 2,458,624 像素；单张不超过 16 MiB；每个请求最多 128 张；请求原始字节及解压后不超过 32 MiB。示例中的阈值只是占位，请用你自己的正例、反例和无目标样本校准。

Jev 还接受 Content-Encoding: gzip 或 zstd 压缩的 JSON，以及 multipart 请求：第一个部分名为 request（JSON），图片作为其他部分上传，并在 assets 中用 {"type": "image", "part": "<部分名>"} 引用。携带 TypeSafe-Danger-Zone-Long-Context 请求头会返回 422 system_one_long_context_not_enabled：平台未开放长上下文模式。

示例：Clef 判断#

Clef 系列与 Jev 使用相同的 Noul / Choice / Score 问题格式；state 为字符串或对象，最多 64 个问题，问题 ID 由字母、数字和 _.- 组成。图片放在 images 数组中（clef-omni 另可用 audio、videos），每项是 data URI 或 {"content_type": "…", "base64": "…"}，不接受远程 URL。

cURL

curl https://api.tokentosea.com/v1/systemone \
  -H "Authorization: Bearer $TOKENTOSEA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "clef",
    "state": "Checkout has been failing for every customer for the last hour.",
    "questions": {
      "urgent": { "type": "noul", "instructions": "Is this an urgent service outage?" },
      "severity": {
        "type": "score",
        "instructions": "How severe is the impact described in the state?",
        "criteria": ["No impact", "Minor", "Major", "Critical"]
      }
    }
  }'

Clef 的响应为 {"model", "answers", "usage": {"input_tokens", "output_tokens": 0}}，answers 结构与 Jev 相同。

媒体	格式	数量与大小
`images`	PNG、JPEG、WebP	最多 4 张，每张 4 MiB，合计 8 MiB
`audio`（仅 `clef-omni`）	WAV、MP3	最多 4 段，每段 8 MiB
`videos`（仅 `clef-omni`）	MP4、WebM	最多 2 段，每段 16 MiB；音视频合计 16 MiB

示例：Clairic 字段抽取#

Clairic 从文本（或图片）中抽取你定义的字段。state 必须是字符串（最多 65,536 字节），除非只提供图片。

curl https://api.tokentosea.com/v1/systemone \
  -H "Authorization: Bearer $TOKENTOSEA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "clairic",
    "state": "Invoice INV-2291. The total is 1080 USD, due on 2026-11-30.",
    "fields": {
      "total": { "type": "number", "unit": "USD" },
      "reference": { "type": "text", "instructions": "Invoice reference" },
      "due": { "type": "date" }
    }
  }'

import os
import uuid

import requests

response = requests.post(
    "https://api.tokentosea.com/v1/systemone",
    headers={
        "Authorization": f"Bearer {os.environ['TOKENTOSEA_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "model": "clairic",
        "state": "Invoice INV-2291. The total is 1080 USD, due on 2026-11-30.",
        "fields": {
            "total": {"type": "number", "unit": "USD"},
            "reference": {"type": "text", "instructions": "Invoice reference"},
            "due": {"type": "date"},
        },
    },
    timeout=150,
)
response.raise_for_status()
result = response.json()
for name, answer in result["answers"].items():
    print(name, answer.get("value"), answer.get("confidence"))
print("截断：", result.get("truncated"))

import { randomUUID } from 'node:crypto';

const response = await fetch('https://api.tokentosea.com/v1/systemone', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TOKENTOSEA_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': randomUUID(),
  },
  body: JSON.stringify({
    model: 'clairic',
    state: 'Invoice INV-2291. The total is 1080 USD, due on 2026-11-30.',
    fields: {
      total: { type: 'number', unit: 'USD' },
      reference: { type: 'text', instructions: 'Invoice reference' },
      due: { type: 'date' },
    },
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status} ${result.error?.code}`);
for (const [name, answer] of Object.entries(result.answers)) console.log(name, answer.value, answer.confidence);
console.log('截断：', result.truncated);

每个答案为 {"type", "value", "p_null"?, "confidence"?}；value 为 null 表示文本中没有该字段。forecast 字段另有 steps。响应中的 truncated 表示输入是否被截断。

字段配置	规则
字段 ID	最多 16 个；以字母或 `_` 开头，由字母、数字和 `_.-` 组成，最长 64 个字符
`type`	`text`、`number`、`date`、`time`、`datetime`、`duration`、`list`、`estimate`、`forecast`
`list`	必须设置 `items`：`text`、`number` 或 `date`
`estimate` / `forecast`	必须设置 `min` < `max`（数字或 `YYYY-MM-DD` 日期）；可选 `step`（正数，或 `month`、`year`）与 `scale`（`linear`、`log`）
`forecast`	另需 `horizon`（1–64）与 `interval`（`step`、`minute`、`hour`、`day`、`week`、`month`、`quarter`、`year`）
可选	`instructions`、`unit`、`integer`、`decimals`（0–6）、`null_threshold`（大于 0 且不超过 1）
请求级可选	`reference_date`（`YYYY-MM-DD`）；`options.include_quantiles`、`options.return_state_text`（布尔值）

字段配置整体不超过 32,768 字节。

正确使用结果#

结构正确不等于判断正确。用 confidence 决定是否交给人工复核或更强的模型，不要直接当作准确率。
Box 总会返回一个框。同时问一个 Noul“目标是否存在”，两者都达标才使用坐标。
同一次调用中的多个问题并行回答，一个问题不能依赖另一个问题的答案。
图像与 Box 属于厂商标注的实验能力，请在上线前用自己的样本评估误判率。
使用固定版本 jev-1.13.0 / jev-1.14.0，避免厂商别名指向变化带来的行为漂移。

常见错误#

`error.code`	原因
`system_one_request_fields` / `cloudflare_unsupported_field`	请求包含不允许的顶层字段
`system_one_assets_or_questions` / `cloudflare_questions_limit`	缺少问题，或数量超限
`system_one_asset_reference`	`assets` 中的 ID 没有在 `state` 或问题中被引用
`system_one_image_dimensions` / `system_one_image_format`	图片尺寸或格式不符合要求
`system_one_box_requires_v14_image`	Box 只能用于 `jev-1.14.0` 且请求中必须有图片
`system_one_choice_criteria` / `system_one_score_criteria` / `cloudflare_choice_criteria`	选项或等级数量不合法
`cloudflare_embedded_media_required`	Cloudflare 媒体必须内嵌，不接受 URL
`cloudflare_fields_limit` / `cloudflare_extraction_text_limit`	Clairic 字段过多，或文本、字段配置过长
`system_one_request_size` / `cloudflare_request_size`（413）	请求超过型号上限：Jev 32 MiB，`clairic` 16 MiB，`clef` / `clef-flash` 13 MiB，`clef-omni` 32 MiB

型号#