TypeSafe / Jev - Kapon 用户文档

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

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

接入地址与认证

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

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 结尾。

查询可用模型

curl "$ONEHUB_BASE_URL/typesafe/v1/models" \
  -H "Authorization: Bearer $ONEHUB_API_KEY"

响应格式示例：

{
  "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 调用示例。图片支持 JSON assets 中的 PNG/JPEG Base64，属于 Jev 1.14 的实验能力，需要 TypeSafe-Danger-Zone-Images: true；具体请求格式与渠道开关优先规则见 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

因为账本使用整数点，所以取整后的客户金额可能高于按单价计算的理论金额。计算方式见额度计费原理，对账时同时核对模型名、实际输入输出、单价和扣费点数。

失败时是否收费

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

遇到超时或断开时，先用请求关联号查询消费记录再决定是否重新提交。客户端重新提交属于新请求，可能产生新费用；示例关闭了客户端自动重试。

常见问题

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

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