OpenAPI 参考

Modelink API · 决策

结构化决策 API。POST /v1/systemone 使用 System One / Jev 契约（state + questions 对象）；POST /v1/decisions 使用 OpenAI Decisions 原生契约（input + questions 数组）。两个入口都是同步 JSON，没有 SSE，也没有增量事件。

版本 1.0.0

创建 System One 决策

POST

/v1/systemone

提交一段状态和一组结构化问题，一次返回全部答案。

本接口固定使用 System One / Jev 契约，同步返回单个 JSON 对象，不提供 SSE 或增量事件。请求体没有 stream 字段；若仍传入 stream，网关会忽略该字段，不会因此返回 400，也不会改成流式响应。

请求约束（网关入站校验，失败为 400）

model、state、questions 必填。model 必须是非空白字符串，且是控制台中可用的决策模型；支持模型别名。响应里的 model 是解析后的入口模型，不是上游渠道模型名。
state 与每题 instructions 只接受 JSON string、object 或 array。null、布尔、数字以及缺省都会被拒绝。空字符串合法。
questions 必须是非空对象，不是数组。键是题目 ID，成功响应的 answers 使用同一组键。键不能为空白。
type 大小写敏感，只接受 noul、choice、score。
noul.criteria 可省略。一旦提供，必须是对象，且键只能是 "true" / "false"；值只接受 string、object 或 array，不接受 null。
choice.criteria 必填，为 1–255 个「选项 → 描述」。选项名不能为空白。描述接受 string、object、array 或 null。
score.criteria 必填，为有序数组，2–10 档。每一档只接受 string、object 或 array。
未知字段会被 JSON 绑定忽略，不要依赖它们被保存或回显。

响应

成功时每个请求题目都有对应答案，否则视为上游不完整（502），不会补造答案。usage 只有 input_tokens 与 output_tokens；上游缺少 usage 时同样报错，不会伪造零用量。output_tokens 为 0 是合法值。

score 是 legend 索引尺度上的加权得分，不是 0–1 概率。档位从 0 编号；例如三档且概率为 0.1 / 0.7 / 0.2 时，得分可以是 1.1。noul、probabilities 与 confidence 才是 0–1 概率，显式 0 合法。

顶层 id 是本次网关请求 ID，前缀为 chatdecisions-，与响应头 http_x_reqid 相同。

认证方式

BearerAuthBEARER

仅接受 Modelink API Key。在 Authorization 请求头中传入 Bearer <api_key>；不能使用控制台登录访问令牌。

请求体

请求体属性

modelstring, 必填
控制台中的决策模型 ID，非空白。可使用模型别名。响应 model 为解析后的入口模型。
statestring | object | unknown[], 必填
待判断的状态。string、object 或 array。空字符串合法。目前只接受文本类输入；图片、音频、视频和二进制内容需要先转换成文本或结构化字段再传入。
- oneOf[0]string
  可选。
- oneOf[1]object
  可选。
- oneOf[2]unknown[]
  可选。
questionsobject, 必填
题目 ID 到题目的映射，不能为空，也不能是数组。ID 不能为空白。
- *object | object | object
  单道 System One 题目。由 type 决定 criteria 形状。instructions 除字符串外也可以传对象或数组：把问题与它引用的数据放进同一个结构，并在问题中用反引号引用字段名，适合问题依赖多条上下文的场景。
  - oneOf[0]object
    是/否概率题。criteria 可选。答案是 0–1 的「是」概率，不含 confidence，由业务代码自行设置阈值。
    type"noul", 必填
    必填。
    const: noul
    instructionsstring | object | unknown[], 必填
    System One 中 state、instructions 与多数说明文本允许的 JSON 值：string、object 或 array。不接受 null、布尔或数字。
    oneOf[0]string
    可选。
    oneOf[1]object
    可选。
    oneOf[2]unknown[]
    可选。
    criteriaobject
    noul 的 true/false 说明。其他键会被网关拒绝。值不接受 null。
    additionalProperties: false
    truestring | object | unknown[]
    System One 中 state、instructions 与多数说明文本允许的 JSON 值：string、object 或 array。不接受 null、布尔或数字。
    oneOf[0]string
    可选。
    oneOf[1]object
    可选。
    oneOf[2]unknown[]
    可选。
    falsestring | object | unknown[]
    System One 中 state、instructions 与多数说明文本允许的 JSON 值：string、object 或 array。不接受 null、布尔或数字。
    oneOf[0]string
    可选。
    oneOf[1]object
    可选。
    oneOf[2]unknown[]
    可选。
  - oneOf[1]object
    单选。criteria 为选项到描述的映射，1–255 项。choice 是概率最高的选项，probabilities 是完整分布，confidence 由分布计算得出。
    type"choice", 必填
    必填。
    const: choice
    instructionsstring | object | unknown[], 必填
    System One 中 state、instructions 与多数说明文本允许的 JSON 值：string、object 或 array。不接受 null、布尔或数字。
    oneOf[0]string
    可选。
    oneOf[1]object
    可选。
    oneOf[2]unknown[]
    可选。
    criteriaobject, 必填
    选项名不能为空白。描述可为 string、object、array 或 null。
    *string | object | unknown[] | null
    choice 选项描述。比 DecisionTextValue 多接受 null。
    oneOf[0]string | object | unknown[]
    System One 中 state、instructions 与多数说明文本允许的 JSON 值：string、object 或 array。不接受 null、布尔或数字。
    oneOf[0]string
    可选。
    oneOf[1]object
    可选。
    oneOf[2]unknown[]
    可选。
    oneOf[1]null
    可选。
  - oneOf[2]object
    有序评分。criteria 为 2–10 档，顺序即 legend 索引。score 是概率加权值，可能落在两个档位之间。
    type"score", 必填
    必填。
    const: score
    instructionsstring | object | unknown[], 必填
    System One 中 state、instructions 与多数说明文本允许的 JSON 值：string、object 或 array。不接受 null、布尔或数字。
    oneOf[0]string
    可选。
    oneOf[1]object
    可选。
    oneOf[2]unknown[]
    可选。
    criteriastring | object | unknown[][], 必填
    从索引 0 开始的有序档位。
    oneOf[0]string
    可选。
    oneOf[1]object
    可选。
    oneOf[2]unknown[]
    可选。

