POST /v1/systemone
判定エンドポイントの完全リファレンス:model/state/questions フィールド、3 つの問題型(noul、choice、score)、処理セマンティクス、レスポンス構造と上流エラーのパススルー。
リクエストフィールド
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| model | string | 必須 | GET /v1/models の戻り値のモデル名。typesafe/jev-latest など。旧裸名(jev-latest、jev-1.13.0)もエイリアス正規化で呼び出し可能。 |
| state | string / object / array | 必須 | 評価対象の内容。形式は自由:質問、チケット、商品レコードなど——questions から参照できれば何でも可。 |
| questions | object | 必須 | {問題id: 問題定義} のマップ。1 つ以上必須。問題 id はレスポンスにそのまま返ります。 |
| (その他) | any | いいえ | 未知フィールドは上流へそのままパススルー(前方互換性を維持)。 |
{
"model": "typesafe/jev-latest",
"state": "User asks: can I get a refund for order #1024?",
"questions": {
"refund": {"type": "noul", "instructions": "Is this a refund request?"},
"urgency": {
"type": "score",
"instructions": "How urgent is this?",
"criteria": ["low", "normal", "high"]
}
}
}問題型の定義
| 型 | type | 必須フィールド | 戻り値 |
|---|---|---|---|
| Yes/No | noul | — | 「はい」の確率 [0,1]。criteria.true/false の説明は任意。 |
| 単一選択 | choice | criteria | 選択肢名→説明のマップ(255 項まで、説明は null 可)。選択結果と選択肢ごとの probabilities を返す。 |
| 順序評価 | score | criteria | 2〜10 段階の順序配列。レベル間を補間した値を返す。 |
すべての問題型で instructions は任意で、文字列・オブジェクト・配列を受け付けます。画像は assets で添付できます——画像とマルチモーダル資産 を参照。
処理セマンティクス(順序)
- 1. リクエストサイズ制限(メディア 1 ファイル 50 MB、合計:multipart 60 MB / JSON 70 MB)→ 413
- 2. 最小構造チェック——model/state/questions 不足 → 422
- 3. モデル ホワイトリスト(エイリアス正規化後に判定)——不明モデル → 404、転送しない
- 4. キー単位レート制限(既定 600 RPM / 4,500,000 TPM)→ 429
- 5. 残高事前チェック——残高 0 以下 → 402(今回の呼び出しはマイナス決済を 1 回許容し、次回遮断)
- 6. 上流転送とフェイルオーバー:最大 3 組の「チャネル+キー」を試行(401 はキー自動無効化、429 はクールダウン、5xx/ネットワークエラーは切替)
- 7. 200 のみ課金:入力 token × 入力単価 + 出力 token × 出力単価を上流 usage に基づき正確に精算。失敗呼び出しは無料
- 8. 全呼び出し(成否問わず)をログ化し、request_id をレスポンスヘッダーで返す
成功レスポンス
200 本体は上流レスポンスの無変更パススルー(未知フィールドを含む)。usage は課金メーターで、input_tokens / output_tokens / cost(上流が返す場合のみ)のみ公開されます。
{
"model": "typesafe/jev-latest",
"answers": {
"refund": {
"type": "noul",
"noul": 0.97,
"confidence": 0.93
},
"urgency": {
"type": "score",
"score": 1.4,
"confidence": 0.88
}
},
"usage": {"input_tokens": 1234, "output_tokens": 0}
}レスポンスヘッダー
すべてのレスポンス(成否問わず)に同値の X-Request-Id と x-typesafe-request-id があります——照合とサポート問い合わせに使用。公式 SDK は resp.request_id として公開します。
上流エラーのパススルー
上流の検証失敗(400 / 404 / 413 / 422)は無変更でパススルー——本体は上流のエラー JSON でありゲートウェイのエンベロープではありません——課金もされません。その他の失敗は 統一ゲートウェイエラー構造 を使用します。