# Jev APIの使い方 > Jev APIをcurl・Python・Node.jsで呼び出す手順を解説。Choice、Score、Noulの応答、APIキー、コンテキスト長、レート制限と再試行を確認し、TypeSafe直結とOmniaKeyのエンドポイントや課金条件の違いも整理します。 - Canonical HTML: https://omniakey.com/ja/blog/jev-api-guide - Markdown: https://omniakey.com/ja/blog/jev-api-guide.md - Published: 2026-09-28 (updated 2026-10-24) - Author: Kiki, COO at OmniaKey - Language: ja - Category: API setup - Reading time: 11 min - All posts: https://omniakey.com/blog/llms.txt --- **Jev APIは、指定した質問に沿ってテキストを評価し、型の決まった判断結果を返すAPIです。** `state`、`model`、`questions`を送り、同じ質問IDを持つ`answers`を読み取ります。チャットの自由文から後でラベルを抽出する方式ではありません。 このページではJev APIの使い方を、接続から応答処理まで扱います。モデルの用途や料金の背景は、[Jevモデルの解説](https://omniakey.com/ja/blog/jev-model-explained)をご覧ください。 > **確認日：2026年10月24日。** リクエストと応答は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提供経路](https://omniakey.com/ja/jev-latest)を確認してから、ローカル環境に`OMNIAKEY_API_KEY`を設定します。キーをブラウザコード、Git、スクリーンショットへ含めないでください。共通手順は[APIクイックスタート（英語）](https://docs.omniakey.com/en/quick-start)にあります。 ## 完全な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?" } } } ``` 質問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 ``` 公式直結の場合は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.14.0`を指しますが、エイリアスは後で変わり得ます。評価時は実際に返されたバージョンを記録し、固定したい場合は`jev-1.14.0`を指定してください。 3段階の基準で`1.05`なら段階1を少し上回る意味で、100点満点の1.05点ではありません。`legend`と照合します。Noulが`0.8`でも、それだけで返金を実行する根拠にはなりません。ラベル付き業務データで閾値を決めてください。`confidence`は分布から計算される値で、正解の保証ではありません。 以下はレスポンス全体の構造を示すサンプルで、実際に取得した API の結果ではありません。回答の値やトークン数は説明用であり、実際の結果は異なります。 ```json { "model": "jev-1.14.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の応答を表示します。本番では後述する回数と時間を制限した再試行を追加してください。 ```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 3、または`fetch`と`AbortSignal.timeout`を内蔵するNode.jsを使います。HTTPのサンプルであり、OpenAI SDKがJev固有のSchemaに対応するという意味ではありません。TypeSafe独自SDKは[公式リファレンス](https://docs.typesafe.ai/api)を確認してください。 ## コンテキスト長・レート制限・料金 現在の公式仕様では、**リクエスト全体が64K tokens以内**であることに加えて、**`state`と最長の質問1つの合計が32K以内**である必要があります。両方を満たすよう、不要な情報を削り、同じ状態を本当に必要とする質問だけをまとめます。 TypeSafeの記載は**毎秒250,000 tokens、毎分1,200リクエスト**ですが、早期提供中は変更される場合があります。アカウントの処理上限であり、1件の速度でもOmniaKeyの保証値でもありません。ゲートウェイ側に追加の制限がある場合もあります。 公式直結は確認時点で**入力100万tokensあたり$0.042、出力tokensは無料**です。無料でも出力用量は返されます。API全体が無料になるわけではなく、ゲートウェイの課金単位が同じとも限りません。OmniaKeyでは現在のモデル料金と利用記録を確認し、背景は[Jevの料金・制限の解説](https://omniakey.com/ja/blog/jev-model-explained)で確認してください。 OmniaKey の現在の Jev 料金は**リクエスト単位**です。費用を見積もる際は、モデルの最新料金とダッシュボードの利用記録を確認してください。 ## エラーと再試行の扱い |TypeSafe直結の状態|最初の確認|対応| |-|-|-| |`401`|キーのサービスとBearerヘッダー|キーを修正。同じ無効なキーでは再試行しない| |`422`|必須項目、質問の種類、`criteria`|エラーが示す項目を修正| |`429`|リクエスト数またはtoken上限|あれば`Retry-After`を守り、上限付き指数バックオフとジッターを使う| |`529`|一時的な過負荷|試行回数と総待機時間を制限して再試行| これは公式直結の状態説明です。ゲートウェイには独自の認証・検証・上流エラー形式があり得ます。利用できない場合はURLと正確なmodel IDも確認し、共有する診断情報にキーや非公開本文を含めないでください。 モデルの評価と後続アクションは分離します。分類の再試行でメールや返金を二重実行してはいけません。失敗が続いたら明示的なエラーやレビューに回し、確かな判断であるかのような既定値へ黙って置き換えないでください。 ## よくある質問 ### これはJevの公式APIドキュメントですか？ OmniaKeyの接続ガイドです。直結の仕様は[TypeSafe APIリファレンス](https://docs.typesafe.ai/api)、料金と制限は[公式モデルページ](https://docs.typesafe.ai/models)が基準です。冒頭の表で接続先を区別しています。 ### 画像入力や文章生成はできますか？ Jev 1.14は既定でテキストを評価して型付きの判断を返します。画像などは先にテキストや項目へ変換します。1.14の画像入力は実験的な設定の背後にあり、説明文や動画の生成には別のモデルや処理が必要です。 ### エイリアスと固定バージョンはどちらを使いますか？ 試用にはエイリアスが便利です。閾値を使う本番処理では対応する固定バージョンを評価し、応答の`model`を記録して、変更前に閾値を再検証します。提供モデルは経路ごとに異なる場合があります。 ## 参考資料 - [TypeSafe APIリファレンス](https://docs.typesafe.ai/api) - [モデル・料金・エイリアス・制限](https://docs.typesafe.ai/models) - [Confidenceの説明](https://docs.typesafe.ai/confidence) - [Jev 1.13の制約](https://docs.typesafe.ai/model-jaggedness/jev-1.13)