OpenAPI 参考

Modelink API · 决策

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

版本 1.0.0

创建 OpenAI Decisions

POST

/v1/decisions

按 OpenAI Decisions 原生契约提交 input 和有序 questions，一次返回有序 answers。

本接口同步返回单个 JSON 对象，不提供 SSE 或增量事件。

网关入口实际校验

入口只检查三件事，失败为 400：

请求体必须是 JSON 对象。
model 必须是非空字符串。
stream 的 JSON 值为布尔 true 时直接拒绝，不会发往上游。缺省或 false 可以。其他类型的 stream 不在入口本地校验。

input、questions、图片、布尔选项、题名和客户端扩展字段的语义不是入口上的统一 400 校验。下面的 schema 描述的是标准调用形状和原生上游约束，不是「所有渠道都会在网关被同一套规则拒绝」。

标准调用形状

input 为字符串，或仅含 role: "user" 的 message 数组。content 可以是字符串，或 input_text / input_image parts。
questions 为非空数组，保持客户端顺序。type 为 predicate、choice 或 score。
name 可省略、为 null、为空字符串，也可以重复。
choice.choices[].value 为字符串或布尔。布尔 true 与字符串 "true" 是不同选项。
score.levels[].label 为字符串。标准形状下 choices 为 2–255 项，levels 为 2–10 档。
成功响应按题目顺序返回。predicate 给出 0–1 的 probability；choice / score 的 probabilities[].probability 与 confidence 也是 0–1。score 本身是档位索引尺度上的加权得分，不是 0–1 概率，可以是 1.1 这样的小数。

原生透传与 Jev 可转换子集

选中原生渠道时，网关只替换请求和响应的顶层 model，并覆盖写入顶层 id。图片、布尔 choice、null 题名、refusal、safety_identifier 以及其他扩展字段逐字保留，由该上游校验。上游省略 usage 时，网关不补造用量字段。

只有能表达为 Jev 契约的请求才会同时允许 Jev 渠道。转换会拒绝图片、非 user 消息、未知字段、safety_identifier、非法题型，以及 choices / levels 数量越界等 Jev 无法承载的构造。该拒绝不是原生渠道的统一入口校验：存在原生渠道时这些字段仍会透传。若模型只有 Jev 渠道、而请求又无法转换，调度返回 400，code 为 protocol_unsupported。

经 Jev 渠道回译时，usage 固定为 input_tokens、output_tokens 与 total_tokens（total 为二者之和），不会生成 usage 明细。原生渠道则可能附带 input_tokens_details / output_tokens_details。

顶层 id 前缀为 chatdecisionsoai-，覆盖上游同名字段，并与 http_x_reqid 相同。响应 model 是解析后的入口模型。本入口额外检查 API Key 的模型权限。

认证方式

BearerAuthBEARER

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

请求体

请求体属性

modelstring, 必填
控制台中的决策模型 ID。入口要求非空字符串。
inputstring | object[], 必填
标准 input：字符串，或 user message 数组。图片 part 只属于原生渠道；Jev 转换会拒绝它，这不是所有渠道共用的入口 400。
- oneOf[0]string
  可选。
- oneOf[1]object[]
  - role"user", 必填
    必填。
    const: user
  - type"message"
    可选。标准值为 message。
    const: message
  - contentstring | object | object[], 必填
    message content：字符串，或 content parts 数组。
    oneOf[0]string
    可选。
    oneOf[1]object | object[]
    oneOf[0]object
    文本 part。
    type"input_text", 必填
    必填。
    const: input_text
    textstring, 必填
    必填。
    oneOf[1]object
    图片 part。原生渠道逐字保留。Jev 契约没有图像输入，因此带图片的请求不能转换到 Jev 渠道；若当时没有原生渠道，结果是 protocol_unsupported，而不是一条适用于所有原生渠道的入口校验。
    type"input_image", 必填
    必填。
    const: input_image
    image_urlstring, 必填
    图片 URL 或原生渠道接受的图片引用。
    detailstring
    可选的原生细节提示。入口不校验取值。
