Decisions API

多くのモデル呼び出しでは文章が返され、そこから判断結果を取り出す必要があります。JSON を要求し、解析・検証し、形式が崩れれば再試行する、という流れです。Decisions API は、その処理を不要にします。アプリケーションの現在の状態と質問を送信すると、真偽の確率、指定した選択肢のいずれか、独自の尺度上の値など、型が定まった回答が確率とともに返ります。

会話ではなく、ソフトウェア内部の判断に使う API です。チケットの振り分け、ツール呼び出しの可否判定、キューの優先順位付け、人が確認する前の投稿の評価などに利用できます。

POST https://api.beatapi.io/v1/systemone

エンドポイントのパス、リクエストとレスポンスのボディは TypeSafe の API と同じです。TypeSafe API またはその SDK 向けのクライアントは、ベース URL とモデル名を変更するだけで利用でき、他の調整は不要です。POST /v1/decisions も別名として引き続き利用できます。

クイックスタート

まずは jev-1.13-free を使用してください。入力も出力も $0 で、残高がゼロでも利用できます。デフォルトの auto グループのキーを使います。無料版には専用の上限があり、初回チャージ前は毎分 1 回の成功リクエスト、チャージ後は毎分最大 10 回です。無料の呼び出しを参照してください。

curl https://api.beatapi.io/v1/systemone \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-1.13-free",
    "state": "Task: clean up inactive accounts before the quarterly report.\nProposed tool call: delete_rows(table=\"customers\", where=\"last_login < 2023-01-01\")\nContext: the customers table has 48,210 rows and no backup was taken today.",
    "questions": {
      "safe_to_run": {
        "type": "noul",
        "instructions": "Is this action safe to run without a human approving it first?",
        "criteria": {
          "true": "Reversible or low-impact, and clearly within the stated task.",
          "false": "Destructive, irreversible, or broader than the task requires."
        }
      }
    }
  }'

以下のレスポンスは説明用の例であり、実測結果ではありません。JSON を解析し、HTTP ステータスと回答の型を確認して値を検証したうえで、独自のしきい値を適用してください。

{
  "id": "task_01J...",
  "model": "jev-1.13-free",
  "answers": {
    "safe_to_run": { "type": "noul", "noul": 0.04 }
  },
  "usage": { "input_tokens": 384, "output_tokens": 22 }
}

0.04 は、モデルが回答を「はい」と判断する確率です。4% のため、エージェントは処理を止めて人に確認します。これが、この質問を行う目的です。

型付きの判断を 1 回で取得

接続先を BeatAPI に設定し、state と questions を送信して answers を取得します。別名の /v1/decisions も同じように使えます。これは chat/completions ではなく、jev-1.13-free はそちらでは利用できません。JSON を修復するための再試行ループは不要です。

const response = await fetch("https://api.beatapi.io/v1/systemone", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BEATAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "jev-1.13-free",
    state: {
      task: "clean up inactive accounts",
      tool: 'delete_rows(table="customers", where="last_login < 2023-01-01")',
      rows: 48210,
      backup_today: false,
    },
    questions: {
      safe_to_run: {
        type: "noul",
        instructions: "Is this action safe to run without a human approving it first?",
        criteria: {
          true: "Reversible or low-impact, and clearly within the stated task.",
          false: "Destructive, irreversible, or broader than the task requires.",
        },
      },
    },
  }),
});
if (!response.ok) {
  // On HTTP 429, wait the Retry-After seconds before retrying.
  throw new Error(`JEV HTTP ${response.status}; Retry-After: ${response.headers.get("Retry-After")}`);
}
const decision = await response.json();
const answer = decision.answers?.safe_to_run;
if (answer?.type !== "noul" || !Number.isFinite(answer.noul)
    || answer.noul < 0 || answer.noul > 1) {
  throw new Error("Invalid JEV answer; route to human review");
}
// Illustrative threshold: evaluate it on your own cases before use.
const needsReview = answer.noul < 0.9;
console.log({ probability: answer.noul, needsReview });

リクエスト

各質問には type、instructions、そして型に応じて criteria を指定します。

3 つの質問形式

noul：較正された確率

単純な二者択一ではなく、しきい値に基づいて真偽を判断したい場合に使用します。回答は 0～1 の数値です。

"refund_ok": {
  "type": "noul",
  "instructions": "Should this refund be approved automatically?",
  "criteria": {
    "true": "Clear billing error, under $100, first request from this account.",
    "false": "Disputed usage, over $100, or a repeat request."
  }
}

"refund_ok": { "type": "noul", "noul": 0.83 }

criteria は任意ですが、真偽の両方の条件を説明すると、回答がより明確になります。しきい値は自分で設定してください。例えば、0.9 を超えたら自動承認、0.6 未満なら上位の担当者へ回し、その間は確認待ちのキューに入れます。

choice：指定した選択肢から選択

criteria は、各選択肢の名前とその意味を対応付けるオブジェクトです。回答には、選ばれた選択肢と全選択肢の確率分布が含まれます。

"route": {
  "type": "choice",
  "instructions": "Which queue should this ticket go to?",
  "criteria": {
    "billing": "Payment, invoices, refunds, or charges.",
    "technical": "The product is broken or erroring.",
    "sales": "Pre-purchase questions about plans or pricing."
  }
}

