使用帮助

决策模型使用 System One 原生协议，根据文本、结构化状态或图片一次回答一个或多个分类、评分、是非判断或图片定位问题。

端点与鉴权

项	值
请求端点	`POST https://51kik.com/decision/v1/systemone`
鉴权	`Authorization: Bearer <API-Key>`
Content-Type	`application/json` 或 `multipart/form-data`
响应模式	同步 JSON，不支持流式

模型代号可在决策模型目录中查看。

快速示例

curl -X POST https://51kik.com/decision/v1/systemone \
  -H 'Authorization: Bearer sk-xxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-review-20260930-001' \
  -d '{
    "model": "jev",
    "state": {
      "order": { "amount": 1280, "currency": "CNY" },
      "customer": { "risk_level": "medium" }
    },
    "questions": {
      "review": {
        "type": "choice",
        "instructions": "Decide whether this order can be approved.",
        "criteria": {
          "approve": "Approve when the risk is acceptable.",
          "reject": "Reject when the risk is unacceptable."
        }
      }
    }
  }'

请求体

字段	类型	必需	说明
`model`	`string`	✅	决策模型代号，最长 128 个字符。
`state`	`null` \| `string` \| `object` \| `array`	✅	供模型判断的业务状态。
`questions`	`object`	✅	1～32 个问题；键为问题 ID，非空且最长 128 个字符。
`assets`	`object`	❌	图片资源，以引用字符串为键；资源引用可放在 `state`、`instructions` 或 `criteria` 中。
`session_id`	`string`	❌	缓存亲和会话标识，最长 256 个字符；只用于平台选路，不透传上游。

除上述平台字段外，请求中的 System One 扩展字段会按原协议透传。请求体上限为 32 MiB，包含 JSON、base64 文本以及 multipart 边界。

JSON 和 multipart 均支持通过 Content-Encoding 使用单层 gzip、x-gzip 或 zstd 压缩；压缩前后分别受 32 MiB 限制，zstd 解码窗口最多 8 MiB。官方 SDK 默认压缩较大的请求；若服务环境不支持所用格式而返回 415，可在 SDK 中设置 compression: false。

问题类型

每个问题都必须包含 type，可选包含 instructions。支持以下类型：

`type`	`criteria`	用途
`choice`	对象，包含 1～255 个选项	从命名选项中选择结果；选项名非空且最长 128 个字符。
`score`	数组，包含 2～10 个等级	在有序等级中评分。
`noul`	可省略、为 `null` 或对象	返回“是”或“真”的概率，范围为 0～1。
`box`	不使用	返回图片中目标的归一化边界框与置信度；需要图片资源，上游模型需要 Jev 1.14 或更新版本。`instructions` 可省略或为 `null`。

图片输入与定位

图片和 box 目前是 TypeSafe 的实验能力，请求必须携带 TypeSafe-Danger-Zone-Images: true。Jev 1.13 和 1.14 都支持图片；box 需要 Jev 1.14。model 仍填写平台模型目录中的代号。

multipart 上传

推荐直接上传图片文件。第一部分必须命名为 request，内容为 JSON；assets 中的 part 指向图片文件部分。各部分名称必须非空且唯一，每个图片部分只能由一个资源使用。

curl https://51kik.com/decision/v1/systemone \
  -H 'Authorization: Bearer sk-xxxxxxxx' \
  -H 'TypeSafe-Danger-Zone-Images: true' \
  -F 'request={"model":"jev","state":{"photo":"photo-ref-001"},"assets":{"photo-ref-001":{"type":"image","part":"photo"}},"questions":{"package":{"type":"box","instructions":"Locate the package in `photo`."}}};type=application/json' \
  -F 'photo=@photo.jpg;type=image/jpeg'

JSON base64

JSON 请求沿用 Content-Type: application/json，在资源中提供图片格式和纯 base64 正文：

{
  "model": "jev",
  "state": { "photo": "photo-ref-001" },
  "assets": {
    "photo-ref-001": {
      "type": "image",
      "format": "jpg",
      "data_base64": "<padded base64 of photo.jpg>"
    }
  },
  "questions": {
    "package_visible": { "type": "noul", "instructions": "Is a package visible in `photo`?" }
  }
}

type 可省略；format 为 png、jpg 或 jpeg。base64 必须使用标准字符和所需的 = 填充，不含空白、换行或 data: 前缀。multipart 资源同时提供 part 和 data_base64 时，以 part 为准。

只接受静态 PNG/JPEG。每边为 280～1568 px，单文件最多 16 MiB（base64 按解码后大小计算）。
整个请求、所有图片经上游处理后的总大小，以及引用展开后的请求分别受 32 MiB 限制。超限会拒绝整个请求。
每个资源必须在 state、instructions 或 criteria 的字符串值中出现。建议每张图片使用独立 UUID，避免引用字符串意外匹配其他文本；同一引用多次出现会重复计入展开大小。
box 返回 top、bottom、left、right（均为 0～1）和 confidence；上游未提供置信度时，confidence 为 null。目标可能不存在时，配合 noul 判断是否可见。
图片 Token 已包含在 usage.input_tokens 中，按模型目录的输入单价计费。调用记录保留图片引用和元数据，省略 base64 正文。

完整资源规则见 TypeSafe 官方图片文档和 Box 文档。

成功响应

网关保留上游 System One 响应。成功响应至少包含：

{
  "model": "<resolved-upstream-model>",
  "answers": {
    "review": { "...": "System One answer fields" }
  },
  "usage": {
    "input_tokens": 123,
    "output_tokens": 18
  }
}

answers 中每个答案的内部字段由实际 System One 模型返回；调用方应按所用模型的协议处理，不要假定为固定结构。usage 用于计费，输入和输出 Token 单价可在决策模型目录查看。

可选请求头

请求头	说明
`TypeSafe-Danger-Zone-Images`	使用图片或 `box` 时必须为 `true`，网关转发给上游。
`Idempotency-Key`	最长 255 个字符。重试同一业务请求时使用稳定值；网关会派生上游幂等键，但不会缓存或重放响应。
`x-session-id`	缓存亲和会话标识；仅在请求体未提供 `session_id` 时使用。
`x-trace-id`	业务追踪 ID，写入调用与用量记录。
`x-user-id`	你们产品中的终端用户 ID。
`x-agent-name`	调用方 Agent 或服务名。

错误响应

错误使用 OpenAI 风格的统一结构：

{
  "error": {
    "message": "model is required and must not exceed 128 characters",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

HTTP 状态	含义
`400`	JSON/multipart 或压缩正文解析失败、图片资源或开关请求头无效，或上游拒绝图片。
`401`	缺少、格式错误或无效的 API Key。
`413`	请求体、图片或资源引用超过大小限制。
`415`	请求 Content-Type 或 Content-Encoding 不受支持。
`422`	`state`、`model`、`questions`、问题类型、幂等键或会话标识校验失败。
`502`	所有可用上游线路失败，或上游响应格式无效。