Skip to content
EASYJEV

POST /v1/systemone

判定端点的完整参考:model/state/questions 字段、三种题型(noul、choice、score)、处理语义、响应结构与上游错误透传。

请求字段

字段类型必填说明
modelstring是模型名,取 GET /v1/models 返回值,如 typesafe/jev-latest。存量裸名(jev-latest、jev-1.13.0)经别名归一化仍可调用。
statestring / object / array是被评估的内容。形态自由:一个问题、一张工单、一条商品记录——只要能被 questions 引用。
questionsobject是{问题id: 问题定义} 映射,至少一项;问题 id 会在响应中原样带回。
(其他)任意否未知字段原样透传上游(保持前向兼容)。
JSON · request body
{
  "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 可选描述。
选择题choicecriteria选项名→描述映射(≤255 项,描述可 null);返回选中项与各选项 probabilities。
评分题scorecriteria有序层级数组(2–10 个);返回可在层级间插值的分数。

每种题型的 instructions 均可选,接受字符串、对象或数组。图片可经 assets 附带——见 图片与多模态资产。

处理语义(按顺序)

  1. 1. 请求体大小限制(单个媒体 50 MB;总量:multipart 60 MB / 纯 JSON 70 MB)→ 413
  2. 2. 最小结构校验——缺 model/state/questions → 422
  3. 3. 模型白名单(先做别名归一化)——未知模型 → 404,不转发
  4. 4. 按 key 限流(默认 600 RPM / 4,500,000 TPM)→ 429
  5. 5. 余额预检——零或负余额 → 402(本次调用允许扣至负数,下次拦截)
  6. 6. 上游转发与故障转移:最多尝试 3 组「渠道+key」(401 自动停用 key,429 冷却,5xx/网络错误切换)
  7. 7. 仅 200 计费:输入 token × 输入单价 + 输出 token × 输出单价,按上游 usage 精确结算;失败调用不扣费
  8. 8. 每次调用(无论成败)都写日志,request_id 经响应头返回

成功响应

200 响应体为上游响应原样透传(含未知字段)。usage 是计费口径:只透出 input_tokens / output_tokens / cost(上游返回时才有)三个字段。

JSON · 200 OK
{
  "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 而非网关错误体——且不计费。其余失败走 网关统一错误结构。