请求

POST/v1/systemone

curl https://api.qnaigc.com/v1/systemone \
  --request POST \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "your-decision-model",
  "state": "我的订单 #42 到货时已经压坏，想退款。",
  "questions": {
    "wants_refund": {
      "type": "noul",
      "instructions": "用户是否希望退款？",
      "criteria": {
        "true": "明确要求退款",
        "false": "没有退款诉求"
      }
    },
    "queue": {
      "type": "choice",
      "instructions": "应由哪个队列处理？",
      "criteria": {
        "billing": "账单与退款",
        "technical": "技术问题",
        "other": null
      }
    },
    "urgency": {
      "type": "score",
      "instructions": "紧急程度如何？",
      "criteria": [
        "低",
        "中",
        "高"
      ]
    }
  }
}'

响应

object

决策成功。单个 JSON 对象，无流式事件。

响应体属性

idstring, 必填
网关请求 ID，前缀 chatdecisions-，与 http_x_reqid 相同。
modelstring, 必填
解析后的入口模型 ID，不是上游渠道模型名。
answersobject, 必填
与请求 questions 相同的题目 ID。成功响应包含每一题。
- *object | object | object
  单题答案。出现哪些字段由 type 决定。
  - oneOf[0]object
    noul 答案。noul 为 0–1 概率。
    type"noul", 必填
    必填。
    const: noul
    noulnumber, 必填
    判断为真的概率。0 合法。
    minimum: 0; maximum: 1
  - oneOf[1]object
    choice 答案。probabilities 的键是请求中的选项名，值是 0–1 概率，成功时覆盖全部选项。
    type"choice", 必填
    必填。
    const: choice
    choicestring, 必填
    选中的选项名。
    probabilitiesobject, 必填
    选项名到 0–1 概率。显式 0 会保留。
    *number
    0–1 概率。显式 0 合法，与字段缺失不同。
    minimum: 0; maximum: 1
    confidencenumber, 必填
    0–1 概率。显式 0 合法，与字段缺失不同。
    minimum: 0; maximum: 1
  - oneOf[2]object
    score 答案。score 使用 legend 索引尺度，不是 0–1 概率。
    type"score", 必填
    必填。
    const: score
    scorenumber, 必填
    按档位索引加权的得分。索引 0 是 criteria 的第一档。三档概率 0.1 / 0.7 / 0.2 时得分可以是 1.1。不要把它当成 0–1 概率。
    legendobject, 必填
    索引字符串到档位说明。上游未返回时，网关用请求 criteria 补齐，这是已知映射，不是预测值。
    *string
    可选。
    probabilitiesobject, 必填
    索引字符串到 0–1 概率。成功时覆盖 0 到档数-1 的每一个索引。
    *number
    0–1 概率。显式 0 合法，与字段缺失不同。
    minimum: 0; maximum: 1
    confidencenumber, 必填
    0–1 概率。显式 0 合法，与字段缺失不同。
    minimum: 0; maximum: 1
usageobject, 必填
System One 对外 usage。只有 input_tokens 与 output_tokens，没有 total_tokens，也没有缓存或思考明细。
- input_tokensinteger, 必填
  必填。
  minimum: 0
- output_tokensinteger, 必填
  可为 0。缺少该字段时请求失败，而不是写成 0。
  minimum: 0

object

请求不符合 System One 契约，或模型不存在、已下线、别名不可用。code 可能省略。

响应体属性

errorobject, 必填
统一错误对象。message 末尾会追加 (request_id: ...)。code 仅在有细分业务码时出现。
- messagestring, 必填
  人类可读的错误描述，含 request_id。
- typestring, 必填
  错误分类。常见值：invalid_request_error、authentication_error、access_denied_error、rate_limit_exceeded_error、quota_exceeded_error、upstream_error、service_unavailable_error、internal_server_error。
