Jev の REST API の使い方とエラーコード

Jev の判定 API は POST https://api.typesafe.ai/v1/systemone の1本です。state（材料）、model、questions（質問のマップ）を JSON で送ると、質問と同じキーで答えが返ります。SDK を使わなくても、curl や fetch だけで呼べます。

最小の呼び出し

API キーは環境変数に入れます。コードやコマンド履歴に直接書かないでください。

curl https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "Help! My payouts have been failing for 3 days.",
    "model": "jev-latest",
    "questions": {
      "is_urgent": { "type": "noul", "instructions": "Does this convey urgency?" }
    }
  }'

{
  "model": "jev-1.13.0",
  "answers": { "is_urgent": { "type": "noul", "noul": 0.95 } },
  "usage": { "input_tokens": 283, "output_tokens": 23 }
}

（2026-09-21 に実際に返ってきた値です。usage の数字は公式ドキュメントの例と少し違いました。）

リクエスト

質問の書き方は 3つの質問タイプの書き方 にまとめました。

レスポンス

Node.js（fetch）での例

3種類の質問を一度に送る例です。手元で実行し、約 0.7 秒で返りました（1回の計測）。

const res = await fetch('https://api.typesafe.ai/v1/systemone', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TYPESAFE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    state: { message: '助けてください！3日前から入金がずっと失敗しています。', plan: 'business' },
    model: 'jev-latest',
    questions: {
      is_urgent: { type: 'noul', instructions: 'Does `message` convey urgency?' },
      department: {
        type: 'choice',
        instructions: 'Which team should handle `message`?',
        criteria: {
          billing: 'Payments, invoicing, refunds',
          technical: 'Bugs, outages, integrations',
          sales: 'Pricing, upgrades, new accounts',
        },
      },
      frustration: {
        type: 'score',
        instructions: 'How frustrated is the customer?',
        criteria: ['Calm', 'Frustrated', 'Very angry'],
      },
    },
  }),
});

if (!res.ok) throw new Error(`Jev API ${res.status}: ${await res.text()}`);
const { model, answers } = await res.json();

if (answers.is_urgent.noul > 0.8 && answers.department.confidence > 0.7) {
  console.log(`${answers.department.choice} の優先キューへ（${model}）`);
}

エラー

公式の表にあるのは次の4つです。

実際に返ってきたエラーの形（2026-09-21 に確認）

401 — 誤ったキーで呼んだ場合:

{ "detail": { "error_type": "authentication_error",
              "message": "Cannot authenticate with the server. Please check your API key and try again." } }

422 — Choice に criteria を付け忘れた場合。loc が問題の場所を指します。

{ "detail": [ { "type": "missing",
                "loc": ["body", "questions", "q", "choice", "criteria"],
                "msg": "Field required" } ] }

400 — 存在しないモデル名を指定した場合。公式のエラー表には無いステータスですが、実際にはこう返りました。

{ "detail": { "error_type": "api_usage_error", "message": "Unknown model: jev-does-not-exist" } }

detail は、401 と 400 ではオブジェクト、422 では配列です。エラー処理で detail.message を決め打ちで読むと 422 で壊れるので、形を見てから読みます。

通ってしまう入力に注意

公式は「Score の段階は少なくとも2つ」としていますが、段階が1つだけの Score を送っても 422 にはならず、score: 0、confidence: 1 が 200 で返りました。 配列を組み立てる処理の不具合で段階が1つになっても、API は止めてくれません。送る前に自分のコードで確かめてください。

再試行の書き方

再試行するのは 429 と 529（と、ネットワークの一時的な失敗）だけです。400 / 401 / 422 は何度送っても同じなので、すぐに失敗させます。

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
// 0.5s, 1s, 2s, 4s … に揺らぎを足す
const backoff = (attempt) => 500 * 2 ** attempt + Math.random() * 250;

// Retry-After は「秒数」か「HTTP の日付」のどちらかで返る
function retryAfterMs(value) {
  if (!value) return null;
  const seconds = Number(value);
  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
  const date = Date.parse(value);
  return Number.isNaN(date) ? null : Math.max(0, date - Date.now());
}

async function askJev(body, { retries = 4 } = {}) {
  for (let attempt = 0; ; attempt++) {
    let res;
    try {
      res = await fetch('https://api.typesafe.ai/v1/systemone', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${process.env.TYPESAFE_API_KEY}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(body),
      });
    } catch (err) {
      // 接続できない、途中で切れた、などの一時的な失敗
      if (attempt >= retries) throw err;
      await sleep(backoff(attempt));
      continue;
    }
    if (res.ok) return res.json();

    const retryable = res.status === 429 || res.status === 529;
    if (!retryable || attempt >= retries) {
      throw new Error(`Jev API ${res.status}: ${await res.text()}`);
    }
    await sleep(retryAfterMs(res.headers.get('retry-after')) ?? backoff(attempt));
  }
}

通信の失敗で再試行すると、1回目のリクエストが実はサーバーに届いていた場合、同じ判定を2回行うことになります。Jev の判定は何かを書き換える操作ではないので結果に害はありませんが、入力トークンは2回ぶん数えられる可能性があります。

公式 SDK（Python の typesafe-sdk、JS の @typesafe-ai/sdk）は、この再試行を既定で行い、retry-after ヘッダがあれば従う、と書かれています。自前で書く理由が無ければ SDK を使うほうが簡単です。

このコードで確かめたこと（2026-09-21）:

• 実際の API に対して: 正常に答えが返ること、401 では再試行せずすぐに例外になること
• fetch を差し替えた模擬で: 「通信の失敗 → 429（Retry-After が秒数）→ 529（Retry-After が日付）→ 200」の順に進んで答えが返ること、再試行の上限で諦めること、通信の失敗が続いたら元の例外を投げること、Retry-After が秒数・日付・過去の日付・壊れた値のそれぞれで期待どおりの待ち時間になること

実際の API に 429 や 529 を起こさせることはしていません。 本物の Retry-After がどちらの形式で返るかは未確認です。

使えるモデルの一覧

curl https://api.typesafe.ai/v1/models -H "Authorization: Bearer $TYPESAFE_API_KEY"

現在はエイリアス（jev-latest、jev-preview）が返ります。バージョン ID は一覧に無くても model に指定できます。

日本語で使うとき

state も instructions も日本語で送れますが、公式は英語が最も精度が高く、日本語を含む CJK は同等ではないと明記しています。選択肢のキー（billing など）はコードで分岐に使うので、英数字にしておくと扱いやすくなります。