跳轉到

Decisions API

生成式模型產出的文字是供人閱讀的。當程式碼需要一個可據以分支的判斷時,生成再解析文字的做法會增加延遲,也會讓解析邏輯變得脆弱。

Decisions API 能針對文字、PDF、音訊、圖片與影片,評估具型別的問題。它使用 Gemini Decision 1,並回傳經校準的機率。它不產生任何文字權杖,因此輸出權杖用量永遠為 0。你的程式碼可以直接依據回應進行分支、排序與路由。

How it works

每次呼叫都會送出共用輸入與一組問題對應表,並為每個問題回傳一個具型別的答案。共用輸入可以結合文字、JSON、PDF 文件、音訊、圖片與影片:

每個問題都使用三種問題類型之一:

Question type Goal Returns
Yes/no (noul) 檢查某個陳述是否成立 noul (0.01 to 0.99), confidence
Choice (choice) 從固定清單中選出一個選項 choice, probabilities, confidence
Score (score) 依據有順序的評分等級為輸入評分 score, probabilities, legend, confidence

使用 Gemini Decision 1 開發時,請牢記三個概念:

  • 平行、隔離的評分: 每個問題都在一次前向傳遞中針對共用輸入執行。問題之間彼此看不到對方,當你提出多個問題時,延遲幾乎不會增加。
  • 數值加上信心水準: 答案會告訴你的程式碼適合採取哪個行動。信心水準則告訴你的程式碼,應自動執行該行動,還是升級處理。
  • 原子檢查,在程式碼中組合: 提出狹窄、單一目的的問題。再在程式碼中以一般的 if 陳述式與權重組合這些答案(參見最佳做法)。

Quickstart

需要 SDK 3.2 或更新版本(pip install -U google-genai 或 npm install @google/genai@latest)。傳入模型、共用輸入,以及一組問題對應表。每個問題都需要指定類型(是非題用 noul)與指令:

from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

result = client.decisions.create(
    model="gemini-decision-1",
    input="The blue mug I ordered on Monday arrived cracked on Wednesday.",
    questions={
        "is_damaged": {
            "type": "noul",
            "instructions": "Did the item arrive damaged?",
        },
    },
)

answer = result.answers["is_damaged"]
print(f"P(yes)={answer.noul:.2f} confidence={answer.confidence:.2f}")
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiVersion: "v1beta" });

const result = await ai.decisions.create({
  model: "gemini-decision-1",
  input: "The blue mug I ordered on Monday arrived cracked on Wednesday.",
  questions: {
    is_damaged: {
      type: "noul",
      instructions: "Did the item arrive damaged?",
    },
  },
});

const answer = result.answers?.is_damaged;
if (answer?.type === "noul") {
  console.log(`P(yes)=${answer.noul} confidence=${answer.confidence}`);
}
curl -X POST "https://generativelanguage.googleapis.com/v1beta/decisions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-decision-1",
    "input": "The blue mug I ordered on Monday arrived cracked on Wednesday.",
    "questions": {
      "is_damaged": {
        "type": "noul",
        "instructions": "Did the item arrive damaged?"
      }
    }
  }'

API 會回傳經校準的機率與權杖用量:

{
  "answers": {
    "is_damaged": { "type": "noul", "noul": 0.99, "confidence": 0.99 }
  },
  "usage": {
    "total_input_tokens": 100,
    "input_tokens_by_modality": [{ "modality": "text", "tokens": 100 }],
    "total_output_tokens": 0,
    "total_tokens": 100
  }
}

Question types

Yes or no (noul)

是非題會回傳答案為「是」的經校準機率。當問題本身含義不明確時,請加入判準來說明「是」與「否」分別代表什麼。

from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

result = client.decisions.create(
    model="gemini-decision-1",
    input="Customer returned the sweater because they preferred green over blue.",
    questions={
        "is_defect": {
            "type": "noul",
            "instructions": "Is the customer reporting a product defect?",
            "criteria": {
                "true_description": "The product itself is broken or faulty.",
                "false_description": "Preference, sizing, shipping, or pricing complaint.",
            },
        },
    },
)

print(result.answers["is_defect"].noul)
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiVersion: "v1beta" });

const result = await ai.decisions.create({
  model: "gemini-decision-1",
  input: "Customer returned the sweater because they preferred green over blue.",
  questions: {
    is_defect: {
      type: "noul",
      instructions: "Is the customer reporting a product defect?",
      criteria: {
        true_description: "The product itself is broken or faulty.",
        false_description: "Preference, sizing, shipping, or pricing complaint.",
      },
    },
  },
});

