TypeSafe AI：Jev System One 调用

通过 TypeSafe AI Jev System One 将文本状态转换为可执行的结构化判断。

TypeSafe AI：Jev System One 调用

使用本站的 TypeSafe AI 入口，让 jev-1.13.0 根据一份状态数据回答一个或多个类型化问题，并返回可直接由程序处理的结构化答案、概率和置信度。这个入口是同步 JSON 请求，不生成自然语言回复，也不提供流式或任务查询。

功能与适用场景

System One 适合把文本、记录或业务状态转换成受约束的判断，例如工单分流、风险筛选、优先级评分和是否满足条件。你的代码定义问题和候选范围，Jev 返回 noul、choice 或 score 类型的答案；应用可以根据概率和置信度决定自动处理或转人工。

Jev 目前只接受文本状态：可以是字符串，也可以是由文本组成的 JSON 对象或数组。图片、音频和视频不属于此入口的输入类型；需要生成文本或自由格式解释时，请选择其他聊天接口。

支持模型与组合

模型	适用说明
`jev-1.13.0`	本页示例使用的固定 Jev 版本。
`jev-latest`	TypeSafe 的当前 Jev 别名；实际版本由上游决定。
`jev-preview`	TypeSafe 的预览别名；使用前确认账号已开通。

一次请求可以在同一份 state 上提交多个问题。state 与所有问题共享最多 64,000 个输入 token 的上下文预算；超出后请缩短状态或拆分请求。本站按上游返回的 usage.input_tokens 计量输入，输出 token 不计费。模型是否对你的 API Key 开放仍以控制台权限为准。

第一步：设置鉴权

在请求头中使用 Authorization: Bearer YOUR_API_KEY。将 YOUR_API_KEY 替换为青云TOP API 控制台创建的 API Key，并保留 Bearer 与密钥之间的空格。不要提交真实密钥，也不需要 TypeSafe 厂商密钥。

第二步：调用模型

POST https://top.qingyuntop.ai/typesafe/v1/systemone

请求头使用 Content-Type: application/json 和 Accept: application/json。本站会把请求转发到 TypeSafe System One；不要把上游地址 https://api.typesafe.ai 或厂商 API Key 写进本站调用示例。

请求参数与详细解释

字段路径	类型	必填	允许值或范围	说明
`model`	string	是	`jev-1.13.0`、`jev-latest`、`jev-preview`	选择 Jev 模型。
`state`	string / object / array / null	是	文本状态；总输入不超过 64,000 token	要评估的材料。对象或数组中的内容应为文本，使用字段名保留上下文关系。
`questions`	object	是	至少一个键值	问题映射。每个键是你自定义的 ID，响应会使用相同 ID。
`questions.<id>.type`	string	是	`noul` / `choice` / `score`	问题类型。
`questions.<id>.instructions`	string / object / array / null	否	结构化说明也可	需要模型判断的问题；可以把问题和相关材料放在对象中，并在文字中引用字段名。
`questions.<id>.criteria`	object / array / null	按类型	见下方	`choice` 是候选映射，`score` 是有序等级，`noul` 可描述 true/false。
`stream`	boolean	否	只能省略或为 `false`	此入口不支持流式；建议省略。发送 `true` 会被拒绝。

问题类型的约束如下：

noul 是是否题。criteria 可以省略，或只包含 true、false 两个键；答案中的 noul 是 0 到 1 的“为真”概率。
choice 从候选映射中选择一个结果，候选数为 1 到 255；键是返回的选项名，值是可选的判定说明，也可以为 null。
score 按有序等级评分，等级数为 2 到 10。答案中的 score 是概率加权值，可能落在两个等级之间；legend 会把等级编号映射回说明。

可切换代码示例

curl --request POST "https://top.qingyuntop.ai/typesafe/v1/systemone" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{
    "model": "jev-1.13.0",
    "state": {
      "ticket": "客户反馈过去 3 天付款失败。",
      "channel": "email"
    },
    "questions": {
      "is_urgent": {
        "type": "noul",
        "instructions": "这条反馈是否表达了需要立即处理的紧迫性？",
        "criteria": {
          "true": "明确表示时间紧迫、持续失败或需要尽快处理",
          "false": "没有表达紧迫性"
        }
      },
      "team": {
        "type": "choice",
        "instructions": "哪个团队最适合处理这条反馈？",
        "criteria": {
          "billing": "支付、账单、退款",
          "technical": "故障、接口或产品问题",
          "support": "一般使用帮助"
        }
      },
      "frustration": {
        "type": "score",
        "instructions": "客户表达的挫败程度如何？",
        "criteria": ["平静", "不满", "非常生气"]
      }
    }
  }'

Python 示例依赖 requests；Node.js 示例需要 Node.js 18 或更高版本以使用内置 fetch。三种示例使用同一个请求体，生产环境请通过密钥管理系统注入 API Key。

响应与结果处理

成功响应包含模型名、按问题 ID 对齐的 answers，以及可选的 usage：

{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.95
    },
    "team": {
      "type": "choice",
      "choice": "billing",
      "probabilities": {
        "billing": 0.88,
        "technical": 0.12,
        "support": 0.0
      },
      "confidence": 0.81
    },
    "frustration": {
      "type": "score",
      "score": 1.05,
      "legend": {
        "0": "平静",
        "1": "不满",
        "2": "非常生气"
      },
      "probabilities": {
        "0": 0.0,
        "1": 0.95,
        "2": 0.05
      },
      "confidence": 0.92
    }
  },
  "usage": {
    "input_tokens": 318,
    "output_tokens": 34
  }
}

以上响应是字段结构示意。读取 answers.<id>.type 后再按类型读取字段：noul 读取 noul；choice 读取 choice、probabilities 和 confidence；score 读取 score、legend、probabilities 和 confidence。不要把 score 当作固定的整数等级，也不要只根据最高概率自动执行高风险操作。

本站接口会保留公开请求 ID 和同步结果，但此入口没有可供客户端调用的任务查询接口；收到 2xx 响应即可按同步结果处理，并记录你的请求日志和返回的 usage。

查询、流式消费与下载

TypeSafe System One 是同步接口，不支持 SSE、后台任务、回调、取消、查询或结果文件下载。请求超时后不能据此判断上游是否已经处理完成；请根据业务幂等策略决定是否重试，并避免在没有去重设计时盲目重复提交。

常见错误、限制与参考

401 Unauthorized：检查本站 API Key、Bearer 拼写和 Key 是否有效。
403 Forbidden：确认当前 Key 已开通 TypeSafe 或目标模型。
422 Unprocessable Entity：检查 JSON 对象、model、非空 questions、问题类型以及 criteria 的数量和形状；stream 只能省略或设为 false。
429 Too Many Requests 或 529 Overloaded：按 Retry-After（如果返回）进行指数退避，不要立即连续重试。
输入过大或状态不是文本：缩短 state、减少问题数量，移除图片/音频/视频内容后再提交。

本页仅介绍本站已开放的 TypeSafe AI 路由。官方 API 的请求定义、问题类型和答案字段请参阅 TypeSafe AI API 参考、State 与 Primitives。