文档中心

火山方舟

System One API（beta）

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

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

说明

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

鉴权

本接口支持鉴权方式如下，详情请参见 Base URL 及鉴权。

API Key 鉴权，请在 API Key 管理页面，获取长效 API Key。

请求参数

在 HTTP 请求头中传入。

注意

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

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

Body 参数

model string 必选 | 模型 ID

*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 时，模型使用默认判断方式。

questions object 必选 | 问题集合

*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 时，模型使用默认判断方式。

key object 必选 | 问题配置

是非判断 object

分类选择 object

*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 必须且只能填写一个。

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

*多模态数组 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 必须且只能填写一个。

多模态数组 object[]

图片 object

响应参数

响应头参数

在 HTTP 响应头中返回。

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

响应体参数

*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。

answers object | 答案集合

*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。

key object | 评估答案

分类选择 object

评分判断 object

model string | 模型 ID

usage object | token 用量

是非判断

分类选择

评分判断

发起调试等同于请求真实调用，可能产生云产品费用，请谨慎操作！

Request

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
  }
}

最近更新时间：2026.10.15 18:57:54

这个页面对您有帮助吗？

有用

无用