TokenToSea开发者文档
控制台

System OnePOST

结构化判断与抽取:TypeSafe Jev 与 Cloudflare Clef 返回概率、分类、评分与区域定位,Cloudflare Clairic 从文字或图片中抽取字段。

本页内容

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

System One 型号不生成自由文本。你提供应用状态(state)和一组问题或字段,型号为每一项返回程序可直接使用的结构化答案。只按厂商返回的 usage.input_tokens 计费,输出免费;图片、音频、视频计入输入 token。

不要把这些型号用于 Chat Completions、Messages 或 Responses。

前提:全能密钥或模型密钥,账户可用余额足以覆盖单次预留。Python 示例需要 pip install requests,Node.js 示例需要 Node.js 18+。

支持的型号#

型号厂商类型能力上下文
jev-1.14.0TypeSafe判断Noul、Choice、Score;图片输入与 Box(实验能力)约 64K
jev-1.13.0TypeSafe判断Noul、Choice、Score;图片输入(实验能力)约 64K
clefCloudflare判断Noul、Choice、Score;图片65,536
clef-flashCloudflare判断Noul、Choice、Score;图片24,576
clef-omniCloudflare判断Noul、Choice、Score;图片、音频、视频65,536
clairicCloudflare抽取(研究预览)数值、日期、文本、列表、估计、预测65,536

均在海外区域执行,只支持非流式 JSON 响应。每次调用按单次上限保守预留,收到可核验的用量后结算并释放余款;用量缺失或答案结构不符合协议时进入待核对,不按估算扣费。

请求格式#

项目规则
Content-Typeapplication/json;Jev 另支持 multipart/form-data(见图片)
Content-Encoding可选 gzip、zstd。原始请求与解压后都不能超过 32 MiB
结构嵌套深度不超过 64 层,节点总数不超过 100,000,不能包含非有限数值
TypeSafe-Danger-Zone-ImagesJev 图片判断的官方请求头。平台已在上游固定发送,客户端可以携带
TypeSafe-Danger-Zone-Long-Context不支持,发送即返回 422 system_one_long_context_not_enabled

请求体只能包含下文列出的字段,出现其他字段(包括 stream)返回 422。

判断型号:Jev 与 Clef#

参数类型必填说明
modelstring必填型号 ID
statestring | object必填应用状态,作为数据处理,不会被当作指令、文件或链接执行
questionsobject必填问题表,键为问题 ID,至少 1 个。Clef 最多 64 个,ID 需匹配 ^[A-Za-z0-9_.-]{1,100}$
assetsobject可选仅 Jev:图片资产表,见图片
imagesarray可选仅 Clef:最多 4 张图片,见 Clef 媒体
audio / videosarray可选仅 clef-omni,见 Clef 媒体

问题#

每个问题是 { "type": "…", "instructions": "…", "criteria": … },只能包含这三个字段;instructions 为字符串或对象。

typecriteria答案
noul可选,只能包含 true、false 两个键,例如 { "true": "已付款", "false": "未付款" }{ "type": "noul", "noul": 0.97 }:条件成立的概率
choice必填,选项表(Jev 1–255 项,Clef 2–255 项),值为说明或 null{ "type": "choice", "choice": "billing", "probabilities": { "billing": 0.91, … }, "confidence": 0.88 }
score必填,2–10 个有序等级说明组成的数组{ "type": "score", "score": 2.4, "probabilities": { "0": 0.02, … }, "confidence": 0.8 }:score 为 0 到等级数减 1 之间的加权分
box不能提供仅 jev-1.14.0 且请求包含图片:{ "type": "box", "box": { "top": 0.1, "bottom": 0.6, "left": 0.2, "right": 0.7 }, "confidence": 0.75 },坐标归一化到 0–1

probabilities 的各项之和为 1。置信度适合用来决定是否转人工复核,不等于业务正确率。

Box 即使目标不存在也会返回框

同时问一个 Noul「目标是否存在」,只有存在概率与定位置信度都达到你用样本校准过的阈值时才使用坐标。同一次调用中的问题并行处理,不能让 Box 依赖另一个问题的答案。

Jev 图片#

在 assets 中登记图片,并在 state 或问题文本中引用资产 ID 字符串(未被引用的资产返回 422 system_one_asset_reference)。

规则值
资产写法{ "type": "image", "format": "png" 或 "jpg", "data_base64": "…" }
数量最多 128 个;资产 ID 每个最多 1024 字节,合计最多 64 KiB
格式PNG(不能是动画)或 JPEG
尺寸宽、高各 280–1568 像素,面积不超过 2,458,624 像素
大小每张最多 16 MiB;整个请求(含 base64)最多 32 MiB

multipart 请求:第一个部分必须命名为 request,内容是上面的 JSON;资产写成 { "type": "image", "part": "<部分名>" }(可省略 format,平台按文件头识别),图片作为同名部分上传(image/png、image/jpeg 或 application/octet-stream)。最多 129 个部分,部分名不能重复,每个文件部分都必须被引用。

Clef 媒体#

媒体只能内嵌,不能是远程 URL:写成 data:<MIME>;base64,<数据> 字符串,或 { "content_type": "<MIME>", "base64": "<数据>" }。

字段型号格式数量与大小
images全部 Clefimage/png、image/jpeg、image/webp最多 4 张,每张 4 MiB,合计 8 MiB
audioclef-omniaudio/wav、audio/x-wav、audio/mpeg、audio/mp3最多 4 段,每段 8 MiB
videosclef-omnivideo/mp4、video/webm最多 2 段,每段 16 MiB;音频与视频合计 16 MiB

