# Jev API（TokenRa）

模型 ID：`jev-latest`
获取 API Key：https://tokenra.io/sign-up?utm_source=llms-agent&utm_medium=model-llms
更新日期：2026-10-30

> Jev 是 TypeSafe AI 的决策模型，不生成文本：你提交一段待判断的内容（state）和若干命名问题，每个答案都以类型化结果返回，并附带概率和置信度。

- 厂商：TypeSafe AI
- 类型：决策模型
- 输入：文本或 JSON
- 输出：类型化答案
- 延迟：1 秒以内

## 价格

以下为本文件最后更新时 TokenRa 控制台的价格，单位美元，默认分组。请以实时价格为准：https://tokenra.io/pricing（JSON：https://tokenra.io/api/pricing）。

- `jev-latest`：$0.042 / 100 万 token，输入和输出同价

## 能力与接口

只有一个同步接口。Jev 不使用对话格式，OpenAI 和 Anthropic 的 SDK 都不适用，请直接发送 HTTPS 请求；在 `/v1/chat/completions` 上调用 `jev-latest` 会报错。

- `POST https://tokenra.io/v1/decisions`：提交 `state` 和命名的 `questions`，每个问题返回一个类型化答案。鉴权：`Authorization: Bearer`。

## 调用示例

先把环境变量 `TOKENRA_API_KEY` 设为你的 API Key。文档页提供同一示例的 Python、JavaScript 和 Java 版本。

```bash
curl https://tokenra.io/v1/decisions \
  -H "Authorization: Bearer $TOKENRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "救命！我的提现已经连续 3 天失败了。",
    "questions": {
      "is_urgent": {
        "type": "noul",
        "instructions": "这条消息是否表达了紧急诉求？",
        "criteria": {
          "true": "明确要求尽快处理",
          "false": "没有表达紧急程度"
        }
      },
      "department": {
        "type": "choice",
        "instructions": "应该由哪个团队处理？",
        "criteria": {
          "billing": "支付、发票、退款",
          "technical": "故障、宕机、集成问题",
          "sales": "价格、升级、新开户"
        }
      },
      "frustration": {
        "type": "score",
        "instructions": "客户有多不满？",
        "criteria": [
          "平静",
          "不满",
          "非常愤怒"
        ]
      }
    }
  }'
```

## 问题类型

每个问题由你自定义名称，包含 `type`、`instructions`，并按类型提供 `criteria`。三种类型均已于 2026-10-23 实测。

| type | criteria | 答案字段 |
| --- | --- | --- |
| `noul` | 可选。只能包含 `"true"` 和 `"false"` 两个键，分别说明何种情况成立。 | `noul`：答案为 true 的概率（0–1）。 |
| `choice` | 必填。选项键到选项说明的对象，至少一个选项。 | `choice`（最可能的选项键）、各选项的 `probabilities`、`confidence`。 |
| `score` | 必填。至少两个等级说明组成的数组，从低到高排列。 | `score`（0 到等级数−1，可以是小数）、`legend`、各等级的 `probabilities`、`confidence`。 |

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | `jev-latest`。响应中的 `model` 是实际回答的版本，例如 `typesafe/jev-1.14-20261014` 或 `jev-1.14.0`。 |
| `state` | string / object / array | 是 | 待判断的内容，所有问题共用：可以是文本，也可以是工单、记录等 JSON。已实测中文文本。 |
| `questions` | object | 是 | 问题名称到问题对象的映射，至少一个；答案以相同的名称返回。 |
| `questions.*.type` | string | 是 | `noul`、`choice` 或 `score`。 |
| `questions.*.instructions` | string / object / array | 是 | 问题本身。 |
| `questions.*.criteria` | object / array | 否 | 取决于问题类型，见上表；`choice` 和 `score` 必填。 |
| `stream` | boolean | 否 | 不支持，请不要传；传 `true` 会报错。 |

## 响应格式

**示例请求的实际响应（2026-10-24）**