const answer = result.answers?.is_defect;
if (answer?.type === "noul") console.log(answer.noul);
curl -X POST "https://generativelanguage.googleapis.com/v1beta/decisions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-decision-1",
    "input": "Customer returned the sweater because they preferred green over blue.",
    "questions": {
      "is_defect": {
        "type": "noul",
        "instructions": "Is the customer reporting a product defect?",
        "criteria": {
          "true_description": "The product itself is broken or faulty.",
          "false_description": "Preference, sizing, shipping, or pricing complaint."
        }
      }
    }
  }'

答案:

{ "type": "noul", "noul": 0.03, "confidence": 0.97 }

是非題的機率永遠介於 0.01 與 0.99 之間。請將門檻設定在這個範圍內,因為高於 0.99 的檢查永遠不會符合。

Pick one option (choice)

選擇題會為一組固定選項評分,並同時回傳最佳選項,以及每個選項經校準的機率(總和為 1)。Criteria 會將每個選項 ID 對應到其適用時機的說明。當選項 ID 本身已不言自明時,請使用空字串("")。

評估之前,API 會以 UTF-8 位元組順序依字母順序排序選項鍵。在 JSON 要求中改變鍵的順序,不會改變選項的位置;若機率完全相同,則以字母順序最前面的鍵勝出。

from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

result = client.decisions.create(
    model="gemini-decision-1",
    input="I was charged twice for my order.",
    questions={
        "department": {
            "type": "choice",
            "instructions": "Which department should handle this request?",
            "criteria": {
                "billing": "Payments, invoices, and refunds.",
                "technical": "Problems using the product.",
                "shipping": "Delivery and tracking.",
                "other": "Anything outside these categories.",
            },
        },
    },
)

answer = result.answers["department"]
print(answer.choice, answer.confidence, answer.probabilities)
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiVersion: "v1beta" });

const result = await ai.decisions.create({
  model: "gemini-decision-1",
  input: "I was charged twice for my order.",
  questions: {
    department: {
      type: "choice",
      instructions: "Which department should handle this request?",
      criteria: {
        billing: "Payments, invoices, and refunds.",
        technical: "Problems using the product.",
        shipping: "Delivery and tracking.",
        other: "Anything outside these categories.",
      },
    },
  },
});

const answer = result.answers?.department;
if (answer?.type === "choice") {
  console.log(answer.choice, answer.confidence, answer.probabilities);
}
curl -X POST "https://generativelanguage.googleapis.com/v1beta/decisions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-decision-1",
    "input": "I was charged twice for my order.",
    "questions": {
      "department": {
        "type": "choice",
        "instructions": "Which department should handle this request?",
        "criteria": {
          "billing": "Payments, invoices, and refunds.",
          "technical": "Problems using the product.",
          "shipping": "Delivery and tracking.",
          "other": "Anything outside these categories."
        }
      }
    }
  }'

答案:

{
  "type": "choice",
  "choice": "billing",
  "probabilities": { "billing": 0.99, "shipping": 0.004, "other": 0.003, "technical": 0.002 },
  "confidence": 0.99
}

即使沒有任何選項符合,選擇題仍會把機率分配到你的各個選項上。請以信心水準門檻攔截確定性低的輸入、將問題與另一個是非題範圍檢查搭配使用,或加入帶有明確說明的萬用選項,例如 "other"。避免使用 "none_of_the_above" 這類位置型鍵:字母排序會把它排在 "shipping" 與 "technical" 這類鍵的前面,而不是最後。

Rate on a scale (score)

評分題會依據有順序的等級為輸入評分。Criteria 是一個由非空等級說明組成的陣列,依由低至高的順序排列(2 至 255 個等級,多數評分標準建議使用 2 至 10 個),索引從 0 開始。

回傳的分數是等級索引的機率加權平均,因此可能落在等級之間,而 legend 則將每個索引對應回其說明。

from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

result = client.decisions.create(
    model="gemini-decision-1",
    input="Export fails in Safari but works in Chrome.",
    questions={
        "severity": {
            "type": "score",
            "instructions": "How severe is this issue for the user?",
            "criteria": [
                "Cosmetic: appearance only, no lost functionality.",
                "Workaround available: a task fails, but another way works.",
                "Fully blocked: a task fails with no workaround.",
            ],
        },
    },
)

