Decisions
OpenAI Decisions 接口(公开测试版)。对文本、图片或图文输入一次提交多个问题,返回结构化答案:条件为真的概率、从固定选项中选一个、按等级打分。比 Responses 快约 10 倍,适合分类、路由与优先级排序。
三种问题类型:predicate 返回条件为真的概率(0~1);choice 从你给的选项中选一个,附各选项概率与置信度;score 按从低到高排列的等级打分,结果是等级下标(从 0 开始)的概率加权平均,可以落在两个等级之间。需要按自定义 JSON schema 生成对象(字段抽取、写解释)时用 Responses 的 Structured Outputs,需要模型发起工具调用时用 function calling。
公开测试版接口,可用模型为 gpt-6-luna 与 Clef 系列(clef / clef-flash / clef-omni,以价格页为准),只支持非流式。只按输入 token 计费,gpt-6-luna 单价见价格页分档价格里「调用 /v1/decisions 时」一档。使用官方 SDK 需不低于:Python 3.26.0、JavaScript 7.30.0、Go 3.73.0、Ruby 0.101.0、Java 4.78.0。
接口地址
| 方法 |
地址 |
POST |
https://ai.czl.net/v1/decisions |
请求头
Authorization: Bearer sk-your-api-key
Content-Type: application/json
请求参数
| 参数 |
类型 |
必填 |
说明 |
model |
string |
是 |
模型名称,如 gpt-6-luna 或 Clef 系列(以价格页为准) |
input |
string | array |
是 |
所有问题共享的输入:字符串,或 role 为 user 的消息数组(content 为字符串或 input_text / input_image 片段) |
questions |
array |
是 |
问题列表,每项含 type(predicate / choice / score)、instructions、name(建议填且唯一);choice 需 choices[{value, description}],score 需 levels[{label, description}](从低到高) |
safety_identifier |
string |
否 |
终端用户的不透明标识(建议用哈希后的用户 ID),用于滥用检测 |
请求示例
{
"model": "gpt-6-luna",
"input": "I was charged twice for my order.",
"questions": [
{
"type": "choice",
"name": "department",
"instructions": "Which department should handle this complaint?",
"choices": [
{
"value": "billing",
"description": "Payments, invoices, and refunds."
},
{
"value": "technical",
"description": "Problems using the product."
},
{
"value": "shipping",
"description": "Delivery and tracking."
},
{
"value": "other",
"description": "Requests outside these categories."
}
]
}
]
}
响应示例
{
"model": "gpt-6-luna",
"answers": [
{
"type": "choice",
"name": "department",
"choice": "billing",
"probabilities": [
{
"value": "billing",
"probability": 0.95
},
{
"value": "technical",
"probability": 0.02
},
{
"value": "shipping",
"probability": 0.01
},
{
"value": "other",
"probability": 0.02
}
],
"confidence": 0.93
}
],
"usage": {
"input_tokens": 96,
"input_tokens_details": {
"cached_tokens": 0,
"cache_write_tokens": 0
},
"output_tokens": 1,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 97
}
}
协议细节
一、请求结构
| 字段 |
作用 |
model |
gpt-6-luna 或 Clef 系列(以价格页为准) |
input |
所有问题共享的输入:字符串,或包含文本与图片的 user 消息数组 |
questions |
要评估的问题:每个问题的类型、说明,以及可选项或打分等级 |
响应里的 answers 按 questions 的顺序返回。给每个问题起一个唯一的 name,答案会原样带回,便于按名字取结果(未填时答案里的 name 为 null,只能按下标对应)。
二、问题类型
| type |
适用 |
额外字段 |
主要结果 |
predicate |
判断某个条件,如图片里有无明显损坏、段落是否相关 |
无 |
probability:条件为真的概率估计(0~1) |
choice |
从无序类别中选一个,如分派部门、内容类别 |
choices[]:{ value, description? } |
choice:你给出的某个 value |
score |
按有序等级评估,如问题严重程度 |
levels[]:{ label, description? },从低到高排列 |
score:等级下标的概率加权平均 |
choice 的 value 可以是字符串或布尔值("true" 与 true 是不同的选项)。选项含义要互不重叠,description 写清什么情况选它;类别覆盖不全时加一个 "other" 兜底
score 的等级下标从 0 开始;相邻等级的判定标准要有明确区别
三、答案格式
| type |
字段 |
predicate |
name、probability |
choice |
name、choice、probabilities[]:{ value, probability }、confidence |
score |
name、score、probabilities[]:{ value, label, probability }、confidence |
refusal |
name |
某个问题可能单独返回 type: "refusal"(拒绝回答该问题),其余问题照常给出答案,调用方要按 type 分支处理。
score 示例:三个等级 Cosmetic / Workaround available / Fully blocked 对应下标 0 / 1 / 2,概率 0.1 / 0.7 / 0.2 时:
{
"type": "score",
"name": "severity",
"score": 1.1,
"probabilities": [
{ "value": 0, "label": "Cosmetic", "probability": 0.1 },
{ "value": 1, "label": "Workaround available", "probability": 0.7 },
{ "value": 2, "label": "Fully blocked", "probability": 0.2 }
],
"confidence": 0.55
}
score = 0×0.1 + 1×0.7 + 2×0.2 = 1.1,会落在两个等级之间;只想要一个确定类别时用 choice。
四、怎么用这些结果
predicate 返回条件为真的概率;choice 与 score 返回概率分布和单独的 confidence
- 用你业务里已标注的样本定阈值(路由、过滤或转人工),按误判与漏判的代价取舍,例如损坏概率高于阈值的照片进入人工复核
五、多个问题
- 相互独立的问题放进同一个
questions 数组共享输入,类型可以各不相同(例如同一张商品照片同时判断有无损坏、分类商品品类)
- 依赖前一个答案的问题要分开请求(例如先判断有无损坏,再决定要不要问维修类别)
- 问题围绕可观察的判断标准来写,不同关注点拆成不同问题
- 字符串:直接作为共享输入
- 消息数组:只支持
role: "user" 的消息,content 为字符串或片段数组
{ "type": "input_text", "text": "..." }
{ "type": "input_image", "image_url": "data:image/png;base64,...", "detail": "auto" }(detail 可选 low / high / auto / original)
- 图片只支持 base64 data URL,不支持 http(s) 图片链接与
file_id;整个请求最多 128 张图片
- 不支持 system / assistant 角色、函数调用、文件、音频与 item 引用
图文示例(检查商品照片有无明显损坏):
IMAGE_BASE64="$(base64 < product.png | tr -d '\r\n')"
curl "https://ai.czl.net/v1/decisions" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
--data-binary @- <<JSON
{
"model": "gpt-6-luna",
"input": [{
"role": "user",
"content": [
{"type": "input_text", "text": "Inspect the product in this photo."},
{"type": "input_image", "image_url": "data:image/png;base64,$IMAGE_BASE64"}
]
}],
"questions": [{
"type": "predicate",
"name": "visible_damage",
"instructions": "Does the product have visible damage, such as a crack, tear, or dent? Ignore shadows and damage to the packaging."
}]
}
JSON
Python SDK:
from openai import OpenAI
client = OpenAI(base_url="https://ai.czl.net/v1", api_key="sk-your-api-key")
decision = client.decisions.create(
model="gpt-6-luna",
input="Export fails in Safari but works in Chrome.",
questions=[
{
"type": "score",
"name": "severity",
"instructions": "How severe is this issue?",
"levels": [
{"label": "Cosmetic", "description": "Appearance only; no lost functionality."},
{"label": "Workaround available", "description": "A task fails, but another way works."},
{"label": "Fully blocked", "description": "A task fails with no workaround."},
],
}
],
)
answer = decision.answers[0]
if answer.type == "refusal":
print(f"Refused: {answer.name}")
elif answer.type == "score":
print(f"Severity: {answer.score} (confidence: {answer.confidence})")
七、计费
- 只按输入 token 计费,缓存读取、缓存写入与输出 token 都不收费
- 长上下文的输入加价同样适用
- 单价与 gpt-6-luna 在 Responses 等其它接口的价格不同,以价格页「调用 /v1/decisions 时」这一档为准
- 控制台日志里的 token 数与响应
usage 一致:缓存读取与输出 token 照常列出,单价为 $0
八、错误
| HTTP |
error.code |
error.type |
含义 |
| 400 |
不固定(如 missing_required_parameter / invalid_value / invalid_request) |
czlai_error |
参数非法(如缺少 questions、图片不是 data URL、使用了不支持的消息角色),message 为具体原因,param 指出出错的字段 |
| 401 |
— |
czlai_error |
API key 无效 / 已过期 / 已停用 |
| 402 |
insufficient_user_quota |
czlai_error |
余额或套餐额度不足 |
| 404 |
model_not_found |
czlai_error |
模型不存在, 或当前账号无权访问 |
| 429 |
— |
czlai_error |
触发速率限制 |
| 503 |
model_unavailable |
czlai_error |
模型当前不可用, 稍后重试可能成功 |
| 504 |
gateway_timeout |
czlai_error |
网关未能在重试预算内完成请求 |
| 其余 4xx / 5xx |
不固定 |
system_error |
模型侧失败, 状态码为原始状态码 |
错误响应格式与其它 OpenAI 兼容接口一致:{ "error": { "message", "type", "code" } }。
九、Clef 系列的原生写法
Clef 系列模型(如 cloudflare/clef)同时支持两种写法,响应格式跟随请求格式:
| 写法 |
请求 |
响应 |
| OpenAI |
input + questions 数组(同上文) |
answers 数组(同上文) |
| Clef 原生(System One) |
state + questions 对象(以问题 id 为 key) |
answers 对象(以问题 id 为 key) |
原生写法:state 为字符串或结构化数据;问题类型写 noul(是 / 否)/ choice / score,选项写在 criteria 里(choice 为 { 选项: 说明 },score 为从低到高的等级数组);图片 / 音频 / 视频放 images / audio / videos(base64 data URL)。写法宽松:两种写法里是否题写 predicate / noul / boolean 均可;选项可写在 choices 或 criteria,元素可为字符串或 { value | name, description };等级可写在 levels 或 criteria,元素可为字符串或 { label | name, description };共享输入可用 state、input 或 messages。选项需 2–255 个、等级需 2–10 级,参数错误时报错会指出具体字段。
答案:noul 返回 { "type": "noul", "noul": 0.98 }(为真的概率),choice 返回 choice / probabilities(以选项为 key)/ confidence,score 另带 score 与 legend。
{
"model": "cloudflare/clef",
"state": "Checkout has been failing for every customer for the last hour.",
"questions": {
"urgent": { "type": "noul", "instructions": "Is this support request urgent?" },
"severity": {
"type": "score",
"instructions": "How severe is the customer impact?",
"criteria": ["No impact", "Minor", "Major", "Critical"]
}
}
}
响应:
{
"model": "cloudflare/clef",
"answers": {
"urgent": { "type": "noul", "noul": 0.98 },
"severity": {
"type": "score",
"score": 2.95,
"confidence": 0.91,
"probabilities": { "0": 0.004, "1": 0.004, "2": 0.026, "3": 0.966 },
"legend": { "0": "No impact", "1": "Minor", "2": "Major", "3": "Critical" }
}
},
"usage": { "input_tokens": 324, "output_tokens": 0 }
}
Markdown 原文