questionsobject | object | object[], 必填
有序题目。标准形状为非空数组。入口不本地校验题目语义。
- oneOf[0]object
  是/否题。标准形状不带 choices 或 levels。
  - type"predicate", 必填
    必填。
    const: predicate
  - instructionsstring, 必填
    标准形状为字符串。Jev 转换要求字符串；原生入口不本地强制该类型。
  - namestring | null
    题名。可省略、为 null、为空字符串，也可在数组中重复。
- oneOf[1]object
  单选。标准形状的 choices 为 2–255 项，同一题内 value 不能重复。该数量与去重约束是原生上游与 Jev 可转换子集的约束，不是入口对所有渠道的统一 400。
  - type"choice", 必填
    必填。
    const: choice
  - instructionsstring, 必填
    必填。
  - namestring | null
    题名。可省略、为 null、为空字符串，也可在数组中重复。
  - choicesobject[], 必填
    valuestring | boolean, 必填
    字符串或布尔。true 与 "true" 不相同。同一题内选项值不能重复。
    oneOf[0]string
    可选。
    oneOf[1]boolean
    可选。
    descriptionstring | null
    可选说明。标准形状为字符串或 null。
- oneOf[2]object
  评分题。标准形状的 levels 为 2–10 档，顺序即响应中的 value 索引；不能携带 choices。数量约束属于原生上游与 Jev 可转换子集，不是入口统一校验。
  - type"score", 必填
    必填。
    const: score
  - instructionsstring, 必填
    必填。
  - namestring | null
    题名。可省略、为 null、为空字符串，也可在数组中重复。
  - levelsobject[], 必填
    labelstring, 必填
    必填。
    descriptionstring | null
    可选说明。
streamfalse
只接受缺省或 false。JSON true 会在入口直接 400。本接口没有流式响应。
const: false

请求

POST/v1/decisions

curl https://api.qnaigc.com/v1/decisions \
  --request POST \
  --header 'Authorization: Bearer YOUR_BEARER_AUTH' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "your-decision-model",
  "input": "我的订单 #42 到货时已经压坏，想退款。",
  "questions": [
    {
      "type": "predicate",
      "instructions": "用户是否希望退款？",
      "name": "wants_refund"
    },
    {
      "type": "choice",
      "instructions": "应由哪个队列处理？",
      "name": "queue",
      "choices": [
        {
          "value": "billing",
          "description": "账单与退款"
        },
        {
          "value": "technical",
          "description": "技术问题"
        }
      ]
    },
    {
      "type": "score",
      "instructions": "紧急程度如何？",
      "name": "urgency",
      "levels": [
        {
          "label": "低"
        },
        {
          "label": "中"
        },
        {
          "label": "高"
        }
      ]
    }
  ]
}'

响应

object

决策成功。单个 JSON 对象，无流式事件。原生渠道的扩展字段会保留；schema 列出的是标准答案字段。

响应体属性

idstring, 必填
网关请求 ID，前缀 chatdecisionsoai-。覆盖上游同名 id。
modelstring, 必填
解析后的入口模型 ID。
answersobject | object | object | object[]
标准成功响应按请求题目顺序返回。原生渠道可能额外返回 refusal 或其他类型，网关不改写。
- oneOf[0]object
  predicate 答案。probability 为 0–1。
  - type"predicate", 必填
    必填。
    const: predicate
  - namestring | null
    题名。可省略、为 null、为空字符串，也可在数组中重复。
  - probabilitynumber, 必填
    0–1 概率。显式 0 合法，与字段缺失不同。
    minimum: 0; maximum: 1
- oneOf[1]object
  choice 答案。choice 保持字符串或布尔。原生渠道可能省略 probabilities 或 confidence；Jev 回译成功时二者都会出现。
  - type"choice", 必填
    必填。
    const: choice
  - namestring | null
    题名。可省略、为 null、为空字符串，也可在数组中重复。
  - choicestring | boolean, 必填
    选中值，类型与请求中的 value 一致。
    oneOf[0]string
    可选。
    oneOf[1]boolean
    可选。
  - confidencenumber
    0–1 概率。显式 0 合法，与字段缺失不同。
    minimum: 0; maximum: 1
  - probabilitiesobject[]
    按请求 choices 顺序。choice 项没有 label。
    valuestring | boolean, 必填
    oneOf[0]string
    可选。
    oneOf[1]boolean
    可选。
    probabilitynumber, 必填
    0–1 概率。显式 0 合法，与字段缺失不同。
    minimum: 0; maximum: 1