answer = result.answers["severity"]
print(answer.score, answer.confidence, answer.probabilities)
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiVersion: "v1beta" });

const result = await ai.decisions.create({
  model: "gemini-decision-1",
  input: "Export fails in Safari but works in Chrome.",
  questions: {
    severity: {
      type: "score",
      instructions: "How severe is this issue for the user?",
      criteria: [
        "Cosmetic: appearance only, no lost functionality.",
        "Workaround available: a task fails, but another way works.",
        "Fully blocked: a task fails with no workaround.",
      ],
    },
  },
});

const answer = result.answers?.severity;
if (answer?.type === "score") {
  console.log(answer.score, answer.confidence, answer.probabilities);
}
curl -X POST "https://generativelanguage.googleapis.com/v1beta/decisions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-decision-1",
    "input": "Export fails in Safari but works in Chrome.",
    "questions": {
      "severity": {
        "type": "score",
        "instructions": "How severe is this issue for the user?",
        "criteria": [
          "Cosmetic: appearance only, no lost functionality.",
          "Workaround available: a task fails, but another way works.",
          "Fully blocked: a task fails with no workaround."
        ]
      }
    }
  }'

答案:

{
  "type": "score",
  "score": 1.12,
  "legend": {
    "0": "Cosmetic: appearance only, no lost functionality.",
    "1": "Workaround available: a task fails, but another way works.",
    "2": "Fully blocked: a task fails with no workaround."
  },
  "probabilities": { "0": 0.03, "1": 0.83, "2": 0.15 },
  "confidence": 0.83
}

由於不同的機率分布可能產生相同的期望值(此處為 1.12,略高於等級 1),當輸入可能橫跨多個等級時,請連同分數一併檢查各等級的機率與信心水準。

你可以用分數依評分標準門檻對輸入排序,或篩選候選結果。當程式碼需要一個離散等級時,請選取機率最高的項目:

level = max(answer.probabilities, key=answer.probabilities.get)  # "1"
print(answer.legend[level])  # "Workaround available: ..."

若要比較等級數量不同的量表,請將分數除以最高等級索引,將其正規化到 0 與 1 之間。

Ask multiple questions

將針對同一輸入的獨立問題放在同一個要求中。無論你提出多少問題,共用輸入在每個要求中只計算一次(每個問題只增加其自身的指令與判準),而且問題類型可以混合使用。這個範例利用訂單資料與顧客訊息來路由支援工單。

import json
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

order = {"order": {"id": "8821", "item": "headphones", "price_usd": 240}, "tier": "Gold"}
message = {"message": "Audio cuts out on the left earcup. Fix it today or I cancel my membership."}

result = client.decisions.create(
    model="gemini-decision-1",
    input=[
        {"type": "text", "text": json.dumps(order) + "\n"},
        {"type": "text", "text": json.dumps(message)},
    ],
    questions={
        "is_defect": {
            "type": "noul",
            "instructions": "Does `message` describe a hardware defect?",
        },
        "next_action": {
            "type": "choice",
            "instructions": "What is the right resolution given `tier` and `order`?",
            "criteria": {
                "instant_refund": "Refund without return. Low value or clear fault.",
                "replacement_shipment": "Ship a replacement. Customer returns the original.",
                "troubleshooting_flow": "The issue may be fixable by the customer.",
                "human_escalation": "",
            },
        },
        "churn_risk": {
            "type": "score",
            "instructions": "How likely is the customer to churn if the issue is not resolved now?",
            "criteria": [
                "No churn signal",
                "Mild frustration",
                "Mentions alternatives",
                "Threatens to cancel",
            ],
        },
    },
)

a = result.answers
if a["is_defect"].noul > 0.9 and a["next_action"].confidence > 0.6:
    action = a["next_action"].choice
else:
    action = "human_escalation"

print(action, a["churn_risk"].score)
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiVersion: "v1beta" });

const order = { order: { id: "8821", item: "headphones", price_usd: 240 }, tier: "Gold" };
const message = { message: "Audio cuts out on the left earcup. Fix it today or I cancel my membership." };

