> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Jev

> TypeSafe Jev 决策模型：返回选项、分值、是非概率或图片框选结果，并附带置信度

## 简介

Jev 是 TypeSafe 推出的 **System One 决策模型**。它和对话模型不同，**不生成文字**，而是对你给出的内容（`state`）回答一组限定了答案范围的问题（`questions`），直接返回程序可以使用的结构化结果：

* **单选（choice）**：从你定义的选项里选一个，如「这张工单该分给哪个部门」。
* **打分（score）**：按你定义的档位打分，如「用户情绪有多激动：0 平静 / 1 不满 / 2 愤怒」。
* **是非（noul）**：返回「是」的概率，如「用户是否在要求退款」。
* **框选（box）**：在图片里找到描述的目标，返回它的上下左右四条边，如「找出车身上的划痕」。

一次请求可以同时问多个问题，内容只读一遍，每个问题独立作答。单选、打分和框选答案带置信度，是非答案返回概率，适合用来做工单分流、内容审核、情绪打分、意图识别、Agent 工具调用把关、模型路由等「快速判断」场景。

> [!NOTE]
>
> 请求结构与成功响应的业务字段遵循 TypeSafe 官方 [System One API](https://docs.typesafe.ai/api/system-one)。错误响应可能由平台封装，详见 [错误处理](#错误处理)。

> [!WARNING]
>
> Jev **不支持** OpenAI 的 `/v1/chat/completions`、`/v1/responses` 等对话接口，只能通过下文的 `/v1/systemone` 调用。它不会写回复、写代码或解释推理过程。

## 认证

**Authorization** `string` *required*

Bearer Token，如 `Bearer sk-xxxxxxxxxx`

**Content-Type** `string` *required*

`application/json`；用 multipart 上传图片时为 `multipart/form-data`，见 [multipart 上传图片](#multipart-上传图片)

**TypeSafe-Danger-Zone-Images** `string`

固定为 `true`。按官方规范，请求里带图片（`assets`）或框选题（`box`）时**必须**传。

**TypeSafe-Danger-Zone-Long-Context** `string`

固定为 `true`。打开长上下文模式，上下文上限从 64k 提到 262k，详见 [上下文长度](#上下文长度)。

API Key 在平台的 API 密钥页面创建。请勿将 API Key 写入前端代码、公开仓库或客户端安装包。

## 模型信息

| 模型名称 | 说明 | 题型 | 输入 |
| - | - | - | - |
| `jev-latest` | 最新正式版，当前指向 `jev-1.14.0` | choice / score / noul / box | 文本、图片 |
| `jev-preview` | 最新版本（含预览版），当前同样指向 `jev-1.14.0` | choice / score / noul / box | 文本、图片 |
| `jev-1.14.0` | Jev 1.14 固定版本 | choice / score / noul / box | 文本、图片 |
| `jev-1.13.0` | Jev 1.13 固定版本 | choice / score / noul（**不支持 box**） | 文本、图片 |

* `jev-latest`、`jev-preview` 是别名，官方发布新版本后会自动指向新版本，答案可能随之变化。响应里的 `model` 字段是实际作答的版本号。
* 如果你已经按某个版本调好了置信度阈值，建议直接用固定版本号，确认新版本效果后再切换。

| 项目 | 说明 |
| - | - |
| 接口类型 | 同步返回 |
| 流式输出 | 不支持 |
| 单次问题数量 | 不限，只要请求在上下文上限内 |
| 图片格式 | PNG、JPEG |
| 计费 | 只按输入 token 计费，输出 token 免费 |

## 接口地址

```http theme={null}
POST https://api.gravitex.ai/v1/systemone
```

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `model` | string | 是 | 模型名称，见 [模型信息](#模型信息) |
| `state` | string / object / array | 是 | 需要判断的内容，所有问题都针对它作答，详见 [state](#state) |
| `questions` | object | 是 | 问题集合，键是你给问题起的名字，值是问题定义，至少 1 个，详见 [questions](#questions) |
| `assets` | object | 否 | 图片集合，键是占位符，值是图片定义，详见 [assets](#assets) |

> [!NOTE]
>
> Jev 没有 `temperature`、`max_tokens` 这类采样参数，也不需要设置输出长度。

### state

需要判断的内容，三种写法任选：

* **字符串**：一段文本，如用户消息、工单内容、合同全文。
* **对象**：结构化数据，如 `{"subject": "重复扣款", "message": "请帮我处理"}`，适合把用户消息、订单记录、处理规则一起交给模型。
* **数组**：多段文本，如一组聊天记录。

```json theme={null}
"state": {
  "customer_message": "我的订单被扣了两次钱，已经三天了还没有人处理",
  "orders": [{ "id": "A1024", "charged_times": 2 }],
  "refund_policy": "重复扣款可全额退还多扣部分"
}
```

### questions

问题集合。键是你自定义的问题名，响应的 `answers` 用同样的名字返回答案；值是问题定义：

| 字段 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `type` | string | 是 | 题型：`choice`、`score`、`noul`、`box` |
| `instructions` | string / object / array | 否 | 问题说明，即希望模型判断什么 |
| `criteria` | object / array | 视题型 | 选项或评分标准，各题型写法见下表 |

| 题型 | `criteria` 写法 | 要求 |
| - | - | - |
| `choice` 单选 | 对象：`{选项名: 选项说明}` | **必填**，1 \~ 255 个选项；说明可为空，此时只按选项名理解 |
| `score` 打分 | 数组：按从低到高的顺序列出每个档位的说明 | **必填**，1 \~ 10 个档位，建议至少 2 档；第 1 个为 0 分，依次递增 |
| `noul` 是非 | 对象：`{"true": "什么算是", "false": "什么算否"}` | 可选；`instructions` 和 `criteria` 至少给一个，否则上游报错 |
| `box` 框选 | 不传 | 仅 `jev-1.14.0` 及指向它的别名支持；必须带图片和 `TypeSafe-Danger-Zone-Images: true` |

```json theme={null}
"questions": {
  "department": {
    "type": "choice",
    "instructions": "这张工单应该分给哪个部门？",
    "criteria": {
      "billing": "付款、扣费、退款",
      "technical": "功能故障、报错",
      "sales": "售前咨询、套餐升级"
    }
  },
  "anger": {
    "type": "score",
    "instructions": "用户的情绪有多激动？",
    "criteria": ["平静", "有些不满", "非常愤怒"]
  },
  "wants_refund": {
    "type": "noul",
    "instructions": "用户是否在要求退款？",
    "criteria": { "true": "明确要求退钱", "false": "没有提退款" }
  }
}
```

> [!NOTE]
>
> * 问题之间相互独立，每个问题都单独针对 `state` 作答，不会看到其他问题的答案。
> * 选项说明和档位说明写得越具体，判断越稳定；选项之间尽量不要重叠。

### assets

图片集合。键是你自定义的**占位符**（建议每张图用一个 UUID），值是图片定义。占位符出现在 `state`、问题的 `instructions` 或 `criteria` 里的任何字符串中时，会被替换成对应的图片。

| 字段 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `type` | string | 否 | 传入时固定为 `image`，示例中显式指定 |
| `format` | string | 用 `data_base64` 时必填 | 图片格式：`png`、`jpg`、`jpeg`，实际格式以图片内容为准 |
| `data_base64` | string | 二选一 | 图片的 Base64 编码，**不带** `data:image/...;base64,` 前缀 |
| `part` | string | 二选一 | multipart 请求中图片所在分段的名称，传了 `part` 时忽略 `data_base64` |

下面示例使用一张 **280 × 280** 的白底红色矩形 PNG，可用于后面的图片判断和框选示例。请勿替换为低于最小尺寸的占位图片。

```json theme={null}
"state": "photo",
"assets": {
  "photo": {
    "type": "image",
    "format": "png",
    "data_base64": "iVBORw0KGgoAAAANSUhEUgAAARgAAAEYCAIAAAAI7H7bAAAC/UlEQVR42u3TwQ0AMAgDsey/NN0BPlT4lAEqVKckjYsTSCBJIEkgSQJJAkkCSQJJEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSSJJAkkCSQJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIkkCSQJJAkkCSBJIEkgSSJJAkkCSQmi+NXRxIIBlIIBlIIBlIIIFkIIFkIIFkIIFkIIEEkoEEkoEEkoEEkoEEEkgGEkgGEkgGEkgGEkggGUggGUggGUggGUgggWQggWQggWQggQQSSCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIBhJIIBlIIBlIIBlIIBlIIIFkIIFkIIFkIIFkIIEEkoEEkoEEkoEEkoEEEkgGEkgGEkgGEkgggQQSSAYSSAYSSAYSSCAZSCAZSCAZSCAZSCCBZCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIBhJIIBlIIBlIIBlIIPlSIIEEkoEEkoEEkoEEEkgggQSSgQSSgQSSgQQSSAYSSAYSSAYSSAYSSCAZSCAZSCAZSCAZSCCBZCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIIIEEEkgGEkgGEkgGEkggGUggGUggGUggGUgggWQggWQggWQggWQggSR9HUgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSQJJAkkCSRJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIkkCSQJJAkkCSBJIEkgSSBJIkkCSQJJAkkJxAAkkCSQJJEkgSSNKyHikG6UERft5KAAAAAElFTkSuQmCC"
  }
}
```

> [!WARNING]
>
> 按官方规范，请求里带 `assets` 时必须同时带请求头 `TypeSafe-Danger-Zone-Images: true`。图片输入和框选题是官方标注的早期功能，请求格式、答案和限制可能随版本变化。

### 图片限制

图片需同时满足以下 [官方限制](https://docs.typesafe.ai/images#limits)，不符合尺寸要求时不会自动缩放，而是整次请求失败：

| 项目 | 限制 |
| - | - |
| 格式 | 静态 PNG 或 JPEG，不支持动画 PNG |
| 宽、高 | 每边均为 **280 \~ 1568 像素**，包含边界 |
| 总像素数 | 78,400 \~ 2,458,624 |
| 单张文件 | 不超过 16 MiB，Base64 按解码后的文件大小计算 |
| 请求体 | 不超过 32 MiB，包含 JSON、Base64 或 multipart 的开销 |
| 全部图片 / 引用展开后的请求 | 分别不超过 32 MiB；同一图片引用多次会重复计入展开大小 |

每个 asset 都必须在 `state`、`instructions` 或 `criteria` 中被引用。图片过小、格式无效、未被引用等问题通常返回 400；超出文件、尺寸或请求大小上限可能返回 413。

### multipart 上传图片

图片较大或较多时，可以用 `multipart/form-data` 上传原始图片，不用转 Base64：

* 第一段名为 `request`，内容是 JSON 请求体（`Content-Type: application/json`）。
* 之后每张图片单独一段，段名唯一、不能为空，并且必须被某个 asset 的 `part` 引用。

```bash theme={null}
curl --location 'https://api.gravitex.ai/v1/systemone' \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'TypeSafe-Danger-Zone-Images: true' \
  --form 'request={"model":"jev-latest","state":"photo","questions":{"damage":{"type":"noul","instructions":"车身是否有明显划痕？"}},"assets":{"photo":{"type":"image","part":"img1"}}};type=application/json' \
  --form 'img1=@./car.jpg;type=image/jpeg'
```

### 上下文长度

每个请求要同时满足两个上限：

| 上限 | 默认 | 开启长上下文后 |
| - | - | - |
| 单次请求（`state` + 全部问题） | 64k token | 262k token |
| 单个问题（`state` + 这一个问题） | 32k token | 262k token |

* 超出上限时上游返回 400，错误信息为 `max_tokens_exceeded`。
* 需要处理长合同、长对话记录时，在请求头带 `TypeSafe-Danger-Zone-Long-Context: true`。长上下文**单价不变**，但速度更慢、准确率略低，只在确实需要时打开。

## 调用示例

> [tab] 单选
>
> ```bash theme={null}
> curl --location 'https://api.gravitex.ai/v1/systemone' \
>   --header 'Authorization: Bearer sk-xxxxxxxxxx' \
>   --header 'Content-Type: application/json' \
>   --data '{
>     "model": "jev-latest",
>     "state": "Help! My payouts have been failing for 3 days.",
>     "questions": {
>       "department": {
>         "type": "choice",
>         "instructions": "Which team should handle this?",
>         "criteria": {
>           "billing": "Payments, invoicing, refunds",
>           "technical": "Bugs, outages, integrations",
>           "sales": "Pricing, upgrades, new accounts"
>         }
>       }
>     }
>   }'
> ```

> [tab] 多题一起问
>
> ```bash theme={null}
> curl --location 'https://api.gravitex.ai/v1/systemone' \
>   --header 'Authorization: Bearer sk-xxxxxxxxxx' \
>   --header 'Content-Type: application/json' \
>   --data '{
>     "model": "jev-latest",
>     "state": "我的订单被扣了两次钱，已经三天了还没有人处理，再不退款我就投诉！",
>     "questions": {
>       "department": {
>         "type": "choice",
>         "instructions": "这张工单应该分给哪个部门？",
>         "criteria": { "billing": "付款、扣费、退款", "technical": "功能故障、报错", "sales": "售前咨询、套餐升级" }
>       },
>       "anger": {
>         "type": "score",
>         "instructions": "用户的情绪有多激动？",
>         "criteria": ["平静", "有些不满", "非常愤怒"]
>       },
>       "wants_refund": { "type": "noul", "instructions": "用户是否在要求退款？" }
>     }
>   }'
> ```

> [tab] 结构化 state
>
> ```bash theme={null}
> curl --location 'https://api.gravitex.ai/v1/systemone' \
>   --header 'Authorization: Bearer sk-xxxxxxxxxx' \
>   --header 'Content-Type: application/json' \
>   --data '{
>     "model": "jev-1.14.0",
>     "state": {
>       "customer_message": "我的订单被扣了两次钱",
>       "orders": [{ "id": "A1024", "charged_times": 2 }],
>       "refund_policy": "重复扣款可全额退还多扣部分"
>     },
>     "questions": {
>       "refund_allowed": { "type": "noul", "instructions": "按退款规则，这笔订单是否应该退款？" }
>     }
>   }'
> ```

> [tab] 图片判断
>
> ```bash theme={null}
> curl --location 'https://api.gravitex.ai/v1/systemone' \
>   --header 'Authorization: Bearer sk-xxxxxxxxxx' \
>   --header 'Content-Type: application/json' \
>   --header 'TypeSafe-Danger-Zone-Images: true' \
>   --data '{
>     "model": "jev-latest",
>     "state": "photo",
>     "questions": {
>       "has_red": { "type": "noul", "instructions": "Does the image contain something red?" }
>     },
>     "assets": {
>       "photo": {
>         "type": "image",
>         "format": "png",
>         "data_base64": "iVBORw0KGgoAAAANSUhEUgAAARgAAAEYCAIAAAAI7H7bAAAC/UlEQVR42u3TwQ0AMAgDsey/NN0BPlT4lAEqVKckjYsTSCBJIEkgSQJJAkkCSQJJEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSSJJAkkCSQJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIkkCSQJJAkkCSBJIEkgSSJJAkkCSQmi+NXRxIIBlIIBlIIBlIIIFkIIFkIIFkIIFkIIEEkoEEkoEEkoEEkoEEEkgGEkgGEkgGEkgGEkggGUggGUggGUggGUgggWQggWQggWQggQQSSCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIBhJIIBlIIBlIIBlIIBlIIIFkIIFkIIFkIIFkIIEEkoEEkoEEkoEEkoEEEkgGEkgGEkgGEkgggQQSSAYSSAYSSAYSSCAZSCAZSCAZSCAZSCCBZCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIBhJIIBlIIBlIIBlIIPlSIIEEkoEEkoEEkoEEEkgggQSSgQSSgQSSgQQSSAYSSAYSSAYSSAYSSCAZSCAZSCAZSCAZSCCBZCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIIIEEEkgGEkgGEkgGEkggGUggGUggGUggGUgggWQggWQggWQggWQggSR9HUgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSQJJAkkCSRJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIkkCSQJJAkkCSBJIEkgSSBJIkkCSQJJAkkJxAAkkCSQJJEkgSSNKyHikG6UERft5KAAAAAElFTkSuQmCC"
>       }
>     }
>   }'
> ```

> [tab] 框选
>
> ```bash theme={null}
> curl --location 'https://api.gravitex.ai/v1/systemone' \
>   --header 'Authorization: Bearer sk-xxxxxxxxxx' \
>   --header 'Content-Type: application/json' \
>   --header 'TypeSafe-Danger-Zone-Images: true' \
>   --data '{
>     "model": "jev-1.14.0",
>     "state": "photo",
>     "questions": {
>       "red_rectangle": { "type": "box", "instructions": "Locate the red rectangle." },
>       "has_rectangle": { "type": "noul", "instructions": "Is there a red rectangle in the image?" }
>     },
>     "assets": {
>       "photo": {
>         "type": "image",
>         "format": "png",
>         "data_base64": "iVBORw0KGgoAAAANSUhEUgAAARgAAAEYCAIAAAAI7H7bAAAC/UlEQVR42u3TwQ0AMAgDsey/NN0BPlT4lAEqVKckjYsTSCBJIEkgSQJJAkkCSQJJEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSSJJAkkCSQJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIkkCSQJJAkkCSBJIEkgSSJJAkkCSQmi+NXRxIIBlIIBlIIBlIIIFkIIFkIIFkIIFkIIEEkoEEkoEEkoEEkoEEEkgGEkgGEkgGEkgGEkggGUggGUggGUggGUgggWQggWQggWQggQQSSCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIBhJIIBlIIBlIIBlIIBlIIIFkIIFkIIFkIIFkIIEEkoEEkoEEkoEEkoEEEkgGEkgGEkgGEkgggQQSSAYSSAYSSAYSSCAZSCAZSCAZSCAZSCCBZCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIBhJIIBlIIBlIIBlIIPlSIIEEkoEEkoEEkoEEEkgggQSSgQSSgQSSgQQSSAYSSAYSSAYSSAYSSCAZSCAZSCAZSCAZSCCBZCCBZCCBZCCBZCCBBJKBBJKBBJKBBJKBBBJIBhJIBhJIBhJIIIEEEkgGEkgGEkgGEkggGUggGUggGUggGUgggWQggWQggWQggWQggSR9HUgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkiSQJJAkkCSQJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJAkkCSQJJAkkSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSSJJAkkCSQJJAkgSSBJIEkgSQJJAkkCSRJIEkgSSBJIEkCSQJJAkkCSRJIEkgSSBJIkkCSQJJAkkCSBJIEkgSSBJIkkCSQJJAkkJxAAkkCSQJJEkgSSNKyHikG6UERft5KAAAAAElFTkSuQmCC"
>       }
>     }
>   }'
> ```
>
> 框选题没有「找不到」的答案，即使目标不在图里也会返回四条边。需要确认目标是否存在时，像上面一样在同一个请求里加一道是非题。

> [tab] 长上下文
>
> ```bash theme={null}
> curl --location 'https://api.gravitex.ai/v1/systemone' \
>   --header 'Authorization: Bearer sk-xxxxxxxxxx' \
>   --header 'Content-Type: application/json' \
>   --header 'TypeSafe-Danger-Zone-Long-Context: true' \
>   --data '{
>     "model": "jev-latest",
>     "state": "<一份很长的合同全文>",
>     "questions": {
>       "has_termination_clause": {
>         "type": "noul",
>         "instructions": "合同里是否有允许任一方提前终止协议的条款？"
>       }
>     }
>   }'
> ```

> [tab] Python
>
> ```python theme={null}
> import requests
>
> # 先安装依赖：pip install requests
> resp = requests.post(
>     "https://api.gravitex.ai/v1/systemone",
>     headers={"Authorization": "Bearer sk-xxxxxxxxxx"},
>     json={
>         "model": "jev-latest",
>         "state": "我的订单被扣了两次钱，再不退款我就投诉！",
>         "questions": {
>             "wants_refund": {"type": "noul", "instructions": "用户是否在要求退款？"},
>         },
>     },
>     timeout=60,
> )
> resp.raise_for_status()
> answer = resp.json()["answers"]["wants_refund"]
> if answer["noul"] >= 0.8:
>     print("转退款流程")
> ```

## 成功返回

```json theme={null}
{
  "model": "jev-1.14.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "confidence": 1,
      "probabilities": { "billing": 1, "technical": 0, "sales": 0 }
    },
    "anger": {
      "type": "score",
      "score": 1.87,
      "confidence": 0.8,
      "legend": { "0": "平静", "1": "有些不满", "2": "非常愤怒" },
      "probabilities": { "0": 0, "1": 0.13, "2": 0.87 }
    },
    "wants_refund": {
      "type": "noul",
      "noul": 0.97
    }
  },
  "usage": {
    "input_tokens": 443,
    "output_tokens": 71
  }
}
```

**框选题的答案**

```json theme={null}
{
  "type": "box",
  "box": { "top": 0.2, "bottom": 0.66, "left": 0.19, "right": 0.68 },
  "confidence": 0.9
}
```

### 返回字段

| 字段 | 类型 | 说明 |
| - | - | - |
| `model` | string | 实际作答的模型版本，用别名请求时返回的是版本号，如 `jev-1.14.0` |
| `answers` | object | 答案集合，键与请求里的问题名一一对应 |
| `answers.*.type` | string | 题型：`choice`、`score`、`noul`、`box` |
| `answers.*.choice` | string | 单选：概率最高的选项名 |
| `answers.*.score` | number | 打分：按各档位概率加权的期望分，可能落在两个整数档位之间，如 `1.87` |
| `answers.*.noul` | number | 是非：「是」的概率，0 \~ 1；接近 1 偏向是，接近 0 偏向否，接近 0.5 表示不确定 |
| `answers.*.box` | object | 框选：`top`、`bottom`、`left`、`right` 四条边，分别是占图片高度、宽度的比例，0 \~ 1，从左上角算起 |
| `answers.*.confidence` | number | 单选、打分、框选的置信度，0 \~ 1，越高越确定；框选可能为 `null` |
| `answers.*.probabilities` | object | 单选：每个选项的概率；打分：每个档位的概率，键为档位序号；合计约为 1 |
| `answers.*.legend` | object | 打分：档位序号到档位说明的对照，方便解读分值 |
| `usage.input_tokens` | integer | 输入 token 数，**计费依据** |
| `usage.output_tokens` | integer | 输出 token 数，当前**不计费** |

> [!NOTE]
>
> **怎么用置信度**：概率和置信度是校准过的，适合设阈值做自动决策。例如 `noul ≥ 0.8` 自动处理、`0.2 ~ 0.8` 转人工复核、`< 0.2` 直接放行。阈值建议用一批人工标注过的样本调出来。

## 计费说明

**计费公式**：单次费用 = `usage.input_tokens` / 1,000,000 × 输入单价

| 模型 | 输入单价（美元 / 百万 token） | 输出 |
| - | - | - |
| `jev-1.14.0` | 0.042 | 免费 |
| `jev-1.13.0` | 0.042 | 免费 |
| `jev-latest` | 0.042 | 免费 |
| `jev-preview` | 0.042 | 免费 |

* 以上为官方基础价，实际扣费再乘以令牌所在分组的倍率，以模型广场展示的价格为准。
* 输入 token 包含 `state`、全部问题说明、选项和档位说明；带图片时也包含图片对应的 token。
* 响应里的 `output_tokens` 只做展示，当前不计费。
* 开启长上下文不改变单价，只是允许更长的输入。

**示例**：上面「多题一起问」的请求返回 `input_tokens: 443`，费用为 443 / 1,000,000 × 0.042 ≈ **0.0000186 美元**，也就是每 1 万次这样的请求约 0.19 美元。

## 错误处理

请求失败时返回 JSON 错误对象。平台可能封装上游错误，`message` 有时包含具体原因，有时仅为 `openai_error`，不能仅凭该字段判断失败原因。以下为错误格式示例：

```json theme={null}
{
  "error": {
    "message": "max_tokens_exceeded",
    "type": "bad_response_status_code",
    "param": "",
    "code": "bad_response_status_code"
  }
}
```

> [!NOTE]
>
> 官方接口的参数校验失败可能返回 422，而网关可能返回 400 并使用 `error` 对象封装。应先检查 HTTP 状态码，再读取响应中的错误字段；不要假设所有网关都原样返回官方的 `detail` 结构或具体错误信息。

常见问题：

| 问题 | 处理建议 |
| - | - |
| API Key 无效 | 检查 `Authorization: Bearer ...` 是否正确 |
| 缺少 `model` | `model` 必填，请求体或 multipart 的 `request` 段里都要带 |
| 缺少 `state` / `questions` | 两者都必填，`questions` 至少 1 个 |
| 单选题报错 | `choice` 必须带 `criteria`，且为 1 \~ 255 个选项的对象 |
| 打分题报错 | `score` 必须带 `criteria`，且为 1 \~ 10 个档位的数组 |
| 是非题报错 | `noul` 的 `instructions` 和 `criteria` 至少给一个 |
| 未知题型 | `type` 只能是 `choice`、`score`、`noul`、`box` |
| 带图片报错 | 请求头加 `TypeSafe-Danger-Zone-Images: true`；宽高均需为 280 \~ 1568 像素；Base64 不带 `data:image/...;base64,` 前缀；使用静态 PNG / JPEG，详见 [图片限制](#图片限制) |
| 框选题报错 | 只有 `jev-1.14.0`（及当前指向它的 `jev-latest`、`jev-preview`）支持，且必须带图片和 Images 请求头 |
| `openai_error` | 网关未提供具体原因；检查图片尺寸、模型与题型兼容性、必填字段及上下文长度，必要时保留请求时间和请求 ID 联系平台排查 |
| `max_tokens_exceeded` | 超过上下文上限，精简 `state` 或加请求头 `TypeSafe-Danger-Zone-Long-Context: true` |
| 用 `/v1/chat/completions` 调用失败 | Jev 不是对话模型，请改用 `POST /v1/systemone` |

## 官方参考

* [System One API](https://docs.typesafe.ai/api/system-one)
* [模型、别名与上下文长度](https://docs.typesafe.ai/models)
* [图片上传与限制](https://docs.typesafe.ai/images)
* [Box 框选与置信度](https://docs.typesafe.ai/primitives/box)
* [请求规则与错误码](https://docs.typesafe.ai/api/errors)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.