Decisions API

回答の形は、条件が真である確率、固定の選択肢からの選択、ルーブリックに対するスコアの 3 つです。Responses API と比べて約 10 倍の速さで回答を返します。返された回答は、アプリケーションの中でコンテンツの分類、リクエストの振り分け、作業の優先順位付けに使えます。

レスポンスには answers 配列が含まれます。各質問に一意の name を付けると、API はその名前をレスポンスに返すため、どの回答がどの質問に対応するかを識別できます。

Decisions が返すのは型付きの回答までです。回答に応じた処理は、アプリケーション側で実行します。入力としてファイル、音声、アイテム参照はサポートされていません。

コードを書く前に、Playground で質問と入力を試すこともできます。

• 条件の確率 (predicate): 条件が真である確率を返します。
• **choice**: 指定した選択肢から 1 つの値を選びます。回答には、選ばれた値 (choice)、選択肢ごとの probabilities 配列、confidence フィールドが含まれます。部署のような順序の無いカテゴリに使います。
• **score**: 2〜10 段階の順序付きの levels に照らして入力を評価します。深刻度のような順序のあるレベルに使います。返される score は、0 から始まるレベル番号を確率で重み付けした平均のため、レベルとレベルの間の値になる場合があります。

choice と score はどちらも、離散的な選択肢に対する確率を返します。

• 会話履歴: メッセージと、関数呼び出しやカスタムツールの呼び出し・出力を順に並べて input に渡します。各ツール出力は call_id で対応する呼び出しと結び付けます。
• JSON: input_json のコンテンツパートを使い、JSON のオブジェクトまたは配列を data に入れます。ユーザーメッセージの中で、テキストや画像のパートと並べて使えます。メッセージ内の input_json は user ロールでのみサポートされています。data の中の role や image_url といったキーは通常のデータとして扱われ、メッセージの作成や画像の取得は行われません。
• 画像: base64 のインライン data URL か、公開されている HTTP または HTTPS の URL で渡します。file_id による入力はサポートされていません。
• 質問ごとの画像: 質問の instructions を、input_text と input_image のパートからなる空でない配列にすると、質問ごとに別の画像を渡せます。predicate・choice・score のどの質問でも使えます。

プロンプトキャッシュを使うと、繰り返しのリクエストで共有の input のうち一致する先頭部分を再利用し、割引されたキャッシュ読み取り料金を受けられます。questions の中の内容は、再利用される先頭部分には含まれません。

既定では、共有の input の末尾に暗黙のキャッシュの区切り (breakpoint) が置かれます。再利用する先頭部分は 1,024 トークン以上が必要です。

キャッシュを細かく制御する設定は次のとおりです。

• prompt_cache_key: 呼び出し側が指定したキーで、キャッシュの再利用を分けます。
• prompt_cache_breakpoint: {"mode": "explicit"}: 共有の input のテキストや画像のパートに付けて、区切りの位置を指定します。
• prompt_cache_options.mode を "explicit" にすると、印を付けた区切りだけを使います。このモードで区切りの印が無いリクエストは、プロンプトキャッシュを使いません。質問の instructions の中では区切りはサポートされていません。

キャッシュの読み取りは usage.input_tokens_details.cached_tokens、書き込みは usage.input_tokens_details.cache_write_tokens で確認できます。

組織全体の Decisions のトークン使用量とリクエスト数は、GET /v1/organization/usage/decisions で取得できます。認証には admin API key と api.usage.read 権限を使います。期間と集計の単位 (bucket width) を選び、プロジェクト・API キー・モデルで絞り込みやグループ化ができます。

リクエストは model・input・questions の 3 つの部分で構成されます。

1. POST /v1/decisions にリクエストを送ります。モデルには、現在サポートされている唯一のモデルである gpt-6-luna を指定します。
2. input に、質問に共通する材料を入れます。テキストの文字列か、メッセージ・ツール呼び出し・ツール出力を順に並べた配列を使います。
3. questions に評価したい内容を指定します。各質問の種類、指示 (instructions)、許可する選択肢やスコアのレベルを含めます。