- oneOf[2]object
  score 答案。score 是档位索引尺度上的加权得分，不是 0–1 概率。
  - type"score", 必填
    必填。
    const: score
  - namestring | null
    题名。可省略、为 null、为空字符串，也可在数组中重复。
  - scorenumber, 必填
    索引尺度得分。三档时 1.1 表示介于第 2 档与第 3 档之间，不是超出 0–1 的概率。原生渠道不把该值夹紧到 0–1。
  - confidencenumber
    0–1 概率。显式 0 合法，与字段缺失不同。
    minimum: 0; maximum: 1
  - probabilitiesobject[]
    按 levels 顺序。value 为从 0 开始的索引。Jev 回译会带上请求中的 label，空字符串也保留。
    valueinteger, 必填
    档位索引，从 0 开始。
    minimum: 0
    labelstring
    请求档位的 label。可为空字符串。choice 分布项没有该字段。
    probabilitynumber, 必填
    0–1 概率。显式 0 合法，与字段缺失不同。
    minimum: 0; maximum: 1
- oneOf[3]object
  仅原生渠道可能原样返回的 refusal。Jev 回译不会生成该类型；上游 refusal 在 Jev 路径按错误处理。不要把它写成所有渠道都会返回的统一答案。
  - type"refusal", 必填
    必填。
    const: refusal
  - namestring | null
    题名。可省略、为 null、为空字符串，也可在数组中重复。
usageobject
usage 不是成功响应的必填字段。原生渠道省略时，网关不补造，客户端响应保持上游原文。经 Jev 渠道回译时固定包含 input_tokens、output_tokens、total_tokens，且不生成明细。
- input_tokensinteger
  可选。
  minimum: 0
- output_tokensinteger
  可选。
  minimum: 0
- total_tokensinteger
  Jev 回译时等于 input_tokens + output_tokens。原生渠道若提供该字段则原样保留。
  minimum: 0
- input_tokens_detailsobject
  仅原生渠道可能返回的输入明细。Jev 回译不会生成该对象。
  - cached_tokensinteger
    可选。
    minimum: 0
  - cache_write_tokensinteger
    可选。
    minimum: 0
- output_tokens_detailsobject
  仅原生渠道可能返回的输出明细。Jev 回译不会生成该对象。
  - reasoning_tokensinteger
    可选。
    minimum: 0

object

入口传输契约失败（非对象、空 model、stream 为 true），或模型不可用。protocol_unsupported 只表示该请求无法由当前仅有的 Jev 渠道承载，不是对所有原生扩展字段的统一入口拒绝。

响应体属性

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 或额度超限。本入口按 input 与 questions 的文本预估，并另加输出缓冲。

响应体属性

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

上游失败。经 Jev 渠道回译时，缺概率、缺 usage 或题型不匹配会在网关侧失败，不会补零。原生渠道的成功响应则按上游原文回写。

响应体属性

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": "chatdecisionsoai-0123456789abcdef0123456789abcdef",
  "model": "your-decision-model",
  "answers": [
    {
      "type": "predicate",
      "name": "wants_refund",
      "probability": 0.93
    },
    {
      "type": "choice",
      "name": "queue",
      "choice": "billing",
      "confidence": 0.81,
      "probabilities": [
        {
          "value": "billing",
          "probability": 0.88
        },
        {
          "value": "technical",
          "probability": 0.12
        }
      ]
    },
    {
      "type": "score",
      "name": "urgency",
      "score": 1.1,
      "confidence": 0.55,
      "probabilities": [
        {
          "label": "低",
          "value": 0,
          "probability": 0.1
        },
        {
          "label": "中",
          "value": 1,
          "probability": 0.7
        },
        {
          "label": "高",
          "value": 2,
          "probability": 0.2
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 296,
    "output_tokens": 20,
    "total_tokens": 316
  }
}