const result = await ai.decisions.create({
  model: "gemini-decision-1",
  input: [
    { type: "text", text: JSON.stringify(order) + "\n" },
    { type: "text", text: JSON.stringify(message) },
  ],
  questions: {
    is_defect: {
      type: "noul",
      instructions: "Does `message` describe a hardware defect?",
    },
    next_action: {
      type: "choice",
      instructions: "What is the right resolution given `tier` and `order`?",
      criteria: {
        instant_refund: "Refund without return. Low value or clear fault.",
        replacement_shipment: "Ship a replacement. Customer returns the original.",
        troubleshooting_flow: "The issue may be fixable by the customer.",
        human_escalation: "",
      },
    },
    churn_risk: {
      type: "score",
      instructions: "How likely is the customer to churn if the issue is not resolved now?",
      criteria: ["No churn signal", "Mild frustration", "Mentions alternatives", "Threatens to cancel"],
    },
  },
});

const { is_defect, next_action, churn_risk } = result.answers ?? {};
let action = "human_escalation";
if (
  is_defect?.type === "noul" && next_action?.type === "choice" &&
  (is_defect.noul ?? 0) > 0.9 && (next_action.confidence ?? 0) > 0.6
) {
  action = next_action.choice ?? action;
}
console.log(action, churn_risk?.type === "score" ? churn_risk.score : undefined);
curl -X POST "https://generativelanguage.googleapis.com/v1beta/decisions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-decision-1",
    "input": [
      { "type": "text", "text": "{\"order\": {\"id\": \"8821\", \"item\": \"headphones\", \"price_usd\": 240}, \"tier\": \"Gold\"}\n" },
      { "type": "text", "text": "{\"message\": \"Audio cuts out on the left earcup. Fix it today or I cancel my membership.\"}" }
    ],
    "questions": {
      "is_defect": {
        "type": "noul",
        "instructions": "Does `message` describe a hardware defect?"
      },
      "next_action": {
        "type": "choice",
        "instructions": "What is the right resolution given `tier` and `order`?",
        "criteria": {
          "instant_refund": "Refund without return. Low value or clear fault.",
          "replacement_shipment": "Ship a replacement. Customer returns the original.",
          "troubleshooting_flow": "The issue may be fixable by the customer.",
          "human_escalation": ""
        }
      },
      "churn_risk": {
        "type": "score",
        "instructions": "How likely is the customer to churn if the issue is not resolved now?",
        "criteria": ["No churn signal", "Mild frustration", "Mentions alternatives", "Threatens to cancel"]
      }
    }
  }'

回應:

{
  "answers": {
    "is_defect": { "type": "noul", "noul": 0.94, "confidence": 0.94 },
    "next_action": {
      "type": "choice",
      "choice": "human_escalation",
      "probabilities": {
        "human_escalation": 0.76,
        "replacement_shipment": 0.18,
        "troubleshooting_flow": 0.04,
        "instant_refund": 0.02
      },
      "confidence": 0.76
    },
    "churn_risk": {
      "type": "score",
      "score": 2.99,
      "legend": {
        "0": "No churn signal",
        "1": "Mild frustration",
        "2": "Mentions alternatives",
        "3": "Threatens to cancel"
      },
      "probabilities": { "0": 0.0, "1": 0.0, "2": 0.01, "3": 0.99 },
      "confidence": 0.99
    }
  },
  "usage": {
    "total_input_tokens": 324,
    "input_tokens_by_modality": [{ "modality": "text", "tokens": 324 }],
    "total_output_tokens": 0,
    "total_tokens": 324
  }
}

有些決策取決於另一個決策,例如只有在物品損壞時才挑選維修類別。你可以在讀取第一個答案後再送出第二個要求,或是在同一個要求中同時提出兩個問題,再忽略不需要的答案即可。

Answers, probabilities, and confidence

每個答案都包含經校準的機率與信心分數:

  • 最佳數值: 二元問題中「是」的機率、選擇題中最可能的選項,或評分題中經機率加權的期望等級。
  • 機率: 在選擇題與評分題答案中,是所有選項或等級的經校準機率對應表(總和為 1)。對於是非題答案,「否」的機率為 1 減去「是」的機率。
  • 信心水準: 最佳答案正確的估計機率(從 0 到 1)。其值等於最佳結果的機率;對於是非題,則為 max(noul, 1 - noul)。

使用答案數值來挑選行動,並以信心水準決定是否自動執行:

answer = result.answers["department"]
if answer.confidence >= 0.7:
    route_to(answer.choice)
else:
    route_to("human_review")

請使用來自你自身流量的已標記範例來設定門檻。權衡誤判為正與誤判為負的成本。

Input

input 欄位接受文字、圖片、音訊、影片與 PDF 文件區塊,使用與 Interactions API 相同的內容區塊結構描述(不支援 tool-call、tool-result 與 thought 區塊):

