Jev APIキーの取得方法 TypeSafe AI

Jev は TypeSafe AI の意思決定モデルです。状態の一部と型付きの質問のセットを送信すると、Jev は散文ではなく確率で回答します。このガイドでは、Jev API キーと最初のリクエストについて説明します。Jev とは何か、なぜテキストではなく数値を返すのかという背景については、まず「Jev とは」をお読みください。検索結果が混乱しているため、明確にしておきます。これは TypeSafe AI のモデルである Jev であり、YouTuber の FaZe Jev や JEV ワクチンではありません。

Jev API キーは他のベアラートークンと同様に機能します。このパターンが初めての場合は、「API キーとは」で基本を学べます。直接 API アクセスはアーリーアクセス段階にあるため、最初のステップはウェイティングリストから外れることです。その後、キーを作成し、リクエストの形式を学び、curl と Python SDK でエンドポイントを呼び出し、確率フィールドを読み取り、これらの確率に対するアサーションを設定してリクエストを Apidog に接続します。待てない場合は、同じモデルが Vercel AI Gateway で利用可能であり、ウェイティングリストはありません。FAQ でその方法について説明しています。

ステップ1：アーリーアクセスを取得し、キーを作成する

この執筆時点では、Jev はアーリーアクセスです。TypeSafe のローンチ投稿では、「できるだけ早く開発者をウェイティングリストから解放する」と述べられているため、typesafe.ai でウェイティングリストに参加し、コンソールからの招待を待ってください。まだセルフサービスのサインアップはありません。コンソールアカウントがアクティブになったら、console.typesafe.ai/settings/keys にアクセスしてキーを作成します。一度コピーしたら、パスワードのように扱ってください。

コードに直接貼り付けるのではなく、環境変数としてエクスポートしてください。

export TYPESAFE_API_KEY="ts_..."

公式の curl の例と Python SDK はどちらも環境から TYPESAFE_API_KEY を読み取るため、1つの変数で以下のすべての例をカバーできます。もしキーがコミットに含まれてしまった場合は、コンソールでキーをローテーションし、リポジトリ全体で API キーの漏洩チェックを実行してください。

ステップ2：リクエストの形式を理解する

すべての Jev の呼び出しは、単一の POST https://api.typesafe.ai/v1/systemone で、TypeSafe API リファレンスに記載されている3つのボディフィールドを含みます。

各質問は、次の3つのプリミティブのいずれかです。

レスポンスには、model および usage.input_tokens / usage.output_tokens も含まれます。異なる種類の質問は1つの状態を共有でき、1回のラウンドトリップで結果が返されます。

ステップ3：curl で最初のリクエストを作成する

このリクエストは、1つのサポートチケットに対して3つのプリミティブすべてを実行します。

curl https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "My card was charged twice for one order and nobody has replied in three days.",
    "questions": {
      "needs_review": {
        "type": "noul",
        "instructions": "Does this ticket need a human agent?",
        "criteria": {
          "true": "money, legal, or an unanswered complaint",
          "false": "a routine question a bot can close"
        }
      },
      "route": {
        "type": "choice",
        "instructions": "Route this ticket to a team.",
        "criteria": {
          "billing": "payment or charge problems",
          "shipping": "delivery problems",
          "technical": "application bugs"
        }
      },
      "urgency": {
        "type": "score",
        "instructions": "How urgent is this ticket?",
        "criteria": ["low", "medium", "high"]
      }
    }
  }'

レスポンスは次のようになります（値は例示です）。

{
  "model": "jev-1.13.0",
  "answers": {
    "needs_review": { "type": "noul", "noul": 0.97 },
    "route": {
      "type": "choice",
      "choice": "billing",
      "confidence": 0.98,
      "probabilities": { "billing": 0.98, "shipping": 0.01, "technical": 0.01 }
    },
    "urgency": {
      "type": "score",
      "score": 1.6,
      "confidence": 0.62,
      "legend": { "0": "low", "1": "medium", "2": "high" },
      "probabilities": { "0": 0.02, "1": 0.36, "2": 0.62 }
    }
  },
  "usage": { "input_tokens": 190, "output_tokens": 0 }
}