```json
{
  "model": "typesafe/jev-1.14-20261014",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": {
        "billing": 0.92,
        "technical": 0.08,
        "sales": 0
      },
      "confidence": 0.88
    },
    "frustration": {
      "type": "score",
      "score": 1.66,
      "legend": {
        "0": "平静",
        "1": "不满",
        "2": "非常愤怒"
      },
      "probabilities": {
        "0": 0,
        "1": 0.34,
        "2": 0.66
      },
      "confidence": 0.49
    },
    "is_urgent": {"type": "noul", "noul": 0.87}
  },
  "usage": {"input_tokens": 461, "output_tokens": 73},
  "id": "gen-dec-1792772719-p9IzUxjzfk4qHGN0DyAd",
  "provider": "TypeSafe"
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `model` | string | 实际回答的 Jev 版本。 |
| `answers.<name>.type` | string | 问题类型。 |
| `answers.<name>.noul` | number | 仅 noul：答案为 true 的概率。 |
| `answers.<name>.choice` | string | 仅 choice：最可能的选项键。 |
| `answers.<name>.score` | number | 仅 score：期望等级，0 到等级数−1。 |
| `answers.<name>.probabilities` | object | choice 和 score：各选项或等级的概率，合计为 1。 |
| `answers.<name>.legend` | object | 仅 score：等级序号到等级说明的对照。 |
| `answers.<name>.confidence` | number | choice 和 score：0–1 的置信度，可据此把不确定的情况转人工。 |
| `usage` | object | 计费用的 `input_tokens` 和 `output_tokens`。 |
| `id / provider` | string | 请求 ID 和实际提供方，上游返回时才有。 |

答案以问题名称为键，不要依赖其顺序；实测返回顺序按名称排序，而不是请求中的顺序。

测试期间上游返回过两种格式：一种的 `model` 形如 `typesafe/jev-1.14-20261014`，并附带 `id` 和 `provider`；另一种的 `model` 形如 `jev-1.14.0`，没有这两个字段。两者的 `answers` 和 `usage` 完全相同，读取时只取你需要的字段即可。

## 错误与限制

### 请求校验错误

请求不合法时返回 HTTP `400`，`error.code` 为 `invalid_request`，message 为下表之一。这类错误重试无效，请修正请求。

| message | 原因 |
| --- | --- |
| `questions must not be empty` | 缺少 `questions` 或为空。 |
| `state must be a string, object or array` | 缺少 `state`，例如误发了对话格式的 `messages`。 |
| `unsupported question type; expected noul, choice or score` | `type` 不是三种之一。 |
| `choice criteria must be a nonempty object of choices` | choice 问题没有选项。 |
| `score criteria must contain at least two string levels` | score 问题少于两个等级。 |
| `noul criteria must contain only true and false string descriptions` | noul 的 criteria 中含有其他键。 |
| `decisions do not support streaming` | 传了 `stream: true`。 |

### 常见错误

| HTTP | error.code | 含义 | 处理建议 |
| --- | --- | --- | --- |
| `401` | — | API Key 缺失、错误或已删除，message 为 `Invalid token`。 | 检查 `Authorization: Bearer` 请求头，并在控制台核对 Key。 |
| `400` | — | 请求体不是合法 JSON。 | 修正 JSON，并带上 `Content-Type: application/json`。 |
| `403` | `insufficient_user_quota` | 账户余额或套餐额度不足。 | 在控制台充值后重试。 |
| `503` | `model_not_found` | 模型 ID 不存在，或你的分组下没有可用渠道。 | 在模型列表或 `GET /v1/models` 中核对模型 ID。 |
| `429` | — | 请求过于频繁。 | 指数退避后重试。 |
| `5xx` | — | 上游服务商出错或超时。 | 稍后重试几次；持续出错时保留 request id 联系支持。 |

### 使用限制与说明

- 实测单次请求耗时 0.35–1 秒。
- 计费：输入和输出 token 同价，均为每 100 万 token $0.042（2026-10-24 核对）。实测一次 358 个输入 token、60 个输出 token 的请求扣了 9 个额度，即 $0.000018。问题定义计入输入 token。价格会调整，实时价格见模型广场。
- 一句话的 state 加示例中的三个问题，实测消耗 461 个输入 token 和 73 个输出 token，问题定义也计入输入。

## 更多链接

- [Jev API 文档页](https://tokenra.io/zh/docs/jev-latest.html)：参数表和 cURL、Python、JavaScript、Java 代码示例
- [Jev 模型介绍与价格页](https://tokenra.io/zh/models/jev-api.html)
- [公共信息](https://tokenra.io/zh/docs/common.html)：Base URL、鉴权、错误码与重试
- [快速开始](https://tokenra.io/zh/docs/quickstart.html)：创建 Key 并发出第一个请求
- [全部模型](https://tokenra.io/zh/docs/models.html)：所有模型 ID
- [本指南的英文版](https://tokenra.io/docs/jev-latest/llms.txt)
- [面向 AI 代理的站点索引](https://tokenra.io/llms.txt)

---

本文档的规范地址：https://tokenra.io/zh/docs/jev-latest/llms.txt