# System One API（beta）

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

`POST https://ark.cn-beijing.volces.com/api/v1/systemone`

调用 System One API 对同一份输入执行一组结构化判定问题，并同步返回与问题 ID 对应的答案。该接口不支持流式输出。

> **说明**
>
> System One API 当前支持最大 128k 上下文窗口，单次请求中的 `state` 和 `questions` 共同占用上下文窗口。

## 鉴权

本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](/docs/base-url-and-authentication)。

* API Key 鉴权，请在 [API Key 管理](https://ark.volcengine.com/region:cn-beijing/apiKey) 页面，获取长效 API Key。

---

<span id="request-parameters"></span>
## 请求参数

### Header 参数

> 在 HTTP 请求头中传入。

> **注意**
>
> System One API 当前处于 beta 测试阶段。调用该接口时，必须在 HTTP 请求头中传入 `ark-beta-systemone-api: true`。

**ark-beta-systemone-api** `string` `必选` | System One API 标识

调用 System One API 时，需将该请求头设置为 `true`。

### Body 参数

**model** `string` `必选` | 模型 ID

本次评估使用的模型 ID 或推理接入点 ID，不可为空或仅包含空白字符。

当前支持的模型为 `doubao-seed-2-1-lite-260915`。

**questions** `object` `必选` | 问题集合

以自定义问题 ID 为键提交 `noul`、`choice`、`score` 三类可混用的问题配置。

> **说明**
>
> - `questions` 至少包含 1 个问题，各问题共享同一份 `state`，并独立评估。
> - 问题 ID 仅用于关联请求与响应，不参与模型评估。响应顺序不保证与请求顺序一致，请按问题 ID 读取对应结果。

**key** `object` `必选` | 问题配置

`questions.key`

调用方自定义问题 ID 对应的评估问题配置；每道问题均针对同一 `state` 独立评估。

是非判断 `object`

判断命题是否成立。

**type** `string` `必选` | 问题类型

`questions.key.type`

指定问题的类型。

取值固定为 `noul`。

**criteria** `object` | 结果说明

`questions.key.criteria`

为 `noul` 问题配置“是”和“否”两种结果的说明。`criteria` 不能传入 `null`；省略 `criteria` 或传入空对象时，表示不补充自定义结果说明。

**false** `string / object / array / null` | “否”说明

`questions.key.criteria.false`

回答为“否”时使用的结果说明。

**true** `string / object / array / null` | “是”说明

`questions.key.criteria.true`

回答为“是”时使用的结果说明。

**instructions** `string / object / array / null` | 判断指令

`questions.key.instructions`

定义本题的判断目标、范围和依据。省略或传入 `null` 时，模型使用默认判断方式。

分类选择 `object`

从调用方提供的候选选项中选择一项。

**criteria** `object` `必选` | 候选选项

`questions.key.criteria`

定义候选选项名称到选项说明的映射；选项名称参与模型推理。

> **注意**
>
> `criteria` 支持配置 `[1, 255]` 个候选选项。重复的 JSON 属性名以后一个值为准，建议使用唯一选项名。

**key** `string / object / array / null` `必选` | 选项说明

`questions.key.criteria.key`

用于帮助模型理解对应选项含义的说明内容。

**type** `string` `必选` | 问题类型

`questions.key.type`

指定问题的类型。

取值固定为 `choice`。

**instructions** `string / object / array / null` | 判断指令

`questions.key.instructions`

定义本题的判断目标、范围和依据。省略或传入 `null` 时，模型使用默认判断方式。

评分判断 `object`

根据调用方提供的有序评分档位进行评分判断。

**criteria** `string / object / array[]` `必选` | 评分标准

`questions.key.criteria`

定义按程度从低到高排列的评分档位标准，数组位置决定从 `0` 开始的档位编号。

> **注意**
>
> `criteria` 支持配置 `[1, 10]` 个评分档位。

**type** `string` `必选` | 问题类型

`questions.key.type`

指定问题的类型。

取值固定为 `score`。

**instructions** `string / object / array / null` | 判断指令

`questions.key.instructions`

定义本题的判断目标、范围和依据。省略或传入 `null` 时，模型使用默认判断方式。

**state** `string / object / string[] / object[]` `必选` | 评估内容

待评估内容，支持单个字符串、字符串数组、任意 JSON 对象或多模态内容对象数组。所有问题均基于同一份内容独立评估。

> **注意**
>
> 仅支持字符串数组或对象数组，不能混用字符串和对象，也不能包含数字、布尔值、`null` 或嵌套数组。空数组按文本输入处理。

单个字符串 `string`

单段纯文本。

JSON 对象 `object`

带自定义字段的结构化纯文本对象，允许嵌套值和显式 null 成员。

字符串数组 `string[]`

多段纯文本组成的字符串数组。

多模态数组 `object[]`

由文本、图片、视频或音频元素组成的多模态对象数组。

文本 `object`

文本内容元素。

**text** `string / string[] / object` `必选` | 文本内容

`state.text`

原生文本评估内容，支持字符串、仅包含字符串的数组或任意 JSON 对象。

**type** `string` `必选` | 内容类型

`state.type`

指定多模态内容的类型。

取值固定为 `text`。

图片 `object`

图片内容元素。

**type** `string` `必选` | 内容类型

`state.type`

指定多模态内容的类型。

取值固定为 `image`。

**detail** `string` `默认值 high` | 图片精细度

`state.detail`

指定图片输入的处理精细程度。可选值：`low`、`high`。

> **说明**
>
> 同时设置 `detail` 和 `image_pixel_limit` 时，以 `image_pixel_limit` 为准。

**file_id** `string` | 图片文件 ID

`state.file_id`

通过图片文件 ID 提供待评估图片。与 `image_url` 必须且只能填写一个。

**image_pixel_limit** `object` | 像素限制

`state.image_pixel_limit`

设置图片下游处理的像素数量范围。与 `detail` 同时设置时，服务端使用 `image_pixel_limit`。

> **说明**
>
> 同时传入 `min_pixels` 和 `max_pixels` 时，`min_pixels` 不能大于 `max_pixels`。

**max_pixels** `integer` | 最大像素数

`state.image_pixel_limit.max_pixels`

指定图片处理的最大像素数。

**最小值**：`1`

**min_pixels** `integer` | 最小像素数

`state.image_pixel_limit.min_pixels`

指定图片下游处理的最小像素数。

**最小值**：`1`

**image_url** `string` | 图片地址

`state.image_url`

通过公网 URL 或 Base64 数据 URL 提供待评估图片。与 `file_id` 必须且只能填写一个。

视频 `object`

视频内容元素。

**type** `string` `必选` | 内容类型

`state.type`

指定多模态内容的类型。

取值固定为 `video`。

**file_id** `string` | 视频文件 ID

`state.file_id`

通过视频文件 ID 提供待评估视频。与 `video_url` 必须且只能填写一个。

**fps** `number` `默认值 1.0` | 采样帧率

`state.fps`

指定视频帧采样频率，单位为帧/秒。

**取值范围**：`[0.2, 5]`

**video_url** `string` | 视频地址

`state.video_url`

通过公网 URL 或 Base64 数据 URL 提供待评估视频。与 `file_id` 必须且只能填写一个。

音频 `object`

音频内容元素。

**type** `string` `必选` | 内容类型

`state.type`

指定多模态内容的类型。

取值固定为 `audio`。

**audio_url** `string` | 音频地址

`state.audio_url`

通过公网 URL 或 Base64 输入提供待评估音频。与 `file_id` 必须且只能填写一个。

**file_id** `string` | 音频文件 ID

`state.file_id`

通过音频文件 ID 提供待评估音频。与 `audio_url` 必须且只能填写一个。

## 响应参数

### 响应头参数

> 在 HTTP 响应头中返回。

**X-Request-Id** `string` `必选` | 请求标识

成功响应的请求标识，用于排查和追踪请求；该字段通过 HTTP 响应头返回，不会出现在成功响应 JSON 中。

### 响应体参数

**answers** `object` | 答案集合

按问题 ID 返回评估答案的映射。属性名与请求 `questions` 中的问题 ID 完全一致，属性值类型与对应问题类型一致。

**key** `object` | 评估答案

`answers.key`

请求 `questions` 中同名问题 ID 对应的评估答案；答案类型与对应问题的类型一致。

是非判断 `object`

是非判断结果。

**noul** `number` | 是的概率

`answers.key.noul`

结果符合 `criteria.true` 的概率。省略 `criteria` 时，表示判断条件成立的概率。

> **说明**
>
> 接近 `0.5` 表示模型不确定，不表示程度中等。`noul` 类型不返回 `confidence` 或 `probabilities`。

**取值范围**：`[0, 1]`

**type** `string` | 回答类型

`answers.key.type`

指定回答结果的类型。

取值固定为 `noul`。

分类选择 `object`

分类选择结果。

**choice** `string` | 选择结果

`answers.key.choice`

概率最高的选项名称，取值来自请求 `criteria` 的属性名。

**confidence** `number` | 结果置信度

`answers.key.confidence`

模型返回的选择结果置信度。

**取值范围**：`[0, 1]`

**probabilities** `object` | 选项概率

`answers.key.probabilities`

各候选选项到对应概率的映射。

> **说明**
>
> 该映射包含概率为 `0` 的选项；各项概率之和约为 `1`，可能存在浮点误差。

**key** `number` | 单项概率

`answers.key.probabilities.key`

对应候选选项的预测概率。

**取值范围**：`[0, 1]`

**type** `string` | 回答类型

`answers.key.type`

指定回答结果的类型。

取值固定为 `choice`。

评分判断 `object`

评分判断结果。

**confidence** `number` | 结果置信度

`answers.key.confidence`

模型返回的评分判断结果置信度。

**取值范围**：`[0, 1]`

**legend** `object` | 评分档位

`answers.key.legend`

使用从 `0` 开始的字符串编号，将各评分档位映射到请求 `criteria` 中对应的原始内容，并保留其字符串、对象或数组形态。

**key** `string / object / array` | 档位说明

`answers.key.legend.key`

对应评分档位的原始 `criteria` 内容，保留字符串、对象或数组形态及嵌套 JSON。

**probabilities** `object` | 档位概率

`answers.key.probabilities`

各评分档位对应的预测概率映射。

> **说明**
>
> 键为从 `0` 到 `N-1` 的评分档位编号，包含概率为 `0` 的档位；各项概率之和约为 `1`，可能存在浮点误差。

**key** `number` | 档位概率

`answers.key.probabilities.key`

对应评分档位的预测概率。

**取值范围**：`[0, 1]`

**score** `number` | 期望分数

`answers.key.score`

各评分档位编号按对应预测概率加权求和得到的期望分数。结果支持小数，且不做归一化。

> **说明**
>
> 实际最大值由请求 `criteria` 的档位数 N 决定，为 N−1；该值不是概率最高档位的编号。

**取值范围**：`[0, 9]`

**type** `string` | 回答类型

`answers.key.type`

指定回答结果的类型。

取值固定为 `score`。

**model** `string` | 模型 ID

执行本次评估的模型 ID。

**usage** `object` | token 用量

本次评估的 token 用量信息，包含输入 token 数和输出 token 数。

**input_tokens** `integer` | 输入 token 数

`usage.input_tokens`

本次评估请求消耗的输入 token 数量。

**最小值**：`0`

**output_tokens** `integer` | 输出 token 数

`usage.output_tokens`

本次评估响应生成的输出 token 数量。

**最小值**：`0`


## 代码示例

## 是非判断

### cURL


#### Request

```bash
curl "https://ark.cn-beijing.volces.com/api/v1/systemone" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "ark-beta-systemone-api: true" \
  -d '{
    "model": "doubao-seed-2-1-lite-260915",
    "state": "客户反馈：收到的杯子裂了，请退回货款。",
    "questions": {
      "refund_requested_v1": {
        "type": "noul",
        "instructions": "客户是否明确要求退款？",
        "criteria": {
          "true": "客户明确提出退款、退回货款或拒绝换货。",
          "false": "客户未提出退款诉求，或仅咨询商品、物流、售后政策。"
        }
      }
    }
  }'
```

#### Response

```
{
  "model": "doubao-seed-2-1-lite-260915",
  "answers": {
    "refund_requested_v1": {
      "type": "noul",
      "noul": 0.96
    }
  },
  "usage": {
    "input_tokens": 76,
    "output_tokens": 16
  }
}
```

## 分类选择

### cURL


#### Request

```bash
curl "https://ark.cn-beijing.volces.com/api/v1/systemone" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "ark-beta-systemone-api: true" \
  -d '{
    "model": "doubao-seed-2-1-lite-260915",
    "state": "客户反馈：收到的杯子有裂纹，申请退款，不接受换货。",
    "questions": {
      "routing_team_v1": {
        "type": "choice",
        "instructions": "根据客户反馈的主要问题选择优先处理团队。",
        "criteria": {
          "财务": "扣款、发票或退款到账问题。",
          "质量": "商品损坏、质量缺陷或与描述不符。",
          "物流": "配送延迟、丢件或物流状态问题。",
          "信息不足": "缺少判断主要问题所需的信息。"
        }
      }
    }
  }'
```

#### Response

```
{
  "model": "doubao-seed-2-1-lite-260915",
  "answers": {
    "routing_team_v1": {
      "type": "choice",
      "choice": "质量",
      "confidence": 0.91,
      "probabilities": {
        "财务": 0.04,
        "质量": 0.91,
        "物流": 0.02,
        "信息不足": 0.03
      }
    }
  },
  "usage": {
    "input_tokens": 113,
    "output_tokens": 32
  }
}
```

## 评分判断

### cURL


#### Request

```bash
curl "https://ark.cn-beijing.volces.com/api/v1/systemone" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "ark-beta-systemone-api: true" \
  -d '{
    "model": "doubao-seed-2-1-lite-260915",
    "state": "客户反馈：退款金额一直不到账，我已经准备向监管平台投诉。",
    "questions": {
      "risk_level_v1": {
        "type": "score",
        "instructions": "该工单的处理风险等级是多少？",
        "criteria": [
          "风险较低，不涉及资金、合规或客户投诉。",
          "存在一定风险，需要补充材料或人工确认。",
          "风险较高，涉及资金损失、投诉升级或合规问题。"
        ]
      }
    }
  }'
```

#### Response

```
{
  "model": "doubao-seed-2-1-lite-260915",
  "answers": {
    "risk_level_v1": {
      "type": "score",
      "score": 1.82,
      "confidence": 0.88,
      "probabilities": {
        "0": 0.03,
        "1": 0.12,
        "2": 0.85
      },
      "legend": {
        "0": "风险较低，不涉及资金、合规或客户投诉。",
        "1": "存在一定风险，需要补充材料或人工确认。",
        "2": "风险较高，涉及资金损失、投诉升级或合规问题。"
      }
    }
  },
  "usage": {
    "input_tokens": 121,
    "output_tokens": 63
  }
}
```