GPT-6 Sol、Claude Opus 5.5 已上线GPT-6 Sol 价格仅为 5.6 Sol 的一半
博客
API 接入

Jev API 调用教程

读懂请求、响应与限流,完成一次 Jev API 调用。

11 分钟阅读OmniaKey
Jev APIAPI 文档JSONPythonNode.js

Jev API 用来对文本做有明确范围的判断。 请求由 state、model 和 questions 组成,返回的 answers 使用原来的问题 ID。它不是聊天补全接口,不需要从一段生成文本里再提取标签。

这篇教程解决接入问题。模型适合什么任务、有哪些限制和价格背景,请先看 Jev 模型介绍。

核验日期:2026 年 9 月 28 日。 请求与响应结构依据 TypeSafe 官方文档,网关路由结合 OmniaKey 实现核对。示例做了离线检查,没有新增付费性能实测。官方直连的价格和限额不自动等于网关账号的条件。

先选对接口和 API Key

调用方式POST 地址使用的凭据
OmniaKeyhttps://api.omniakey.com/v1/alpha/search有权调用 jev-latest 的 OmniaKey API Key
TypeSafe 官方直连https://api.typesafe.ai/v1/systemoneTypeSafe API Key

两种方式都使用 Authorization: Bearer ... 和原生 Jev 请求体。不要把 OmniaKey Key 发给 TypeSafe,也不要反过来使用。 网关地址不是 /v1/chat/completions,把 state 换成 messages 会改变接口合同。

创建权限受控的 Key,确认 当前 Jev 模型路由,并在本地环境中设置 OMNIAKEY_API_KEY。Key 不应放进浏览器代码、Git 或截图。通用步骤见 API 快速开始。

完整的 Jev JSON 请求示例

将下面内容保存为 jev-request.json。一次请求对同一条客服消息分别判断部门、情绪程度和紧急性。示例保留英文输入;TypeSafe 表示英文目前表现最好,中文工作流应使用自己的真实样本验证。

json
{
  "model": "jev-latest",
  "state": "My payouts have failed for three days. Please help me resolve this today.",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this message?",
      "criteria": {
        "billing": "Payments, invoices, or refunds",
        "technical": "Bugs, outages, or integrations",
        "sales": "Pricing, upgrades, or new accounts"
      }
    },
    "frustration": {
      "type": "score",
      "instructions": "How frustrated is the customer?",
      "criteria": ["Calm", "Frustrated", "Very angry"]
    },
    "is_urgent": {
      "type": "noul",
      "instructions": "Does the message express a time-sensitive need?"
    }
  }
}

department、frustration、is_urgent 是请求与响应之间的对应 ID。官方说明这些 ID 不参与推理,因此真正的判断要求要写在 instructions 里,不能只藏在键名里。state 也可以是包含文本的 JSON 对象或数组,例如带不同字段的工单记录。

bash
curl --fail-with-body https://api.omniakey.com/v1/alpha/search \
  -H "Authorization: Bearer $OMNIAKEY_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @jev-request.json

使用官方直连时,将地址换为 https://api.typesafe.ai/v1/systemone,凭据换为 $TYPESAFE_API_KEY。保留原生 JSON 结构,并核对该账号可用的模型名称。

Choice、Score、Noul 的返回值怎么读

问题类型请求中定义什么读取哪些字段含义
choice选项与描述的映射,最多 255 个选项choice、probabilities、confidence选中的标签和各选项的概率分布
score2–10 级有序评分标准score、legend、probabilities、confidence按概率加权的等级,可以是小数
noul是非问题,可选填 true / false 标准noul0 到 1 之间“是”的概率,不是布尔值

响应还包含 model 和 usage.input_tokens / usage.output_tokens。当前 jev-latest 指向 jev-1.13.0,别名以后可能变化。做效果评估时应记录实际返回的版本。

如果评分标准只有三级,1.05 表示略高于第 1 级,并不是百分制的 1.05 分,要结合 legend 阅读。Noul 返回 0.8 也不意味着可以直接执行退款等不可逆动作。阈值应在带标签的业务样本上确定;confidence 来自概率分布,不保证判断一定正确。

下面是完整响应的示意数据,不是本次实测的 API 返回。答案数值和 token 数量仅用于解释结构,实际结果会有所不同。

