POST /v1/systemone
判定端点的完整参考:model/state/questions 字段、三种题型(noul、choice、score)、处理语义、响应结构与上游错误透传。
请求字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 模型名,取 GET /v1/models 返回值,如 typesafe/jev-latest。存量裸名(jev-latest、jev-1.13.0)经别名归一化仍可调用。 |
| state | string / object / array | 是 | 被评估的内容。形态自由:一个问题、一张工单、一条商品记录——只要能被 questions 引用。 |
| questions | object | 是 | {问题id: 问题定义} 映射,至少一项;问题 id 会在响应中原样带回。 |
| (其他) | 任意 | 否 | 未知字段原样透传上游(保持前向兼容)。 |
{
"model": "typesafe/jev-latest",
"state": "User asks: can I get a refund for order #1024?",
"questions": {
"refund": {"type": "noul", "instructions": "Is this a refund request?"},
"urgency": {
"type": "score",
"instructions": "How urgent is this?",
"criteria": ["low", "normal", "high"]
}
}
}题型定义
| 题型 | type | 必填字段 | 返回 |
|---|---|---|---|
| 是非题 | noul | — | 「是」的概率,区间 [0,1];criteria.true/false 可选描述。 |
| 选择题 | choice | criteria | 选项名→描述映射(≤255 项,描述可 null);返回选中项与各选项 probabilities。 |
| 评分题 | score | criteria | 有序层级数组(2–10 个);返回可在层级间插值的分数。 |
每种题型的 instructions 均可选,接受字符串、对象或数组。图片可经 assets 附带——见 图片与多模态资产。
处理语义(按顺序)
- 1. 请求体大小限制(单个媒体 50 MB;总量:multipart 60 MB / 纯 JSON 70 MB)→ 413
- 2. 最小结构校验——缺 model/state/questions → 422
- 3. 模型白名单(先做别名归一化)——未知模型 → 404,不转发
- 4. 按 key 限流(默认 600 RPM / 4,500,000 TPM)→ 429
- 5. 余额预检——零或负余额 → 402(本次调用允许扣至负数,下次拦截)
- 6. 上游转发与故障转移:最多尝试 3 组「渠道+key」(401 自动停用 key,429 冷却,5xx/网络错误切换)
- 7. 仅 200 计费:输入 token × 输入单价 + 输出 token × 输出单价,按上游 usage 精确结算;失败调用不扣费
- 8. 每次调用(无论成败)都写日志,request_id 经响应头返回
成功响应
200 响应体为上游响应原样透传(含未知字段)。usage 是计费口径:只透出 input_tokens / output_tokens / cost(上游返回时才有)三个字段。
{
"model": "typesafe/jev-latest",
"answers": {
"refund": {
"type": "noul",
"noul": 0.97,
"confidence": 0.93
},
"urgency": {
"type": "score",
"score": 1.4,
"confidence": 0.88
}
},
"usage": {"input_tokens": 1234, "output_tokens": 0}
}响应头
每个响应(成功或失败)都带同值的 X-Request-Id 与 x-typesafe-request-id——用于对账与联系支持;官方 SDK 也以 resp.request_id 暴露它。
上游错误透传
上游校验失败(400 / 404 / 413 / 422)原样透传——响应体是上游的错误 JSON 而非网关错误体——且不计费。其余失败走 网关统一错误结构。