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

# TypeSafe / Jev

> 使用 TypeSafe 官方客户端调用 Jev 决策模型，了解模型发现、输入计费与失败处理。

Jev 根据你提供的材料和问题返回结构化判断，适合分类、评分、真假判断和图片目标定位。Kapon 通过 TypeSafe 原生协议提供同步调用，一次请求可以包含多个问题。

> [!NOTE]
>
> 这是预览功能，尚未正式发布。请使用已开通 Jev 的环境域名和该环境签发的模型调用令牌；实际可用模型以当前令牌查询结果为准。

## 接入地址与认证

将环境域名保存为 `ONEHUB_BASE_URL`，不要在末尾添加 `/v1`。`ONEHUB_API_KEY` 使用平台签发的模型调用令牌，客户应用不需要填写 TypeSafe 上游密钥。

```bash theme={null}
export ONEHUB_BASE_URL="https://your-onehub.example"
export ONEHUB_API_KEY="YOUR_ONEHUB_API_KEY"
```

| 用途 | 地址 |
| - | - |
| 官方客户端基础地址 | `${ONEHUB_BASE_URL}/typesafe` |
| 提交问题 | `POST /typesafe/v1/systemone` |
| 官方格式模型列表 | `GET /typesafe/v1/models` |

认证请求头为 `Authorization: Bearer YOUR_ONEHUB_API_KEY`。客户端会在基础地址后补上 `/v1/systemone` 或 `/v1/models`，因此客户端基础地址只需以 `/typesafe` 结尾。

## 查询可用模型

```bash theme={null}
curl "$ONEHUB_BASE_URL/typesafe/v1/models" \
  -H "Authorization: Bearer $ONEHUB_API_KEY"
```

响应格式示例：

```json theme={null}
{
  "models": [
    {"name": "jev-latest", "description": "", "release_date": ""},
    {"name": "jev-preview", "description": "", "release_date": ""}
  ]
}
```

列表只展示当前账号和令牌获准使用、且有可用供给及计费配置的模型。模型说明和发布日期有来源时返回原值，缺失时为空字符串；原有 `/v1/models` 继续返回 OpenAI 格式的 `data` 数组。

| 模型名称 | 使用说明 |
| - | - |
| `jev-latest` | 独立授权和计价的模型别名；仅在模型列表返回时使用。 |
| `jev-preview` | 另一模型别名；是否可用同样取决于当前令牌的列表。 |

响应中的 `model` 可能是具体版本，例如 `jev-1.13.0`。这表示本次返回的版本，不代表该版本名已获准作为下一次请求的模型名称；两个别名也可能返回同一版本。

## 支持的调用方式

* `choice`：从给定选项中选择，返回选项、概率和置信度。
* `score`：按给定等级评分，返回分值、等级说明、概率和置信度。
* `noul`：判断条件是否成立，返回 0 到 1 的判断值。
* `box`：定位图片中的目标，返回 0 到 1 的四边坐标和置信度；需要具备该能力的 Jev 1.14 供给。

支持文本材料及其 JSON 对象、数组形式。原文本调用方式见 [System One 调用示例](https://docs.kapon.cloud/typesafe/systemone.md)。图片支持 JSON `assets` 中的 PNG/JPEG Base64，属于 Jev 1.14 的实验能力，需要 `TypeSafe-Danger-Zone-Images: true`；具体请求格式与渠道开关优先规则见 [JSON 图片与 Box 定位](https://docs.kapon.cloud/typesafe/systemone.md#json-图片与-box-定位)。

当前不提供 Jev Router、聊天转换、流式响应、音视频输入、multipart、图片 URL 下载或新版 SDK 文件上传适配。

## 计费

默认基准为每百万输入 token **\$0.042**，输出免费。token 是模型计量输入用量的单位，实际收费使用上游最终返回的 `usage.input_tokens`，而不是本地估算字数。

同一次请求的多个问题按这次请求的最终输入用量计费，不再乘问题数。`output_tokens` 可以非零，默认仍按零输出单价计算；你账号的客户覆盖价优先于默认基准，请以控制台当前价格和消费记录为准。

平台按请求将费用向上取整为整数额度点。按 1 美元等于 500,000 点、默认单价且无额外费用计算：

| 最终输入 token | 最终输出 token | 实际扣费点数 | 对应美元 |
| -: | -: | -: | -: |
| 1,000 | 70 | 21 | \$0.000042 |
| 404 | 70 | 9 | \$0.000018 |
| 100 | 0 | 3 | \$0.000006 |
| 明确报告为 0 | 70 | 0 | \$0 |

因为账本使用整数点，所以取整后的客户金额可能高于按单价计算的理论金额。计算方式见[额度计费原理](https://docs.kapon.cloud/guide/quota-billing.md)，对账时同时核对模型名、实际输入输出、单价和扣费点数。

### 失败时是否收费

* 上游明确拒绝且没有最终用量：释放预扣，不产生最终消费。
* 上游已给出有效最终用量：按该用量结算一次，即使客户端断开或未完整收到答案。
* 请求发送后结果未知，或输入用量缺失、非法：释放预扣，不用本地估算形成最终账单。该请求仍按失败处理。

遇到超时或断开时，先用[请求关联号](https://docs.kapon.cloud/guide/request-id.md)查询消费记录再决定是否重新提交。客户端重新提交属于新请求，可能产生新费用；示例关闭了客户端自动重试。

## 常见问题

| 现象 | 处理方法 |
| - | - |
| 模型列表为空或请求被拒绝 | 核对环境域名、令牌模型权限、账号授权和模型是否开通。 |
| 提示余额不足或价格未配置 | 先处理余额或联系管理员补齐价格，再提交请求。 |
| 参数校验失败 | 核对 `model`、`state` 和 `questions`，以及问题类型和选项数量。 |
| 返回 429 或 529 | 读取 `Retry-After` 等待提示；避免立即反复提交。 |

错误状态和原因可通过官方客户端异常读取。上游错误可能使用 TypeSafe 原生字段，也可能是兼容服务的错误包装；保留状态码和平台请求关联号，便于排查。


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