ステップ4：確率フィールドを読み取る

数値を正確に読み取ってください：

• noul は「はい」の確率です。0.97 は、Jev がこのチケットが人間による対応を必要とすると97%確信していることを意味します。
• choice は最も確率の高いオプションで、probabilities はすべてのオプションをリストし、confidence は選択の決定度合いを示します。0.98 のルーティングは自動化しても安全ですが、0.51 で次点が0.47 のルーティングは五分五分です。
• score は、順序付けられたレベル全体の確率加重位置であり、1.6 は「中」（1）と「高」（2）の間に位置します。legend は各インデックスをそのラベルにマッピングし、probabilities は完全な分布を示します。

出力はラベルではなく分布であるため、閾値はモデルではなくあなたが設定します。これが、ステップ6のアサーションが数値をテストする理由です。

ステップ5：Python SDK を使用した同じ呼び出し

SDK をインストールしてください。クライアントは環境から TYPESAFE_API_KEY を取得します。

pip install typesafe-sdk

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

with TypeSafeClient() as client:
    response = client.system_one(
        state="My card was charged twice for one order and nobody has replied in three days.",
        questions={
            "needs_review": Noul(
                instructions="Does this ticket need a human agent?",
                criteria={"true": "money, legal, or an unanswered complaint",
                          "false": "a routine question a bot can close"},
            ),
            "route": Choice(
                instructions="Route this ticket to a team.",
                criteria={"billing": "payment or charge problems",
                          "shipping": "delivery problems",
                          "technical": "application bugs"},
            ),
            "urgency": Score(
                instructions="How urgent is this ticket?",
                criteria=["low", "medium", "high"],
            ),
        },
    )

print(response.nouls["needs_review"].noul)
print(response.choices["route"].choice, response.choices["route"].probabilities)
print(response.scores["urgency"].score)

応答オブジェクトでは、回答はタイプ別にグループ化されています（nouls、choices、scores）。同じ形式の JavaScript SDK があり、Vercel AI Gateway を使用している場合は、AI SDK 7 の experimental_evaluate がモデルを typesafe-ai/jev として呼び出します。ただし、1つの違いがあります。ブール型質問は noul ではなく probability フィールドを返します。

ステップ6：Apidog に Jev API キーを保存してテストする

curl はキーが一度機能することを証明します。Apidog は、リクエストをチーム全体で再実行可能、アサート可能、モック可能にします。

キーをシークレット変数として保存する。 TypeSafe という名前の環境を作成し、TYPESAFE_API_KEY をシークレットとして追加します。これにより、その値はUIでマスクされ、エクスポートに含まれなくなります。Apidog 環境とシークレット変数でセットアップ手順が説明されています。リクエストの認証を Bearer Token に設定し、{{TYPESAFE_API_KEY}} を値として使用します。

POST リクエストを作成する。 https://api.typesafe.ai/v1/systemone への POST リクエストを追加し、ステップ3の JSON ボディを貼り付けて送信します。レスポンスパネルに回答ツリーが表示されるため、アサーションを記述する前に確率を確認できます。

散文ではなく、確率でアサートする。 ビジュアルアサーションビルダーで、気になるフィールドに JSONPath 式を向けます：

• $.answers.needs_review.noul が 0.9 より大きい
• $.answers.route.choice が billing と等しい
• $.answers.route.probabilities.billing が 0.8 より大きい
• $.answers.urgency.score が 1 以上
• $.usage.input_tokens が 1000 未満

スクリプトを好む場合は、ポストプロセッサーが使い慣れた pm API を受け入れます。

const body = pm.response.json();
pm.test("ticket flagged for a human", () => {
  pm.expect(body.answers.needs_review.noul).to.be.above(0.9);
});
pm.test("routed to billing", () => {
  pm.expect(body.answers.route.choice).to.eql("billing");
});