Input   = string | Content | Content[]
Content = TextContent | ImageContent | AudioContent | VideoContent | DocumentContent
區塊 欄位 支援的 MIME 類型
text text n/a
image data 或 uri、mime_type、選填的 resolution image/png, image/jpeg, image/webp, image/heic, image/heif, image/gif, image/bmp, image/tiff
audio data or uri, mime_type audio/wav, audio/mp3, audio/mpeg, audio/aiff, audio/aac, audio/ogg, audio/flac, audio/m4a, audio/opus, audio/webm, audio/l16, audio/alaw, audio/mulaw
video data 或 uri、mime_type、選填的 resolution video/mp4, video/mpeg, video/mov, video/avi, video/webm, video/wmv, video/x-flv, video/3gpp
document data or uri, mime_type application/pdf
  • 行內資料接受 base64 編碼的位元組(每個要求上限 100 MB,PDF 為 50 MB)。
  • URI 輸入接受 Files API URI(file.uri)以及公開或已簽署的 HTTPS URL(每個外部 URL 上限 15 MB)。
  • 請務必將 MIME 類型設定為真實的檔案格式。API 會拒絕通用的 octet-stream 類型,以及與區塊類型不符的內容。
  • API 會依序串連 input 與 instructions 中相鄰的文字區塊,且不加入分隔符。請在區塊之間自行加入空格或換行(\n)。
  • 輸入不可為空。

Structured data

將 JSON 物件與陣列序列化為字串,並以文字形式傳入,這樣酬載內的鍵就會保持為純資料,而不是內容區塊。在問題指令中,請以鍵路徑參照 JSON 欄位:

state = json.dumps({"customer": {"tier": "Gold"}, "order": {"id": "8821", "age_days": 14}})

Documents (PDF)

以行內 base64 位元組傳入上限 50 MB 的 PDF。對於較大或可重複使用的檔案,請使用 Files API 上傳。模型會一併讀取文字、表格、圖表與頁面版面配置。這個範例檢查發票 PDF 是否含有採購訂單編號,並將其路由到費用類別:

import base64
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

with open("invoice.pdf", "rb") as f:
    pdf_b64 = base64.b64encode(f.read()).decode("utf-8")

result = client.decisions.create(
    model="gemini-decision-1",
    input=[
        {
            "type": "document",
            "data": pdf_b64,
            "mime_type": "application/pdf",
        },
    ],
    questions={
        "has_po_number": {
            "type": "noul",
            "instructions": "Does the invoice include a purchase order (PO) number?",
        },
        "expense_category": {
            "type": "choice",
            "instructions": "Which expense category fits this invoice?",
            "criteria": {
                "cloud_infrastructure": "Servers, GPU compute, hosting, or storage.",
                "software_licenses": "SaaS subscriptions or seat licenses.",
                "travel": "Flights, hotels, meals, or ground transport.",
                "other": "Anything outside these categories.",
            },
        },
    },
)

po = result.answers["has_po_number"]
category = result.answers["expense_category"]
print(po.noul, category.choice, category.confidence)
import { readFileSync } from "node:fs";
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiVersion: "v1beta" });
const pdfB64 = readFileSync("invoice.pdf").toString("base64");

const result = await ai.decisions.create({
  model: "gemini-decision-1",
  input: [
    {
      type: "document",
      data: pdfB64,
      mime_type: "application/pdf",
    },
  ],
  questions: {
    has_po_number: {
      type: "noul",
      instructions: "Does the invoice include a purchase order (PO) number?",
    },
    expense_category: {
      type: "choice",
      instructions: "Which expense category fits this invoice?",
      criteria: {
        cloud_infrastructure: "Servers, GPU compute, hosting, or storage.",
        software_licenses: "SaaS subscriptions or seat licenses.",
        travel: "Flights, hotels, meals, or ground transport.",
        other: "Anything outside these categories.",
      },
    },
  },
});

const po = result.answers?.has_po_number;
const category = result.answers?.expense_category;
if (po?.type === "noul" && category?.type === "choice") {
  console.log(po.noul, category.choice, category.confidence);
}
curl -X POST "https://generativelanguage.googleapis.com/v1beta/decisions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-decision-1",
    "input": [
      { "type": "document", "data": "<BASE64_PDF_DATA>", "mime_type": "application/pdf" }
    ],
    "questions": {
      "has_po_number": {
        "type": "noul",
        "instructions": "Does the invoice include a purchase order (PO) number?"
      },
      "expense_category": {
        "type": "choice",
        "instructions": "Which expense category fits this invoice?",
        "criteria": {
          "cloud_infrastructure": "Servers, GPU compute, hosting, or storage.",
          "software_licenses": "SaaS subscriptions or seat licenses.",
          "travel": "Flights, hotels, meals, or ground transport.",
          "other": "Anything outside these categories."
        }
      }
    }
  }'

