Decisions API
Decisions API 用来让模型对一段内容做类型化判断,而不是生成文本。你提供要判断的内容和一组问题,模型对每个问题返回一个结构化答案:是/否的概率、从选项中选一个、或在分级量表上打分,并附带每个选项的概率和置信度。
适合分类、路由、审核、打分、过滤等需要「程序直接拿结果做分支」的场景。模型只能在你给定的选项和分级里作答,不会返回选项以外的内容,也不需要解析自由文本。
首次使用判断模型时,建议先阅读 Jev 使用指南,其中包含快速开始、问题设计、返回结果说明与场景示例。本页为字段级参考。
端点
三条路径背后是同一批模型、同一套计费,区别只在请求和响应的格式。按你使用的客户端选一条:
认证方式与其他接口相同:Authorization: Bearer <你的 OFOXAI_API_KEY>。只支持非流式,一次请求同步返回全部答案。
可用模型
支持该接口的完整模型列表见模型页 。对普通对话模型(如 openai/gpt-4o)调用会返回 endpoint_not_supported。
统一格式:/v1/decisions
请求参数
输入格式
input 支持三种写法:
- 文本:一个字符串。
"input": "客户留言:我被重复扣款了,两封邮件都没人回,今天必须退款。" - 结构化数据:一个 JSON 对象,原样交给模型。问题里可以用反引号引用字段名,如
`message`。"input": { "ticket_id": 4812, "message": "我被重复扣款了。", "plan": "pro" } - 消息数组:
[{ "role", "content" }],content为字符串或内容块列表,内容块只支持input_text与input_image。图片仅对可读图片的模型有效,Jev 不读图片,传图片会返回 400。
问题对象
请求示例
cURL
curl https://api.ofox.ai/v1/decisions \
-H "Authorization: Bearer $OFOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "typesafe/jev-latest",
"input": "客户留言:我被重复扣款了,两封邮件都没人回,今天必须退款。",
"questions": [
{ "type": "predicate", "name": "is_frustrated", "instructions": "客户是否不满?" },
{
"type": "choice",
"name": "category",
"instructions": "这张工单属于哪一类?",
"choices": [
{ "value": "billing", "description": "扣款与退款" },
{ "value": "bug", "description": "产品故障" },
{ "value": "other", "description": "其他" }
]
},
{
"type": "score",
"name": "urgency",
"instructions": "需要多快由人工回复?",
"levels": [
{ "label": "low", "description": "一周内即可" },
{ "label": "medium", "description": "应尽快回复" },
{ "label": "high", "description": "今天必须回复" }
]
}
]
}'响应格式
{
"model": "typesafe/jev-latest",
"answers": [
{ "type": "predicate", "name": "is_frustrated", "probability": 0.97 },
{
"type": "choice",
"name": "category",
"choice": "billing",
"confidence": 1,
"probabilities": [
{ "value": "billing", "probability": 1 },
{ "value": "bug", "probability": 0 },
{ "value": "other", "probability": 0 }
]
},
{
"type": "score",
"name": "urgency",
"score": 2,
"confidence": 1,
"legend": { "0": "low: 一周内即可", "1": "medium: 应尽快回复", "2": "high: 今天必须回复" },
"probabilities": [
{ "value": 0, "label": "low", "probability": 0 },
{ "value": 1, "label": "medium", "probability": 0 },
{ "value": 2, "label": "high", "probability": 1 }
]
}
],
"usage": { "prompt_tokens": 407, "completion_tokens": 72, "total_tokens": 479 }
}answers 与 questions 一一对应、顺序相同。各类型答案的字段:
TypeSafe 原生格式:/typesafe/v1/systemone
与 TypeSafe 官方 API 的请求和响应格式一致,适合直接使用 TypeSafe SDK 或迁移已有代码。和统一格式相比有三处不同:
curl https://api.ofox.ai/typesafe/v1/systemone \
-H "Authorization: Bearer $OFOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "jev-latest",
"state": "Help! My payouts have been failing for 3 days.",
"questions": {
"is_urgent": { "type": "noul", "instructions": "Does this convey urgency?" },
"department": {
"type": "choice",
"instructions": "Which team should handle this?",
"criteria": {
"billing": "Payments, invoicing, refunds",
"technical": "Bugs, outages, integrations",
"sales": "Pricing, upgrades"
}
},
"frustration": {
"type": "score",
"instructions": "How frustrated is the customer?",
"criteria": ["Calm", "Frustrated", "Very angry"]
}
}
}'{
"model": "typesafe/jev-latest",
"answers": {
"is_urgent": { "type": "noul", "noul": 0.95 },
"department": {
"type": "choice",
"choice": "billing",
"confidence": 0.85,
"probabilities": { "billing": 0.9, "technical": 0.1, "sales": 0 }
},
"frustration": {
"type": "score",
"score": 1.03,
"confidence": 0.95,
"legend": { "0": "Calm", "1": "Frustrated", "2": "Very angry" },
"probabilities": { "0": 0, "1": 0.97, "2": 0.03 }
}
},
"usage": { "input_tokens": 399, "output_tokens": 73 }
}SDK 接入
OpenAI SDK
OpenAI 官方 SDK 提供 client.decisions.create(),base_url 指向 https://api.ofox.ai/v1 即可,请求体使用统一格式。示例见上方 Python 标签页。需使用包含 Decisions API 的 SDK 版本(实测 openai Python 3.31.0 可用)。
TypeSafe SDK
TypeSafe 官方 SDK 把 base_url 指向 https://api.ofox.ai/typesafe,api_key 换成 OfoxAI API Key,其余代码不变:
Python
# pip install typesafe-sdk
import os
from typesafe_sdk import TypeSafeClient, Noul, Choice, Score
with TypeSafeClient(base_url="https://api.ofox.ai/typesafe", api_key=os.environ["OFOX_API_KEY"]) as client:
r = client.system_one(
model="jev-latest",
state={"message": "我被重复扣款了,两封邮件都没人回,今天必须退款。"},
questions={
"urgent": Noul(instructions="客户是否要求今天处理?"),
"dept": Choice(
instructions="应该由哪个团队处理?",
criteria={"billing": "扣款、发票、退款", "technical": "故障、接入", "sales": "价格、升级"},
),
"anger": Score(instructions="客户有多不满?", criteria=["平静", "不满但礼貌", "非常愤怒"]),
},
)
print(r.nouls["urgent"].noul) # 0.98
print(r.choices["dept"].choice) # billing
print(r.scores["anger"].score) # 1.92概率与置信度
- 概率回答「答案是什么」:
probability、probabilities是模型对各个答案的校准概率。 - 置信度回答「该不该信这次判断」:
confidence由概率分布推出,分布越集中越高。两个选项各 0.5 时,choice仍会给出一个,但confidence很低。
常见做法是在代码里设阈值:置信度高时自动执行,低时转人工或交给更强的模型复核。
计费
按 token 计费,单价见模型页 。typesafe/jev-latest 只按输入 token 计费,输出不计费(completion_tokens / output_tokens 照常返回)。
一次请求里的所有问题共享同一份输入,把多个问题放进同一请求比拆成多次调用便宜得多,也更快。
限制
常见报错
其他通用错误见错误处理。