Jev APIの使い方
Jev固有のAPIで、型付きの判断をアプリに組み込みます。
Jev APIは、指定した質問に沿ってテキストを評価し、型の決まった判断結果を返すAPIです。 state、model、questionsを送り、同じ質問IDを持つanswersを読み取ります。チャットの自由文から後でラベルを抽出する方式ではありません。
このページでは接続から応答処理までを扱います。モデルの用途や料金の背景は、Jevモデルの解説をご覧ください。
確認日:2026年9月28日。 リクエストと応答はTypeSafe公式文書、ゲートウェイの経路はOmniaKeyの実装と照合しました。サンプルはオフラインで確認しており、新たな有料性能テストではありません。公式直結の料金・上限がそのままゲートウェイに適用されるとは限りません。
エンドポイントとAPIキーを選ぶ
| 接続先 | POSTエンドポイント | 必要なキー |
|---|---|---|
| OmniaKey | https://api.omniakey.com/v1/alpha/search | jev-latestを利用できるOmniaKey APIキー |
| TypeSafe公式 | https://api.typesafe.ai/v1/systemone | TypeSafe APIキー |
どちらもAuthorization: Bearer ...とJev固有の本文を使います。別サービスのキーを送らないでください。 OmniaKey側も/v1/chat/completionsではなく、stateをmessagesに置き換えることはできません。
権限を絞ったキーを作り、現在のJev提供経路を確認してから、ローカル環境にOMNIAKEY_API_KEYを設定します。キーをブラウザコード、Git、スクリーンショットへ含めないでください。共通手順はAPIクイックスタート(英語)にあります。
完全なJSONリクエストを作る
以下をjev-request.jsonとして保存します。同じサポートメッセージについて、担当部署、不満の度合い、緊急性を一度に評価する例です。TypeSafeは現在英語で最も高い精度が得られると説明しているため、例の入力は英語にしています。日本語の業務には自分の代表的なデータで検証してください。
{
"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?"
}
}
}
質問IDは応答との対応に使われます。公式仕様ではID自体は推論に使われないため、判断内容はキー名だけでなくinstructionsに書きます。stateにはテキストを含むJSONオブジェクトや配列も指定でき、問い合わせ記録を項目別に渡せます。
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
公式直結の場合はURLをhttps://api.typesafe.ai/v1/systemone、キーを$TYPESAFE_API_KEYに変更します。本文の形式は維持し、そのアカウントが受け付けるモデル名を確認してください。
Choice・Score・Noulの応答を読む
| 種類 | 指定する内容 | 主な応答フィールド | 読み方 |
|---|---|---|---|
choice | 選択肢と説明のマップ、最大255個 | choice、probabilities、confidence | 選ばれたラベルと全選択肢の確率分布 |
score | 2–10段階の順序付き評価基準 | score、legend、probabilities、confidence | 確率で重み付けした段階値。小数にもなる |
noul | はい・いいえの質問。true / falseの基準は任意 | noul | 「はい」の確率を0から1で返す。真偽値ではない |
応答にはmodelとusage.input_tokens / usage.output_tokensも含まれます。現在jev-latestはjev-1.13.0を指しますが、エイリアスは後で変わり得ます。評価時は実際に返されたバージョンを記録してください。
3段階の基準で1.05なら段階1を少し上回る意味で、100点満点の1.05点ではありません。legendと照合します。Noulが0.8でも、それだけで返金を実行する根拠にはなりません。ラベル付き業務データで閾値を決めてください。confidenceは分布から計算される値で、正解の保証ではありません。
以下はレスポンス全体の構造を示すサンプルで、実際に取得した API の結果ではありません。回答の値やトークン数は説明用であり、実際の結果は異なります。
{
"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を想定せず、Jevの応答を表示します。本番では後述する回数と時間を制限した再試行を追加してください。
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))
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 3、またはfetchとAbortSignal.timeoutを内蔵するNode.jsを使います。HTTPのサンプルであり、OpenAI SDKがJev固有のSchemaに対応するという意味ではありません。TypeSafe独自SDKは公式リファレンスを確認してください。
コンテキスト長・レート制限・料金
現在の公式仕様では、リクエスト全体が64K tokens以内であることに加えて、stateと最長の質問1つの合計が32K以内である必要があります。両方を満たすよう、不要な情報を削り、同じ状態を本当に必要とする質問だけをまとめます。
TypeSafeの記載は毎秒250,000 tokens、毎分1,200リクエストですが、早期提供中は変更される場合があります。アカウントの処理上限であり、1件の速度でもOmniaKeyの保証値でもありません。ゲートウェイ側に追加の制限がある場合もあります。
公式直結は確認時点で入力100万tokensあたり$0.042、出力tokensは無料です。無料でも出力用量は返されます。API全体が無料になるわけではなく、ゲートウェイの課金単位が同じとも限りません。OmniaKeyでは現在のモデル料金と利用記録を確認し、背景はJevの料金・制限の解説で確認してください。
OmniaKey の現在の Jev 料金はリクエスト単位です。費用を見積もる際は、モデルの最新料金とダッシュボードの利用記録を確認してください。
エラーと再試行の扱い
| TypeSafe直結の状態 | 最初の確認 | 対応 |
|---|---|---|
401 | キーのサービスとBearerヘッダー | キーを修正。同じ無効なキーでは再試行しない |
422 | 必須項目、質問の種類、criteria | エラーが示す項目を修正 |
429 | リクエスト数またはtoken上限 | あればRetry-Afterを守り、上限付き指数バックオフとジッターを使う |
529 | 一時的な過負荷 | 試行回数と総待機時間を制限して再試行 |
これは公式直結の状態説明です。ゲートウェイには独自の認証・検証・上流エラー形式があり得ます。利用できない場合はURLと正確なmodel IDも確認し、共有する診断情報にキーや非公開本文を含めないでください。
モデルの評価と後続アクションは分離します。分類の再試行でメールや返金を二重実行してはいけません。失敗が続いたら明示的なエラーやレビューに回し、確かな判断であるかのような既定値へ黙って置き換えないでください。
よくある質問
これはJevの公式APIドキュメントですか?
OmniaKeyの接続ガイドです。直結の仕様はTypeSafe APIリファレンス、料金と制限は公式モデルページが基準です。冒頭の表で接続先を区別しています。
画像入力や文章生成はできますか?
Jev 1.13はテキストを評価して型付きの判断を返します。画像などは先にテキストや項目へ変換します。説明文、画像、動画の生成には別のモデルや処理が必要です。
エイリアスと固定バージョンはどちらを使いますか?
試用にはエイリアスが便利です。閾値を使う本番処理では対応する固定バージョンを評価し、応答のmodelを記録して、変更前に閾値を再検証します。提供モデルは経路ごとに異なる場合があります。