Images

將本機圖片位元組以 base64 傳入,或傳入 URI,並設定解析度,在視覺細節與權杖成本之間取捨。這個範例檢查產品照片是否有損壞:

import base64
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

with open("earcup.jpg", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode("utf-8")

result = client.decisions.create(
    model="gemini-decision-1",
    input=[
        {"type": "text", "text": "Customer photo for return request #8821."},
        {
            "type": "image",
            "data": image_b64,
            "mime_type": "image/jpeg",
            "resolution": "low",  # Supported values: "low", "medium", "high", "ultra_high"
        },
    ],
    questions={
        "visible_damage": {
            "type": "noul",
            "instructions": "Does the photo show physical damage to the device? Ignore the packaging.",
        },
    },
)

print(result.answers["visible_damage"].noul)
import { readFileSync } from "node:fs";
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiVersion: "v1beta" });
const imageB64 = readFileSync("earcup.jpg").toString("base64");

const result = await ai.decisions.create({
  model: "gemini-decision-1",
  input: [
    { type: "text", text: "Customer photo for return request #8821." },
    {
      type: "image",
      data: imageB64,
      mime_type: "image/jpeg",
      resolution: "low", // Supported values: "low", "medium", "high", "ultra_high"
    },
  ],
  questions: {
    visible_damage: {
      type: "noul",
      instructions: "Does the photo show physical damage to the device? Ignore the packaging.",
    },
  },
});

const answer = result.answers?.visible_damage;
if (answer?.type === "noul") console.log(answer.noul);
curl -X POST "https://generativelanguage.googleapis.com/v1beta/decisions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-decision-1",
    "input": [
      { "type": "text", "text": "Customer photo for return request #8821." },
      { "type": "image", "data": "<BASE64_IMAGE_DATA>", "mime_type": "image/jpeg", "resolution": "low" }
    ],
    "questions": {
      "visible_damage": {
        "type": "noul",
        "instructions": "Does the photo show physical damage to the device? Ignore the packaging."
      }
    }
  }'

Audio

傳入公開或已簽署的 HTTPS URL、使用 Files API 上傳本機錄音,或送出行內 base64 位元組。模型無需額外的轉錄步驟,即可評估說話內容、節奏與語調,因此適合用於通話分流、品質保證與語音評估。

這個範例檢查一段演講錄音的主題,並為講者的表現評分:

from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

result = client.decisions.create(
    model="gemini-decision-1",
    input=[
        {
            "type": "audio",
            "uri": "https://storage.googleapis.com/generativeai-downloads/audio/rehearsing.wav",
            "mime_type": "audio/wav",
        },
    ],
    questions={
        "mentions_launch": {
            "type": "noul",
            "instructions": "Is the speaker talking about a product campaign launch?",
        },
        "delivery": {
            "type": "score",
            "instructions": "How fluent and prepared does the speaker sound?",
            "criteria": [
                "Hesitant, searching for notes, or self-correcting.",
                "Mostly steady with minor pauses.",
                "Polished, fluent, and confident throughout.",
            ],
        },
    },
)

print(result.answers["mentions_launch"].noul, result.answers["delivery"].score)
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiVersion: "v1beta" });

const result = await ai.decisions.create({
  model: "gemini-decision-1",
  input: [
    {
      type: "audio",
      uri: "https://storage.googleapis.com/generativeai-downloads/audio/rehearsing.wav",
      mime_type: "audio/wav",
    },
  ],
  questions: {
    mentions_launch: {
      type: "noul",
      instructions: "Is the speaker talking about a product campaign launch?",
    },
    delivery: {
      type: "score",
      instructions: "How fluent and prepared does the speaker sound?",
      criteria: [
        "Hesitant, searching for notes, or self-correcting.",
        "Mostly steady with minor pauses.",
        "Polished, fluent, and confident throughout.",
      ],
    },
  },
});

