Jev API Docs

接口

向本站的 POST /api/v1/decisions 发送请求。没有 chat-completions 路径，也没有流式响应。GET /api/v1/models 列出模型 id。TypeSafe 兼容的 POST /v1/systemone 见下文。

POST https://jev-api.org/api/v1/decisions
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

鉴权

把控制台密钥放在 Authorization: Bearer。缺失或被拒绝的密钥返回 401。试用台在你运行请求时，会为已登录账号创建密钥。

快速开始

把 JEV_API_KEY 设为控制台里的密钥，然后发送下面的请求。

curl https://jev-api.org/api/v1/decisions \
  -H "Authorization: Bearer $JEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "jev-1.13",
  "state": "Thanks for the refund. Still annoyed it took three emails.",
  "questions": {
    "sentiment": {
      "type": "choice",
      "instructions": "What is the overall sentiment of this message?",
      "criteria": {
        "positive": "Satisfied or thankful overall.",
        "mixed": "Both satisfied and unhappy.",
        "negative": "Unhappy overall."
      }
    },
    "needs_follow_up": {
      "type": "noul",
      "instructions": "Should a person reply to this message?"
    }
  }
}'

在 AI 编程工具中使用

复制一份包含完整请求约定的提示词，连同你的任务一起粘贴到 Cursor、Claude Code 或 ChatGPT。同样的参考内容也在 /llms.txt。

请求体

model 为 jev-1.13 或 jev-latest。state 是字符串、JSON 对象或文本数组，最多 60,000 字符。questions 是 1 到 6 个 snake_case id 的映射。id 只是答案返回时的标签，不是问题本身。真正的问题写在 instructions，为 1 到 2,000 字符的文本。

{
  "model": "jev-1.13",
  "state": "Thanks for the refund. Still annoyed it took three emails.",
  "questions": {
    "sentiment": {
      "type": "choice",
      "instructions": "What is the overall sentiment of this message?",
      "criteria": {
        "positive": "Satisfied or thankful overall.",
        "mixed": "Both satisfied and unhappy.",
        "negative": "Unhappy overall."
      }
    },
    "needs_follow_up": {
      "type": "noul",
      "instructions": "Should a person reply to this message?"
    }
  }
}

问题类型

Noul

type 为 noul 时只需要 instructions。答案字段 noul 是陈述为真的概率，从 0 到 1。没有单独的 confidence 字段。如果你在 noul 问题上发送 criteria，本接口会忽略它。

Choice

type 为 choice 时需要 instructions 和 criteria：2 到 8 个 snake_case 选项 id，各映射到最多 300 字符的说明。答案包含 choice、每个选项的 probabilities，以及 confidence。

Score

type 为 score 时需要 instructions，以及从低到高排列的 2 到 10 条档位说明。答案包含 score、你的档位 legend、probabilities 和 confidence。

响应

成功的响应体包含 model、以你的问题 id 为键的 answers、含 input_tokens 和 output_tokens 的 usage，以及 credits_used。即使发送 jev-latest，model 也报告 jev-1.13。下面是快速开始请求的示例响应，已省略 usage。

{
  "model": "jev-1.13",
  "answers": {
    "sentiment": {
      "type": "choice",
      "choice": "mixed",
      "probabilities": { "mixed": 0.79, "negative": 0.2, "positive": 0.01 },
      "confidence": 0.61
    },
    "needs_follow_up": { "type": "noul", "noul": 0.83 }
  },
  "credits_used": 1
}

读懂概率和 confidence

Noul 是 instructions 中陈述为真的概率。Choice 和 Score 返回每个选项或档位的概率，外加 confidence。

第二名就是转人工的信号。当 confidence 低，或两个选项接近时，把这种情况交给人，或再问一个更具体的问题。看过这些接近的结果之前，不要调低截止值。

限制

与 TypeSafe API 的差异

TypeSafe AI 在 POST https://api.typesafe.ai/v1/systemone 用 TypeSafe 密钥服务 Jev，并按输入 token 计费。本站的 POST /v1/systemone 原样接受同样的请求体；更简单的 POST /api/v1/decisions 有以下差异：

• 路径和密钥：jev-api.org 上的 POST /api/v1/decisions，密钥来自本站控制台。TypeSafe 密钥在这里无效，本站密钥也不能用在 TypeSafe 上。
• 模型 id：/api/v1/decisions 发送 jev-1.13 或 jev-latest，版本化 id（如 jev-1.13.0）会返回 422。/v1/systemone 接受 jev-latest、jev-preview、jev-1.13、jev-1.13.0 和 typesafe/jev-1.13。
• 限制：/api/v1/decisions 每次调用 1 到 6 个问题、2 到 8 个 Choice 选项。/v1/systemone 接受完整的 TypeSafe 范围——最多 256 个问题、255 个 Choice 选项。
• 字段：/api/v1/decisions 的 instructions 必须是文本，且每个 Choice 选项需要描述。/v1/systemone 也接受对象或数组形式的 instructions 和 null 选项描述。
• 计费：每次成功调用 1 积分，无论 token 数。

TypeSafe SDK 兼容接口

本站的 POST /v1/systemone 原样接受 TypeSafe 请求体——model、state 和 questions——并返回 TypeSafe 响应结构：model、answers、usage。把 TypeSafe 兼容客户端的 base URL 指向 https://jev-api.org，或直接调用 https://jev-api.org/v1/systemone。GET /v1/models 无需密钥即可列出所提供的模型。

POST https://jev-api.org/v1/systemone
GET  https://jev-api.org/v1/models

接受的模型 id：jev-latest、jev-preview、jev-1.13、jev-1.13.0、typesafe/jev-1.13。此路径接受更宽的 TypeSafe 范围——1 到 256 个问题、2 到 255 个 Choice 选项、2 到 10 个 Score 档位、对象或数组形式的 instructions——以及每请求 64k token、状态加最长问题 32k token 的限制。计费相同：每次成功调用 1 积分。

Python

from typesafe_sdk import Noul, TypeSafeClient

with TypeSafeClient(api_key="YOUR_JEV_API_KEY", base_url="https://jev-api.org") as client:
    response = client.system_one(
        state="The invoice total does not match the quote.",
        questions={"is_billing": Noul(instructions="Is this about billing?")},
    )

print(response.answers["is_billing"])

JavaScript

const res = await fetch('https://jev-api.org/v1/systemone', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.JEV_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'jev-latest',
    state: 'The invoice total does not match the quote.',
    questions: { is_billing: { type: 'noul', instructions: 'Is this about billing?' } },
  }),
})
const { answers } = await res.json()

Jev Python 指南·Jev 模型

错误

• 401 — 缺少或被拒绝的 API 密钥。
• 402 — 密钥有效，但余额不够这次调用。上游失败不会扣积分。
• 422 — 请求体校验失败。消息会指出字段。
• 429 — 决策服务被限流。稍后再试。
• 502 — 决策服务没有返回答案。不扣积分。