json
{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": {
        "billing": 0.88,
        "technical": 0.12,
        "sales": 0.0
      },
      "confidence": 0.81
    },
    "frustration": {
      "type": "score",
      "score": 1.05,
      "legend": {
        "0": "Calm",
        "1": "Frustrated",
        "2": "Very angry"
      },
      "probabilities": {
        "0": 0.0,
        "1": 0.95,
        "2": 0.05
      },
      "confidence": 0.92
    },
    "is_urgent": {
      "type": "noul",
      "noul": 0.8
    }
  },
  "usage": {
    "input_tokens": 320,
    "output_tokens": 72
  }
}

Python 与 Node.js 调用

下面都复用 jev-request.json,每次只发送一个请求,打印原生答案,不假设存在 OpenAI 风格的 choices。生产客户端还需要后文的有限重试策略。

python
import json
import os
import urllib.error
import urllib.request
from pathlib import Path

request = urllib.request.Request(
    "https://api.omniakey.com/v1/alpha/search",
    data=Path("jev-request.json").read_bytes(),
    headers={
        "Authorization": f"Bearer {os.environ['OMNIAKEY_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise SystemExit(f"Jev request failed: HTTP {error.code}") from None

print(result["model"])
print(json.dumps(result["answers"], indent=2))
javascript
import { readFile } from 'node:fs/promises';

const key = process.env.OMNIAKEY_API_KEY;
if (!key) throw new Error('Set OMNIAKEY_API_KEY first');

const response = await fetch('https://api.omniakey.com/v1/alpha/search', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${key}`,
    'Content-Type': 'application/json',
  },
  body: await readFile('jev-request.json', 'utf8'),
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) throw new Error(`Jev request failed: HTTP ${response.status}`);

const result = await response.json();
console.log(result.model);
console.log(result.answers);

Python 示例使用 Python 3 标准库;Node.js 需要支持内置 fetch 和 AbortSignal.timeout。这是 HTTP 接入示例,不代表 OpenAI SDK 原生支持 Jev Schema。TypeSafe 自有 SDK 的行为以官方 API 文档为准。

上下文长度、限流与费用

当前官方限制需要同时满足:整个请求最多 64K tokens,state 加最长的单个问题最多 32K tokens。先删掉无关上下文,再把确实共享同一状态的问题放到一起。

TypeSafe 当前列出 250,000 tokens/秒、1,200 请求/分钟,并说明早期开放期间可能动态调整。这是账号吞吐限制,不是单次响应速度,也不是对 OmniaKey 账号的承诺。网关可能另有账号或请求限制。

官方直连价格为 每百万输入 tokens $0.042,输出 tokens 免费。响应仍会返回输出用量。这不等于整个 API 免费,也不代表网关使用相同计费单位或价格。OmniaKey 费用以当前模型报价和调用记录为准,概览见 Jev 价格与限制说明。

OmniaKey 当前的 Jev 模型按请求次数计费。估算网关费用时,请核对当前模型报价和控制台用量记录。

鉴权失败、参数错误和重试

TypeSafe 直连接口状态先检查什么处理方式
401Key 是否属于当前服务,Bearer 头是否正确修正凭据,不重复发送相同无效 Key
422必填字段、问题类型与 criteria 结构根据错误信息修正对应字段
429请求数或 token 限额有 Retry-After 时遵守该值;使用有上限的指数退避并加入抖动
529服务暂时过载退避重试,同时限制次数和总等待时间

这些含义来自官方直连文档。网关可能有自己的鉴权、参数校验和上游错误格式。路由不可用时还要检查路径与准确的模型 ID。对外分享诊断信息时,不包含 Key 或私有请求正文。

把模型调用与后续业务动作分开:重试分类请求不能导致邮件重复发送或重复退款。连续失败后,应明确返回失败或进入人工复核,而不是默默使用一个看似确定的默认答案。

常见问题

这是 Jev 官方 API 文档吗?

这是 OmniaKey 的接入教程。TypeSafe API 参考定义官方请求结构,型号页定义官方价格与限额。上方表格已区分两条调用路径。

可以上传图片,或者让 Jev 写文章吗?

Jev 1.13 只接受文本并返回上述类型化决策。非文本素材需要先转成文本或结构化字段;生成解释、图片或视频需要其他模型或应用步骤。

应该使用别名还是固定版本?

探索阶段可以使用别名。上线带阈值的工作流时,应评估实际支持的固定版本并记录响应中的 model,版本变化后重新验证阈值。网关和官方可用的模型名称可能不同。

资料来源