決断 API (Decisions API) 概要と活用ガイド

1. API の概要と特徴

決断 API は、テキスト、画像、あるいはその両方を評価し、レスポンス API に比べて 10 倍高速 でタイプ付けされた回答を返すための専用 API です。

主な機能

• 確率取得: 条件が真である確率を算出
• 選択: 与えられた固定集合からの最適な選択肢を選定
• スコアリング: 基準への得点やレベル評価を行う
• 活用シーン:
  • コンテンツの分類
  • リクエストのルーティング
  • アプリケーション内の作業優先順位の決定

現在のステータス

• プレイグラウンド利用で事前実験が可能（コード書写前）
• 一般ベータ版（GA: 一般公開は来週予想）
• サポートモデル:

  gpt-6-luna

  のみ
• 専用エンドポイント:

  /v1/decisions

  (POST リクエスト)

2. リクエスト構造

リクエストは以下の 3 つのフィールド で構成されます。

フィールド定義

model

gpt-6-luna

input

questions

レスポンス構造

• answers

  配列で回答が格納されます。
• 各質問には一意の名前 (

  name

  ) が与えられ、レスポンスでもその名前で回答が識別可能です。

3. 質問タイプの選択

predicate

probability

choice

choice

probabilities

score

score

タイプ選定のヒント

• 離散的なカテゴリ（順序なし、例：部門） →

  choice

  を使用
• 順序のあるレベル（例：深刻度 1〜5 など） →

  score

  を使用
• Yes/No の判定 →

  predicate

  を使用

注意点:

choice

と

score

はどちらも離散的な選択肢に関する確率を返します。一方、独自の JSON スキーマや抽出フィールドが必要な場合は Response API の Structured Outputs、ツール呼び出しが必要なら Function Calling を使用してください。

4. 実装例とレスポンス解説

A. Predicate（述語）質問：画像の損傷検出

製品写真に「ひび」「破損」「凹み」があるかを確認する例です。画像は内联 base64 データ URL である必要があります（外部 URL や

file_id

リクエスト

curl https://api.openai.com/v1/decisions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<JSON
{
  "model": "gpt-6-luna",
  "input": [{
    "role": "user",
    "content": [
      {"type": "input_text", "text": "この写真の製品を点検してください。"},
      {"type": "input_image", "image_url": "data:image/png;base64,$IMAGE_BASE64"}
    ]
  }],
  "questions": [{
    "type": "predicate",
    "name": "visible_damage",
    "instructions": "製品に目に見える損傷（ひび、破損、凹みなど）がありますか？陰影やパッケージの損傷は無視してください。"
  }]
}
JSON

レスポンス示例

{
  "answers": [
    {
      "type": "predicate",
      "name": "visible_damage",
      "probability": 0.92
    }
  ]
}

• probability

  : モデルが「条件が真である」と推定する確率（例：0.92 = 92%）。
• 活用: この閾値に基づき、レビュー対象として写真をマークできます。

B. Choice（選択肢）質問：顧客苦情のルーティング

提供するオプションの中から単一の値を選択させる例です。各選択肢には

value

description

リクエスト

curl https://api.openai.com/v1/decisions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "input": "注文が二重に請求されました。",
    "questions": [{
      "type": "choice",
      "name": "department",
      "instructions": "この苦情を担当する部門はどれですか？",
      "choices": [
        {"value": "billing", "description": "支払い、請求書、および返金に関する問題。"},
        {"value": "technical", "description": "製品の使用方法に関する問題。"},
        {"value": "shipping", "description": "配送および追跡に関する問題。"},
        {"value": "other", "description": "これらのカテゴリ外のリクエスト。"}
      ]
    }]
  }'

レスポンス示例

{
  "answers": [
    {
      "type": "choice",
      "name": "department",
      "choice": "billing",
      "probabilities": [
        {"value": "billing", "probability": 0.95},
        {"value": "technical", "probability": 0.02},
        {"value": "shipping", "probability": 0.01},
        {"value": "other", "probability": 0.02}
      ],
      "confidence": 0.93
    }
  ]
}