请求体 JSON 上限:clef、clef-flash 13 MiB,clef-omni 32 MiB;超出返回 413 cloudflare_request_size。

抽取型号:Clairic#

参数类型必填说明
modelstring必填clairic
statestring必填(提供了 images 时可省略)原文,最多 65,536 字节
fieldsobject必填字段表,1–16 个,ID 需匹配 ^[A-Za-z_][A-Za-z0-9_.-]{0,63}$,整个字段表 JSON 最多 32,768 字节
imagesarray可选同 Clef 媒体 的图片规则
reference_datestring可选YYYY-MM-DD,用于解析相对日期
optionsobject可选include_quantiles、return_state_text,均为布尔值

请求体 JSON 上限 16 MiB。

字段定义:

键说明
type必填:text、number、date、time、datetime、duration、list、estimate、forecast
instructions可选,字段说明
unit可选,单位,例如 USD
integer可选,布尔值
decimals可选,0–6
itemslist 必填:text、number 或 date
min / maxestimate、forecast 必填:数值或 YYYY-MM-DD 日期,且 min 小于 max
step可选:正数,或 month、year
scale可选:linear 或 log
null_threshold可选:大于 0 且不超过 1
horizon / intervalforecast 必填:horizon 为 1–64,interval 为 step、minute、hour、day、week、month、quarter、year

答案:{ "type": "…", "value": …, "p_null": 0.01, "confidence": 0.9 }。value 可能为 null(原文中没有);number、duration 为数值,text、日期时间类为字符串,list 为数组,forecast 另有 steps 数组。响应顶层的 truncated 表示原文是否被截断。

响应#

判断型号响应示例
{
  "model": "jev-1.14.0",
  "answers": {
    "payment_issue": { "type": "noul", "noul": 0.98 },
    "queue": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.93, "technical": 0.05, "other": 0.02 },
      "confidence": 0.9
    }
  },
  "usage": { "input_tokens": 212 }
}

Cloudflare 型号的 usage 另含 output_tokens: 0。answers 的键与请求中的问题 / 字段 ID 一一对应。

示例#

文字判断(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."}
      }
    }
  }'

图片判断与区域定位(Jev 1.14)#

# multipart:第一个部分 request 为 JSON,图片部分按 part 名引用
cat > request.json <<'JSON'
{
  "model": "jev-1.14.0",
  "state": {"picture": "picture-1"},
  "assets": {"picture-1": {"type": "image", "part": "picture"}},
  "questions": {
    "present": {"type": "noul", "instructions": "Does `picture` contain a chart?"},
    "region": {"type": "box", "instructions": "The main chart in `picture`."}
  }
}
JSON
curl https://api.tokentosea.com/v1/systemone \
  -H "Authorization: Bearer $TOKENTOSEA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "TypeSafe-Danger-Zone-Images: true" \
  -F "request=@request.json;type=application/json" \
  -F "picture=@selected-image.png;type=image/png"

判断(Clef Flash)#

请求体
{
  "model": "clef-flash",
  "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 on customers?",
      "criteria": ["No impact", "Minor", "Major", "Critical"]
    }
  }
}

字段抽取(Clairic)#

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.",
    "fields": {
      "total": {"type": "number", "unit": "USD"},
      "reference": {"type": "text", "instructions": "Invoice reference"}
    }
  }'

错误#

状态码code原因
400system_one_invalid_json请求体不是有效的 UTF-8 JSON 对象(含 BOM 也会被拒绝)
400system_one_multipart_boundary、system_one_multipart_headers、system_one_invalid_multipartmultipart 格式错误
413system_one_request_size、system_one_compressed_body_invalid_or_too_largeJev 请求超过 32 MiB,或压缩数据无效
413cloudflare_request_sizeCloudflare 型号请求超过上限
415system_one_content_type、system_one_encoding_not_supportedContent-Type 或 Content-Encoding 不支持
422system_one_request_fields、system_one_question_invalid、system_one_question_type出现未定义的字段,或问题结构错误
422system_one_noul_criteria、system_one_choice_criteria、system_one_score_criteriacriteria 不符合该类型的规则
422system_one_box_requires_v14_imageBox 只能用于 jev-1.14.0 且请求包含图片
422system_one_asset_reference、system_one_asset_fields、system_one_base64资产未被引用、字段错误或 base64 不规范
422system_one_image_format、system_one_image_dimensions、system_one_image_size、system_one_image_invalid、system_one_image_invalid_or_animated图片格式、尺寸或大小不符合要求
422system_one_multipart_parts、system_one_multipart_asset、system_one_multipart_unreferencedmultipart 部分命名或引用错误
422system_one_structure_limit、system_one_nonfinite_number结构过深、过大,或包含非有限数值
422system_one_long_context_not_enabled发送了长上下文请求头
422cloudflare_unsupported_field、cloudflare_questions_limit、cloudflare_fields_limit、cloudflare_state_requiredCloudflare 请求字段、问题或字段数量不符合规则
422cloudflare_embedded_media_required、cloudflare_media_format、cloudflare_media_count、cloudflare_media_size_or_base64、cloudflare_combined_media_size媒体不是内嵌 base64,或格式、数量、大小超限
422cloudflare_field_type、cloudflare_estimate_range、cloudflare_forecast_range、cloudflare_extraction_text_limit、cloudflare_extraction_optionsClairic 字段定义错误
422cloudflare_input_not_verified、system_one_input_not_verified该型号未开放所用的媒体类型

厂商答案不符合协议(例如概率之和不为 1)时,调用进入待核对,接口返回 202;不会扣除无法核验的费用。

下一步#

    输入关键词搜索全部文档与模型。