const launch = result.answers?.mentions_launch;
const delivery = result.answers?.delivery;
if (launch?.type === "noul" && delivery?.type === "score") {
  console.log(launch.noul, delivery.score);
}
curl -X POST "https://generativelanguage.googleapis.com/v1beta/decisions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-decision-1",
    "input": [
      {
        "type": "audio",
        "uri": "https://storage.googleapis.com/generativeai-downloads/audio/rehearsing.wav",
        "mime_type": "audio/wav"
      }
    ],
    "questions": {
      "mentions_launch": {
        "type": "noul",
        "instructions": "Is the speaker talking about a product campaign launch?"
      },
      "delivery": {
        "type": "score",
        "instructions": "How fluent and prepared does the speaker sound?",
        "criteria": [
          "Hesitant, searching for notes, or self-correcting.",
          "Mostly steady with minor pauses.",
          "Polished, fluent, and confident throughout."
        ]
      }
    }
  }'

對於大於 15 MB 的本機檔案或錄音,請使用 Files API 上傳一次,再傳入回傳的 URI(相同模式也適用於 PDF、圖片與影片):

uploaded = client.files.upload(file="support_call.wav")
audio_block = {"type": "audio", "uri": uploaded.uri, "mime_type": uploaded.mime_type}

Video

透過 Files API、公開或已簽署的 HTTPS URL,或行內 base64 位元組傳入影片。當不需要精細的視覺細節時,請將解析度設為 low。

這個範例以低解析度檢查一段 MP4 影片片段:

from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

result = client.decisions.create(
    model="gemini-decision-1",
    input=[
        {
            "type": "video",
            "uri": "https://storage.googleapis.com/generativeai-downloads/videos/ForBiggerBlazes.mp4",
            "mime_type": "video/mp4",
            "resolution": "low",
        },
    ],
    questions={
        "shows_fire": {
            "type": "noul",
            "instructions": "Does the video show fire or flames?",
        },
    },
)

print(result.answers["shows_fire"].noul)
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiVersion: "v1beta" });

const result = await ai.decisions.create({
  model: "gemini-decision-1",
  input: [
    {
      type: "video",
      uri: "https://storage.googleapis.com/generativeai-downloads/videos/ForBiggerBlazes.mp4",
      mime_type: "video/mp4",
      resolution: "low",
    },
  ],
  questions: {
    shows_fire: {
      type: "noul",
      instructions: "Does the video show fire or flames?",
    },
  },
});

const answer = result.answers?.shows_fire;
if (answer?.type === "noul") console.log(answer.noul);
curl -X POST "https://generativelanguage.googleapis.com/v1beta/decisions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-decision-1",
    "input": [
      {
        "type": "video",
        "uri": "https://storage.googleapis.com/generativeai-downloads/videos/ForBiggerBlazes.mp4",
        "mime_type": "video/mp4",
        "resolution": "low"
      }
    ],
    "questions": {
      "shows_fire": {
        "type": "noul",
        "instructions": "Does the video show fire or flames?"
      }
    }
  }'

Media resolution

在圖片與影片區塊上設定媒體解析度(low、medium、high 或 ultra_high),以控制權杖成本與視覺細節。超高解析度僅適用於圖片;音訊與文件區塊不使用解析度設定。

Best practices

  • 讓每個問題都聚焦於單一決策或評分標準。當判準明確時,複雜的評分標準可以在一個問題中處理;或者,你也可以將獨立檢查拆成同一個要求中的多個問題,再在程式碼中組合答案。
  • 在指令中寫出完整的問題。模型永遠看不到問題鍵或你的變數名稱。
  • 為每個選擇選項與評分等級提供簡短說明。讓相鄰的評分等級有清楚區別,並保持評分量表為線性。由於分數是陣列索引(0、1、2 等)的平均值,像 1、10、100、1000 這類指數型量表會扭曲期望值。
  • 預先規劃不符合任何選擇選項的輸入。在依據最佳選項行動前先檢查信心水準,或將選擇題與是非題範圍檢查搭配使用,例如「這則訊息是否與訂單有關?」。若你加入萬用選項,請使用 "other" 這類非位置型鍵,而不是 "none_of_the_above",因為 API 會依字母順序排序選項鍵。
  • 優先使用正向表述。詢問「等級是否為 Gold?」,並在程式碼中以 1 減去「是」的機率,而不是詢問「等級是否不是 Gold?」這類否定問題。
  • 只送出問題所需的欄位。無關內容會降低準確度。
  • 在程式碼中比較數字、日期與時間長度,再將結果或具名分組傳入輸入中。
  • 將輸入視為不可信任。使用者提供的文字可能為自身的分類辯護。請寫出明確的判準、以對抗性範例測試,並對付款等高風險行動保留人工或第二道檢查。