テストシナリオとして保存する。 チケットと予想されるルートの小さな CSV とともにリクエストをテストシナリオにドロップし、指示または基準の変更があるたびに実行します。プロンプトの編集はコードの変更です。10行のシナリオは、0.95 を静かに0.6 に変更する編集を検出します。同じシナリオは Apidog CLI を介して CI で実行されるため、回帰はマージをブロックします。

宣言されたレスポンス形式をモックする。 エンドポイントに応答スキーマ（3つの回答オブジェクトと usage）を定義すると、Apidog のスマートモックがすぐにリアルな偽の確率を提供します。フロントエンドは、バックエンドがリリースされる前にモックに対して「レビューが必要」バッジとルーティングUIを構築でき、その後、1つの環境変更でモックURLを実際のエンドポイントに置き換えることができます。

シートの計画について：Apidog のフリープランには4ユーザーが含まれており、有料ティアはシートごとに課金されます。

コード内の閾値

アサーションがパスすると、同じ数値が本番ロジックを駆動します。閾値を一箇所にまとめて名前を付けてください。

REVIEW_THRESHOLD = 0.9
AUTO_ROUTE_CONFIDENCE = 0.85

needs_review = response.nouls["needs_review"].noul >= REVIEW_THRESHOLD
route = response.choices["route"]

if route.confidence >= AUTO_ROUTE_CONFIDENCE and not needs_review:
    assign(ticket, team=route.choice)
else:
    queue_for_human(ticket, suggested=route.choice)

すべての決定で完全な probabilities マップをログに記録し、後で実際のデータから閾値を調整できるようにします。信頼度が低い場合は、人間のレビューをデフォルトにしてください。モデルは自信がないことを伝えています。

制限、料金、モデル

TypeSafe モデルページから直接引用：

この価格で、100万枚の短いチケットは10ドル未満で処理できます。TypeSafe はまた、Jev が顧客のリクエストや応答でトレーニングされていないことを述べています。

よくあるエラーとその対処法

イテレーション中に最も遭遇するのは 422 エラーでしょう。ステップ6のエンドポイントスキーマは、リクエストがマシンを出る前にそのほとんどを捕捉します。

よくある質問 (FAQ)

Jev API に無料枠はありますか？ 公開ドキュメントにはトークンごとの料金が記載されており、無料枠やスタータークレジットについては説明されておらず、アクセス自体は現在ウェイティングリスト形式です。招待が届いたらコンソールで現在のオファーを確認し、他の場所で見た数値は非公式なものとして扱ってください。

1つのリクエストで複数の回答を得られますか？ はい。questions はマップなので、noul、choice、score のすべてを1回の呼び出しで1つの状態に対して実行できます。これは3つのリクエストよりも安価であり、1つの入力を共有するため、回答の一貫性が保たれます。

これはチャットモデルの構造化出力とどう違うのですか？ 構造化出力は、言語モデルに有効なJSONを出力させますが、内部の値は依然として生成されたトークンであり、「信頼度」フィールドはモデル自身が書いたテキストです。Jev は測定された確率をネイティブな出力として返すため、noul > 0.9 のようにアサートし、その比較を信頼することができます。

Vercel を利用している場合でも TypeSafe の SDK が必要ですか？ いいえ。Vercel AI SDK は、モデルIDを typesafe-ai/jev として experimental_evaluate を介して Jev を公開しています。TypeSafe キーの代わりに AI Gateway キーで認証し、ブール型の回答は probability として返されます。

次のステップ

これで Jev API キー、curl および Python で動作するリクエスト、そして noul、choice、score の明確な読み取り方法が分かりました。リクエストを Apidog に投入し、確率アサーションを追加し、テストシナリオを保存して、プロンプトの編集がコードのようにテストされるようにします。一緒に進めるには、Apidog をダウンロードしてください。