• choice

  : 選ばれた値（例：

  "billing"

  ）。

• probabilities

  : 各オプションの確率分布。

• confidence

  : 回答への信頼度。
• ヒント: カテゴリーが全ての入力をカバーしない場合は、フォールバックオプション（例：

  "other"

  ）を含めることを推奨します。

C. Score（スコアリング）質問：問題の深刻さ評価

順序付けられたレベルに対する入力の評価を行います。低水準から高水準順に定義してください。

リクエスト

curl https://api.openai.com/v1/decisions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "input": "Safari ではエクスポートが失敗しますが、Chrome では動作します。",
    "questions": [{
      "type": "score",
      "name": "severity",
      "instructions": "この問題の深刻さはどれくらいですか？",
      "levels": [
        {"label": "Cosmetic（装飾的な）", "description": "外観のみで機能性の損失はありません。"},
        {"label": "Workaround available（代替手段がある）", "description": "タスクは失敗しますが、別の方法で実行可能です。"},
        {"label": "Fully blocked（完全にブロックされている）", "description": "タスクが失敗し、代替手段がありません。"}
      ]
    }]
  }'

レスポンス示例

{
  "answers": [
    {
      "type": "score",
      "name": "severity",
      "score": 1.1,
      "probabilities": [
        {"value": 0, "label": "Cosmetic（装飾的な）", "probability": 0.1},
        {"value": 1, "label": "Workaround available（代替手段がある）", "probability": 0.7},
        {"value": 2, "label": "Fully blocked（完全にブロックされている）", "probability": 0.2}
      ],
      "confidence": 0.55
    }
  ]
}

• score

  : レベルインデックス (0〜) の確率加重平均値。
  • 例：レベル 0(10%), レベル 1(70%), レベル 2(20%) → スコア = $0 \times 0.1 + 1 \times 0.7 + 2 \times 0.2 = \mathbf{1.1}$

• confidence

  : 分布全体の信頼度。
• 活用: 単一カテゴリの選択ではなく、レベル全体にわたる分布の概要を知る際に使用します。

5. ベストプラクティス

• 複数の質問を 1 つのリクエストで実行: 同一

  input

  を共有しながら異なる質問（例：「損傷チェック」＋「カテゴリ分類」）を行えます。各質問は異なるタイプを使用可能です。
• 依存関係のある判断は分割する: 以前の回答に依存する場合は別々のリクエストを送信してください。
  • 例: まず「損傷の有無」を確認し、結果に基づいて「修理カテゴリが必要か」を判断するフローにする。
• 質問の記述は観測基準を中心に:
  • 選択肢には明確な意味を持たせる。
  • スコアレベルは隣接するレベルが明確な境界を持てるように定義する。

6. 回答の解釈と閾値設定

• Predicate: 「条件が真である」推定確率 (

  probability

  ) を返します。
• Choice & Score: 確率分布 (

  probabilities

  ) と独立した信頼度 (

  confidence

  ) を返します。
• 閾値の設定方法: アプリケーションのラベル付き例を学習させ、偽陽性や偽陰性のコストに基づいて最適な閾値を選択してください。

7. プライシングとコンプライアンス

コスト構造

• 基本単価: 入力トークンあたり 100 万文字につき $0.10。
• 課金対象: 入力トークンのみ。
  • キャッシュ読み書き、出力トークン：無料。
• 追加料金:
  • 地域ごとの処理プレミアム
  • 長期コンテキスト入力の価格倍率

適用範囲:

/v1/decisions

エンドポイントにのみ適用されます。他リクエストでは該当モデルの通常価格体系が適用されます。

セキュリティ・準拠

• ゼロデータ保持 (ZDR) のサポートあり。
• HIPAA 利用 を支援（適合する顧客向け）。
• データ所在・処理地域: 米国および欧州（EEA+スイス）でサポート。

8. まとめ：Live API との連携

決断 API は、Live API と組み合わせて以下のワークフローを構築できます。

1. Live API で音声リクエストからアクションを選択。
2. 結果をユーザーに報告する前に、Decisions API で文脈を理解・分類。
3. ユーザーに対して適切な次のステップを案内する。