Decisions API or structured output

當你需要在封閉式結果上取得經校準的機率時,請使用 Decisions API:

  • 將要求路由到模型、佇列、代理或工具。
  • 一次針對多條政策規則檢查輸入與輸出。
  • 決定代理需要哪些工具,或是否應壓縮、升級或停止。
  • 依據評分標準篩選、評分或排序候選結果。
  • 即時回應 UI 狀態、音訊或影片畫面。
當你需要以下功能時,使用 Decisions API 當你需要以下功能時,使用 Interactions API
是非題機率、從固定集合中選出一個選項,或在固定量表上評分 生成的文字、摘要或說明
可設定門檻的經校準機率 遵循你自訂 JSON 結構描述的擷取值或物件(參見 Structured outputs)
在一次呼叫中針對同一輸入進行多項獨立檢查 帶有引數的工具呼叫
低延遲且零輸出權杖成本 多步驟推理

Request and response reference

欄位 類型 必填 說明
model string yes 模型 ID:gemini-decision-1。參見 Gemini Decision 1。
input string, Content, or Content[] yes 所有問題的共用上下文(文字、圖片、音訊、影片或 PDF 文件)。參見 Input。
questions map of string to Question yes 1 至 1,000 個問題。鍵由你自行選擇([A-Za-z0-9_-]+,上限 64 個字元)。答案會以相同的鍵回傳。

每個問題都有:

欄位 類型 必填 說明
type noul, choice, or score yes 問題類型。
instructions string, TextContent, or TextContent[] yes 要針對輸入評估的問題。僅限文字。
criteria depends on type choice and score: yes. noul: no. 可能的答案。參見 Question types。

API 會針對共用輸入獨立評估每個問題。問題之間彼此看不到對方,新增或移除一個問題不會改變其他答案。模型永遠看不到問題鍵,因此請在 instructions 欄位中寫出完整的問題。

回應包含:

欄位 類型 說明
answers map of string to Answer 每個問題一個答案,使用與 questions 相同的鍵。每個答案的類型都與其問題相符。
usage Usage 依模態區分的輸入權杖數量(文字、圖片與音訊,其中影片畫面與 PDF 頁面圖片計為圖片權杖),以及 0 個輸出權杖。僅輸入權杖計費;參見 Pricing。

當輸入安全篩選器封鎖要求時,API 會回傳 HTTP 400 Bad Request 錯誤,而不是 answers。JSON error 物件包含 message 與 code(safety、prohibited_content、blocklist、 image_safety 或 content_blocked):

{
  "error": {
    "code": "safety",
    "message": "Request blocked due to safety violations (harmful content). Please modify your input and retry."
  }
}

Limits

限制 值
每個要求的問題數 1 至 1,000(受 262,144 個權杖的上下文視窗限制)
每個選擇題的選項數 2 至 255
每個評分題的等級數 2 至 255 個非空字串(多數評分標準建議 2 至 10 個)
問題鍵 1 至 64 個 ASCII 字元,符合 [A-Za-z0-9_-]+
選項鍵 1 至 128 個字元(上限 512 個 UTF-8 位元組)。允許內部 ASCII 空格。不允許開頭或結尾空格、控制字元與非 ASCII 空格。
上下文視窗 共用輸入與所有問題合計 262,144 個權杖
JSON 巢狀深度 100 層
每個要求的媒體數 與 Interactions API 相同
問題指令 僅限文字

當要求超過限制或未通過鍵驗證時,API 會回傳 HTTP 400,並附上指出你所超過規則的錯誤訊息。

Limitations

  • 僅在 Gemini Developer API(v1beta)上搭配 Gemini Decision 1 提供。
  • 問題指令僅接受文字。不支援在問題中放入媒體。
  • Decisions API 不支援 YouTube URL 或直接的 Cloud Storage (gs://)URI。請使用 Files API URI、公開或已簽署的 HTTPS URL,或行內 base64 位元組傳入媒體。
  • 不支援將對話記錄、thought 與 tool-call 區塊作為輸入區塊。請將多輪上下文序列化為文字。
  • Decisions API 不支援上下文快取、 Batch API,以及 Flex 或 Priority 推論。跨要求重複的輸入會完整計算。

What's next