"route": {
  "type": "choice",
  "choice": "billing",
  "probabilities": { "billing": 1, "technical": 0, "sales": 0 },
  "confidence": 1
}

score：独自の尺度上の値

criteria は、尺度を低い順に説明する配列です。回答は、0 から始まる配列のインデックス上の連続値です。

"urgency": {
  "type": "score",
  "instructions": "How urgent is this ticket?",
  "criteria": [
    "1 - can wait a week",
    "2 - answer within a few days",
    "3 - answer today",
    "4 - answer within an hour",
    "5 - wake someone up"
  ]
}

"urgency": {
  "type": "score",
  "score": 1.98,
  "legend": { "0": "1 - can wait a week", "1": "2 - answer within a few days",
              "2": "3 - answer today", "3": "4 - answer within an hour",
              "4": "5 - wake someone up" },
  "probabilities": { "0": 0, "1": 0.17, "2": 0.67, "3": 0.16, "4": 0 },
  "confidence": 0.72
}

1.98 は legend["1"] と legend["2"] の間で、後者の「今日中に回答」に近い値です。区分に振り分ける場合は丸め、キューを並べ替える場合は小数のまま使用します。

1 回の呼び出しで複数の質問

同じ状態について必要な質問をまとめて送信できます。各回答は独立しており、共通の状態は質問ごとではなく 1 回だけ計上されます。jev-1.13-free の呼び出しは引き続き無料です。

curl https://api.beatapi.io/v1/systemone \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-1.13-free",
    "state": {"ticket": "charged twice this month", "plan": "pro", "tenure_days": 412},
    "questions": {
      "refund_ok": {"type": "noul", "instructions": "Approve the refund automatically?"},
      "urgency":   {"type": "score", "instructions": "How urgent?", "criteria": ["low", "medium", "high"]}
    }
  }'

レスポンス

レスポンスは同期的に返され、HTTP レスポンスが成功すると判断は完了しています。ポーリングや生成ファイルの取得は不要です。

制限

• コンテキスト。 state とすべての質問を合わせて 64K トークンまでです。また、state と最も長い個別の質問の合計は 32K トークン以内である必要があります。モデルの上限を参照してください。
• サンプリングパラメーターは使用できません。 temperature、top_p、seed などは受け付けません。回答の形式が一定になるように設計されたモデルです。
• ストリーミングはありません。 回答は値であり、トークンの列ではありません。
• choice には空でない criteria オブジェクト、score には空でない criteria 配列が必要です。 条件を満たさない場合は HTTP 400 で拒否され、どちらの条件に違反したかが示されます。instructions は任意ですが、空の値を指定すると処理に送信されずに拒否されます。

エラー

エラーは BeatAPI 標準の形式で返され、すべてのエラーに retryable が含まれます。一覧と再試行の方針はエラーを参照してください。

失敗した呼び出しではクレジットは消費されません。

課金

有料モデル jev-1.13 は、state と questions が占める入力トークンのみを対象に、入力 1M トークンあたり $0.042 で課金されます。出力は生成された文章ではなく型付きの値のため、課金されません。各レスポンスの usage.input_tokens で、実際に計上されたトークン数を確認し、呼び出しごとの費用を照合できます。

そのため、同じ状態を何度も送信するより、1 回の呼び出しで複数の質問をまとめた方が、費用を大幅に抑えられます。

無料の呼び出し

"model": "jev-1.13-free" を指定すると、呼び出しは無料です。同じモデル、同じリクエストとレスポンスを使用し、指定した質問名で回答が返ります。残高がゼロでも使えるため、チャージ前に JEV をプロジェクトへ組み込めます。

• 新しいキーがデフォルトで使用する auto グループから利用できます。特定の 1 グループに固定したキーでは、このモデルは表示されません。
• 無料版にはアカウント単位の専用の固定上限があります。初回チャージ前は毎分 1 回の成功リクエスト、チャージ後は金額にかかわらず毎分最大 10 回です。アカウントの通常のレート制限とは別にカウントされ、無料の呼び出しで有料の利用枠を消費することはありません。
• 無料版の上限を超えると、Retry-After ヘッダー付きの 429 rate_limit_exceeded が返ります。指定された時間だけ待ってから再試行してください。
• 有料モデル jev-1.13 は、上記の料金で引き続き利用できます。累計チャージ額に応じて増える、アカウントの通常のレート制限が適用されます。利用するにはモデル名だけを変更してください。

リクエスト上限を増やす

チャージ後も jev-1.13-free は無料のままで、毎分最大 10 回の成功リクエストを送信できます。有料モデル jev-1.13 の呼び出しには、アカウント共通の利用枠が適用されます。現在の上限と次のチャージ区分はダッシュボードで確認してください。JEV 専用の別枠ではありません。

残高をチャージしたうえで、有料版を使う場合は model を jev-1.13-free から jev-1.13 に明示的に変更してください。エンドポイント、state、questions はそのまま使用します。入力は 1M トークンあたり $0.042、出力は無料です。チャージしてもモデルは自動で切り替わらず、有料版の呼び出しには十分な残高が必要です。HTTP 429 の場合は Retry-After に従ってください。