- codestring
  可选细分码，例如 model_not_found、protocol_unsupported、auth_api_key_invalid、rate_limit_rpm_exceeded、channel_unavailable。

object

API Key 缺失、无效、过期、禁用或已删除。

响应体属性

errorobject, 必填
统一错误对象。message 末尾会追加 (request_id: ...)。code 仅在有细分业务码时出现。
- messagestring, 必填
  人类可读的错误描述，含 request_id。
- typestring, 必填
  错误分类。常见值：invalid_request_error、authentication_error、access_denied_error、rate_limit_exceeded_error、quota_exceeded_error、upstream_error、service_unavailable_error、internal_server_error。
- codestring
  可选细分码，例如 model_not_found、protocol_unsupported、auth_api_key_invalid、rate_limit_rpm_exceeded、channel_unavailable。

object

Relay 关闭、调用方不是 API Key、账号封禁、API Key 额度不足或体验期限制。本入口不额外执行 API Key 模型权限检查。

响应体属性

errorobject, 必填
统一错误对象。message 末尾会追加 (request_id: ...)。code 仅在有细分业务码时出现。
- messagestring, 必填
  人类可读的错误描述，含 request_id。
- typestring, 必填
  错误分类。常见值：invalid_request_error、authentication_error、access_denied_error、rate_limit_exceeded_error、quota_exceeded_error、upstream_error、service_unavailable_error、internal_server_error。
- codestring
  可选细分码，例如 model_not_found、protocol_unsupported、auth_api_key_invalid、rate_limit_rpm_exceeded、channel_unavailable。

object

RPM、TPM、RPS 或额度超限。本入口的预估用量按 state 与 questions 的原始 JSON 字节数除以 3，不加额外缓冲。

响应体属性

errorobject, 必填
统一错误对象。message 末尾会追加 (request_id: ...)。code 仅在有细分业务码时出现。
- messagestring, 必填
  人类可读的错误描述，含 request_id。
- typestring, 必填
  错误分类。常见值：invalid_request_error、authentication_error、access_denied_error、rate_limit_exceeded_error、quota_exceeded_error、upstream_error、service_unavailable_error、internal_server_error。
- codestring
  可选细分码，例如 model_not_found、protocol_unsupported、auth_api_key_invalid、rate_limit_rpm_exceeded、channel_unavailable。

object

网关内部错误。

响应体属性

errorobject, 必填
统一错误对象。message 末尾会追加 (request_id: ...)。code 仅在有细分业务码时出现。
- messagestring, 必填
  人类可读的错误描述，含 request_id。
- typestring, 必填
  错误分类。常见值：invalid_request_error、authentication_error、access_denied_error、rate_limit_exceeded_error、quota_exceeded_error、upstream_error、service_unavailable_error、internal_server_error。
- codestring
  可选细分码，例如 model_not_found、protocol_unsupported、auth_api_key_invalid、rate_limit_rpm_exceeded、channel_unavailable。

object

上游失败，或上游响应缺少 usage、答案、概率或 confidence。网关不会把缺项补成 0 后当作成功。

响应体属性

errorobject, 必填
统一错误对象。message 末尾会追加 (request_id: ...)。code 仅在有细分业务码时出现。
- messagestring, 必填
  人类可读的错误描述，含 request_id。
- typestring, 必填
  错误分类。常见值：invalid_request_error、authentication_error、access_denied_error、rate_limit_exceeded_error、quota_exceeded_error、upstream_error、service_unavailable_error、internal_server_error。
- codestring
  可选细分码，例如 model_not_found、protocol_unsupported、auth_api_key_invalid、rate_limit_rpm_exceeded、channel_unavailable。

object

没有可用的决策渠道，或渠道暂时不可用。

响应体属性

errorobject, 必填
统一错误对象。message 末尾会追加 (request_id: ...)。code 仅在有细分业务码时出现。
- messagestring, 必填
  人类可读的错误描述，含 request_id。
- typestring, 必填
  错误分类。常见值：invalid_request_error、authentication_error、access_denied_error、rate_limit_exceeded_error、quota_exceeded_error、upstream_error、service_unavailable_error、internal_server_error。
- codestring
  可选细分码，例如 model_not_found、protocol_unsupported、auth_api_key_invalid、rate_limit_rpm_exceeded、channel_unavailable。

响应

{
  "id": "chatdecisions-0123456789abcdef0123456789abcdef",
  "model": "your-decision-model",
  "answers": {
    "wants_refund": {
      "type": "noul",
      "noul": 0.93
    },
    "queue": {
      "type": "choice",
      "choice": "billing",
      "probabilities": {
        "billing": 0.88,
        "technical": 0.12,
        "other": 0
      },
      "confidence": 0.81
    },
    "urgency": {
      "type": "score",
      "score": 1.1,
      "legend": {
        "0": "低",
        "1": "中",
        "2": "高"
      },
      "probabilities": {
        "0": 0.1,
        "1": 0.7,
        "2": 0.2
      },
      "confidence": 0.55
    }
  },
  "usage": {
    "input_tokens": 296,
    "output_tokens": 20
  }
}