Jev API ドキュメント

概要

Jev は渡した 1 つの state——サポートチケット、チャットログ、ツール呼び出し、任意のテキストや JSON——を型付き質問群で評価し、コードが分岐できる構造化回答を返します。テキストは生成しません。

1 リクエストで最大 8 問を評価でき、state の入力コストを共有します。リクエスト本文は TypeSafe の SystemOne API と同じ形です——既存の統合を移すにはベース URL と Bearer キーを差し替えるだけです。

• POST https://jevmodel.org/v1/systemone —— 唯一の判定エンドポイント。
• CORS は開放済み（access-control-allow-origin: *）で、どのオリジンからでも応答します。それでもキーはサーバーに置いてください。
• プレイグラウンドはブラウザセッション経由で同一リクエストを送ります——プレビューそのものが送信内容です。

認証

すべての API 呼び出しに jevmodel.org の API キーが必要です。ダッシュボード → API keys で作成します。キーは sk- で始まり作成時に一度だけ表示されます。JEVMODEL_API_KEY などの環境変数に保存してください。

Authorization: Bearer $JEVMODEL_API_KEY

キーはアカウントのトークン残高に紐付き、ダッシュボードで無効化できます。クライアント側コードに埋め込んだりリポジトリにコミットしたりしないでください——漏洩時は無効化して再発行を。プレイグラウンドはログイン済みのブラウザセッションで認証するためキー不要です。

HTTP エンドポイント

Bearer 認証付きで JSON 本文を評価エンドポイントへ送信します：

POST /v1/systemone HTTP/1.1
Host: jevmodel.org
Authorization: Bearer $JEVMODEL_API_KEY
Content-Type: application/json
Idempotency-Key: ticket-4821-run-1   # optional

Idempotency-Key は任意（最大 100 文字）。同じキーでリトライすると元の課金レコードが再利用されるため、同一入力が二重課金されません。

curl -X POST https://jevmodel.org/v1/systemone \
  -H "Authorization: Bearer $JEVMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "The customer has been billed twice and wants a refund today.",
    "questions": {
      "route": {
        "type": "choice",
        "instructions": "Which queue should own this ticket?",
        "criteria": {
          "billing": "Payments, refunds, invoices",
          "technical": "Product errors and usage problems",
          "sales": "Pricing, upgrades, new business"
        }
      },
      "escalate": {
        "type": "noul",
        "instructions": "Does this need a human right now?"
      },
      "urgency": {
        "type": "score",
        "instructions": "How urgent is this for the customer?",
        "criteria": ["routine", "soon", "urgent", "critical"]
      }
    }
  }'

リクエスト本文

state と questions マップを持つ 1 つの JSON オブジェクト：

{
  "model": "jev-latest",
  "state": "The customer has been billed twice and wants a refund today.",
  "questions": {
    "route": {
      "type": "choice",
      "instructions": "Which queue should own this ticket?",
      "criteria": {
        "billing": "Payments, refunds, invoices",
        "technical": "Product errors and usage problems",
        "sales": "Pricing, upgrades, new business"
      }
    },
    "escalate": {
      "type": "noul",
      "instructions": "Does this need a human right now?"
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is this for the customer?",
      "criteria": ["routine", "soon", "urgent", "critical"]
    }
  }
}

各質問には type と instructions（最大 1,800 文字）が必要で、何を判定するかを指示します。criteria が解答空間を供給します——choice と score は必須、noul は任意。

質問タイプ

アプリが扱える回答の形を選んでください。

シリアライズ済み criteria は質問ごとに 2,000 文字まで。バリデーション失敗はトークン予約前に 422 を返します——不正リクエストは課金されません。

レスポンス JSON

200 レスポンスはモデル出力そのものです：解決されたモデル、質問名ごとの回答、usage。以下の数値は例示です——実際の出力は実リクエストで確認してください。

{
  "model": "jev-latest",
  "answers": {
    "route": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.93, "technical": 0.05, "sales": 0.02 },
      "confidence": 0.93
    },
    "escalate": {
      "type": "noul",
      "noul": 0.12
    },
    "urgency": {
      "type": "score",
      "score": 1.4,
      "confidence": 0.88
    }
  },
  "usage": { "input_tokens": 136, "output_tokens": 18 }
}

• answers は質問名をキーにします——質問したフィールドだけを読みます。
• choice は選択ラベルで分岐し、全分布が必要なら probabilities を確認します。
• noul は P(yes)——閾値はコードが決めます。
• usage.input_tokens がこの呼び出しの実課金量です。出力トークンは無料。

課金

API は入力トークンのみ課金——出力は無料。各呼び出しは推定値を先に予約し、モデルが報告する実際の usage.input_tokens で精算します。上流で失敗した場合、予約分は自動的に全額返金されます。

• ログインで 100,000 入力トークン無料。有料パックは $9.90 からで有効期限なし。
• 残高不足は Jev 呼び出し前に 402 を返します。
• すべての 200 レスポンスの X-Tokens-Remaining が精算後残高です。
• 自分で推定：ceil(JSON.stringify({state, questions}).length / 4)。

モデルと制限

jev-latest がデフォルトで現在提供中のモデル——model フィールドは任意。プレイグラウンドに表示される Laya バリアントは近日公開予定で、このエンドポイントでは未公開です。

上記は API バリデーターの制限で、上流モデルには独自のコンテキスト制限がある場合があります。

エラーとリトライ

エラーは機械可読の type と人間向け message を持つ JSON で返ります：

{
  "error": {
    "type": "invalid_request_error",
    "message": "At most 8 questions per request."
  }
}

429 と 502 は指数バックオフでリトライ——レート窓は 1 分単位なので短い待機で十分なことがほとんどです。リトライ時は Idempotency-Key を送り、同一課金レコードに精算させましょう。

エージェント向け MCP サーバー

jevmodel.org は https://jevmodel.org/mcp で Streamable HTTP のリモート MCP サーバーも動かしています。4 つのツール——jev_decide（state+questions の完全契約）、jev_noul、jev_choice、jev_score——を公開し、Claude Code、Cursor、Cline などのコーディングエージェントが HTTP を書かずに Jev を呼べます。

claude mcp add --transport http jev https://jevmodel.org/mcp \
  --header "Authorization: Bearer $JEVMODEL_API_KEY"

• 本 API と同じ Authorization: Bearer sk-… キーと同じトークン残高——tools/call は入力トークンのみ課金。
• initialize・ping・tools/list は認証不要。tools/call のみキーを使います。
• GET /mcp はエージェントと人間向けの JSON ディスカバリーカードを返します。

Claude Code・Cursor のセットアップコマンドと対応する agent skill（判断プレイブック）は エージェントツールページにあります。

エージェントツールガイド →

プレイグラウンドから API へ

まずプレイグラウンドでシナリオを作りましょう——リクエストプレビューがアプリが送るべき JSON をそのまま表示し、Copy API example が対応する cURL をくれます。回答に満足したらダッシュボードでキーを作成し、ブラウザセッションを Bearer 認証に置き換えます。

さらに読む：Jev の使い方が最初の呼び出しを最後まで案内し、Jev API 例に各質問タイプの本番パターンがあります。