# Decisions API

生成模型生成文本供人们阅读。当您的代码需要判断分支时，生成和解析文本会增加延迟和脆弱的解析逻辑。

Decisions API 评估文本、PDF、音频、图像和视频中键入的问题。它使用 [Gemini Decision 1](/docs/models/gemini-decision-1) 并返回校准概率。它生成零文本 token，因此输出 token 用法始终为 0. 您的代码可以直接对响应进行分支、排序和路由。

## 它是如何运作的  {% #how-it-works %}

每次呼叫都会发送 [共享输入](/docs/decisions-api#input) 和问题地图，并为每个问题返回一个键入的答案。共享输入可以组合文本、JSON、 [PDF文档](/docs/decisions-api#documents), [音频](/docs/decisions-api#audio), [图片](/docs/decisions-api#media), 和 [视频](/docs/decisions-api#video):

![](https://www.gstatic.com/cloud-cms/55bb56725305bef6dd99ace3e16515c1.png)

每个问题都使用三个之一 [问题类型](/docs/decisions-api#question-types):

| 问题类型                                       | 目标               | 退货                                               |
| ------------------------------------------ | ---------------- | ------------------------------------------------ |
| [是/否（`noul`)](/docs/decisions-api#noul)    | 检查语句是否成立         | `noul` （0.01 至 0.99）， `confidence`               |
| [选择（`choice`)](/docs/decisions-api#choice) | 从固定列表中选择一个选项     | `choice`, `probabilities`, `confidence`          |
| [分数（`score`)](/docs/decisions-api#score)   | 根据有序的标题级别对输入进行评分 | `score`, `probabilities`, `legend`, `confidence` |

使用 Gemini Decision 1 构建时请记住三个想法：

* **并行、孤立评分：** 每个问题都与一次前向传播中的共享输入有关。问题无法看到彼此，并且当您 [问多个问题](/docs/decisions-api#multiple-questions).
* **价值加信心：** 答案告诉您的代码适合什么操作。 [信心](/docs/decisions-api#confidence) 告诉您的代码是自动运行还是升级。
* **原子检查，由代码组成：** 提出狭隘、单一目的的问题。将答案与普通答案结合起来 `if` 代码中的语句和权重（参见 [最佳实践](/docs/decisions-api#best-practices)).

## 快速入门  {% #quickstart %}

需要 SDK 3.2 或更高版本（`pip install -U google-genai` 或 `npm install @google/genai@latest`）。传递模型、共享输入和问题图。每个问题都需要一个类型 ([`noul`](/docs/decisions-api#noul) 是/否）和说明：

{% tabs %}
{% tab filename="decisions.py" label="Python" %}
```python
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}")
```
{% /tab %}

{% tab filename="decisions.mjs" label="JavaScript" %}
```javascript
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}`);
}
```
{% /tab %}

{% tab filename="decisions.sh" label="REST" %}
```bash
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?"
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

API 返回校准概率和 token 用法：

```json
{
  "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 %}

### 是或否（noul）  {% #noul %}

是/否问题返回答案为“是”的校准概率。当问题本身不明确时，添加标准来定义“是”和“否”的含义。

{% tabs %}
{% tab filename="decisions.py" label="Python" %}
```python
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)
```
{% /tab %}

{% tab filename="decisions.mjs" label="JavaScript" %}
```javascript
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);
```
{% /tab %}

{% tab filename="decisions.sh" label="REST" %}
```bash
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."
        }
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

答：

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

{% callout type="note" %}
是/否概率始终落在 0.01 和 0.99. 之间，在该范围内设置阈值，因为高于 0.99 的检查永远不会匹配。
{% /callout %}

### 选择一个选项（选择）  {% #choice %}

选择问题对一组固定的选项进行评分，并返回顶部选项和每个选项的校准概率（总和为 1）。 Criteria 将每个选项 ID 映射到其适用时间的描述。使用空字符串 (`""`) 当选项 ID 不言自明时。

在评估之前，API 按 UTF-8 字节顺序的字母顺序对选项键进行排序。更改 JSON 请求中的键顺序不会更改选项位置，并且确切的概率关系会破坏按字母顺序排列的第一个键。

{% tabs %}
{% tab filename="decisions.py" label="Python" %}
```python
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)
```
{% /tab %}

{% tab filename="decisions.mjs" label="JavaScript" %}
```javascript
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);
}
```
{% /tab %}

{% tab filename="decisions.sh" label="REST" %}
```bash
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."
        }
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

答：

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

{% callout type="note" %}
选择题总是将概率分配给你的选项，即使没有一个适合。捕获低确定性输入的置信度阈值，将问题与单独的是/否范围检查配对，或添加一个包罗万象的选项，例如带有明确描述的“其他”。避免使用“none_of_the_above”之类的位置键：按字母顺序排序会将其放在“shipping”和“technical”等键之前，而不是最后。
{% /callout %}

### 评分（分数）  {% #score %}

分数问题对有序级别的输入进行评分。 Criteria 是一组非空级别描述，按从最低到最高的顺序排列（2 到 255 级别，对于大多数评分标准建议使用 2 到 10），索引从 0. 开始

返回的分数是级别索引的概率加权平均值，因此它可以落在级别之间，并且图例将每个索引映射回其描述。

{% tabs %}
{% tab filename="decisions.py" label="Python" %}
```python
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)
```
{% /tab %}

{% tab filename="decisions.mjs" label="JavaScript" %}
```javascript
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);
}
```
{% /tab %}

{% tab filename="decisions.sh" label="REST" %}
```bash
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."
        ]
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

答：

```json
{
  "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 之上），因此当输入可以跨级别拆分时，请检查每级别的概率和置信度以及分数。

使用分数对输入进行排名或根据评分标准阈值筛选候选结果。当您的代码需要离散级别时，请选择概率最高的条目：

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

要比较具有不同级别数的量表，请将分数除以最高级别指数，以在 0 和 1. 之间进行归一化

## 提出多个问题  {% #multiple-questions %}

在一个请求中提出关于同一输入的独立问题。无论您提出多少问题（每个问题仅添加自己的说明和标准），每个请求共享输入都会计数一次，并且问题类型可以混合。此示例使用订单数据和客户消息路由支持票证。

{% tabs %}
{% tab filename="decisions.py" label="Python" %}
```python
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)
```
{% /tab %}

{% tab filename="decisions.mjs" label="JavaScript" %}
```javascript
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);
```
{% /tab %}

{% tab filename="decisions.sh" label="REST" %}
```bash
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"]
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

回应：

```json
{
  "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
  }
}
```

有些决定取决于另一个决定，例如仅在物品损坏时才选择维修类别。阅读第一个答案后发送第二个请求，或者在一个请求中提出两个问题并忽略您不需要的答案。

## 答案、概率和置信度  {% #confidence %}

每个答案都包含校准概率和置信度分数：

* **最高值：** 二元问题的“是”概率、选择问题的最有可能选项或分数问题的概率加权预期水平。
* **概率：** 关于选择和评分答案，所有选项或级别的校准概率图（总和为 1）。对于是/否答案，“否”的概率是 1 减去“是”的概率。
* **信心：** 最高答案正确的估计概率（从 0 到 1）。等于最高结果的概率，或者 `max(noul, 1 - noul)` 对于是/否问题。

使用答案值来选择操作和置信度来决定是否自动运行它：

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

{% callout type="note" %}
使用您自己的流量中的标记示例设置阈值。权衡误报和漏报的成本。
{% /callout %}

## 输入  {% #input %}

输入字段使用与输入字段相同的内容块模式接受文本、图像、音频、视频和 PDF 文档块。 [Interactions API](/docs/interactions-overview) （不支持工具调用、工具结果和思维块）：

```none
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` 或 `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` 或 `uri`, `mime_type`                  | `application/pdf`                                                                                                                                                               |

* 内联数据接受 base64 编码字节（每个请求最多 100 MB，对于 PDF 最多为 50 MB）。
* URI 输入接受 [Files API](/docs/files) URI (`file.uri`）和公共或签名的 HTTPS URL（每个外部 URL 最多 15 MB）。
* 始终将 MIME 类型设置为真实文件格式。 API 拒绝通用八位字节流类型和与块类型不匹配的内容。
* API 连接相邻的文本块 `input` 和 `instructions` 没有分隔符的顺序。包含您自己的空格或换行符 (`\n`) 块之间。
* 输入不能为空。

### 结构化数据  {% #structured-data %}

将 JSON 对象和数组序列化为字符串并将它们作为文本传递，以便负载中的键保持纯数据而不是内容块。在您的问题说明中，通过关键路径引用 JSON 字段：

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

### 文件（PDF）  {% #documents %}

将最多 50 MB 的 PDF 作为内联 base64 字节传递。对于较大或可重复使用的文件，请使用 [Files API](/docs/files)。该模型一起读取文本、表格、图表和页面布局。此示例检查发票 PDF 中的采购订单编号并将其路由到费用类别：

{% tabs %}
{% tab filename="decisions.py" label="Python" %}
```python
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)
```
{% /tab %}

{% tab filename="decisions.mjs" label="JavaScript" %}
```javascript
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);
}
```
{% /tab %}

{% tab filename="decisions.sh" label="REST" %}
```bash
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."
        }
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

### 图片  {% #media %}

将本地图像字节作为 base64 传递或传递 URI，并设置分辨率以根据 token 成本交换视觉细节。此示例检查产品照片是否有损坏：

{% tabs %}
{% tab filename="decisions.py" label="Python" %}
```python
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)
```
{% /tab %}

{% tab filename="decisions.mjs" label="JavaScript" %}
```javascript
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);
```
{% /tab %}

{% tab filename="decisions.sh" label="REST" %}
```bash
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."
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

### 音频  {% #audio %}

传递公共或签名的 HTTPS URL，使用以下命令上传本地录音 [Files API](/docs/files)，或发送内联 base64 字节。该模型无需单独的转录步骤即可评估口语、节奏和语气，使其适用于呼叫分类、质量检查和语音评估。

此示例检查语音录音的主题并对演讲者的演讲进行评分：

{% tabs %}
{% tab filename="decisions.py" label="Python" %}
```python
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)
```
{% /tab %}

{% tab filename="decisions.mjs" label="JavaScript" %}
```javascript
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);
}
```
{% /tab %}

{% tab filename="decisions.sh" label="REST" %}
```bash
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."
        ]
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

对于大于 15 MB 的本地文件或录音，请使用 [Files API](/docs/files) 并传递返回的 URI（相同的模式适用于 PDF、图像和视频）：

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

### 视频  {% #video %}

通过视频传递 [Files API](/docs/files)、公共或签名的 HTTPS URL 或内联 base64 字节。当不需要精细的视觉细节时，将分辨率设置为低。

此示例检查低分辨率的 MP4 视频剪辑：

{% tabs %}
{% tab filename="decisions.py" label="Python" %}
```python
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)
```
{% /tab %}

{% tab filename="decisions.mjs" label="JavaScript" %}
```javascript
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);
```
{% /tab %}

{% tab filename="decisions.sh" label="REST" %}
```bash
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?"
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

### 媒体分辨率  {% #media-resolution %}

套装 [媒体分辨率](/docs/media-resolution) 控制 token 成本和视觉细节的图像和视频块（低、中、高或超高）。超高分辨率仅适用于图像；音频和文档块不使用分辨率设置。

## 最佳实践  {% #best-practices %}

* 让每个问题集中在一个决定或标题上。当标准明确时，复杂的标题可以在一个问题中发挥作用，或者您可以将独立检查拆分为一个请求中的单独问题，并将答案合并到代码中。
* 在说明中写下完整的问题。该模型永远不会看到问题键或变量名称。
* 为每个选择选项和分数级别提供简短的描述。使相邻的分数水平明显不同，并保持分数尺度线性。由于分数对数组索引（0, 1, 2, 及以上）进行平均，因此 1, 10, 100, 和 1000 等指数比例会扭曲预期值。
* 规划不适合任何选择的输入。在对最上面的选项进行操作之前检查置信度，或者将选择问题与是/否范围检查配对，例如“此消息是关于订单的吗？”。如果添加包罗万象的选项，请使用非位置键，例如“other”而不是“none_of_the_above”，因为 API 按字母顺序对选项键进行排序。
* 更喜欢积极的措辞。问“等级是黄金级吗？”并从代码中的 1 中减去“是”的概率，而不是问诸如“该等级不是黄金级吗？”之类的否定性问题。
* 仅发送问题所需的字段。不相关的内容会降低准确性。
* 比较代码中的数字、日期和持续时间，然后在输入中传递结果或命名存储桶。
* 将输入视为不可信。用户提供的文本可以争论其自己的分类。编写明确的标准，使用对抗性示例进行测试，并对支付等高风险行为进行人工或二次检查。

## Decisions API 或结构化输出  {% #when-to-use %}

当您需要校准封闭式结果的概率时，请使用 Decisions API：

* 将请求路由到模型、队列、智能体或工具。
* 立即根据许多策略规则检查输入和输出。
* 决定智能体需要哪些工具，或者是否压缩、升级或停止。
* 根据标题对候选结果进行过滤、评分或排名。
* 实时响应 UI 状态、音频或视频帧。

| 当您需要时使用 Decisions API   | 使用 [Interactions API](/docs/interactions-overview) 当你需要的时候  |
| ----------------------- | ----------------------------------------------------------- |
| 是/否概率、固定组中的一个选项或固定等级的评级 | 生成的文本、摘要或解释                                                 |
| 您可以设定阈值的校准概率            | 遵循您自己的 JSON 架构的提取值或对象（请参阅 [结构化输出](/docs/structured-output)) |
| 在一次调用中对同一输入进行多次独立检查     | 带参数的工具调用                                                    |
| 低延迟和零输出 token 成本        | 多步推理                                                        |

## 请求和响应参考  {% #request %}

| 领域          | 类型                            | 必填 | 说明                                                                              |
| ----------- | ----------------------------- | -- | ------------------------------------------------------------------------------- |
| `model`     | 字符串                           | 是  | 型号： `gemini-decision-1`。参见 [Gemini Decision 1](/docs/models/gemini-decision-1). |
| `input`     | 字符串， `Content`, 或 `Content[]` | 是  | 所有问题的共享上下文（文本、图像、音频、视频或 PDF 文档）。参见 [输入](/docs/decisions-api#input).             |
| `questions` | 字符串映射到 `Question`             | 是  | 1 到 1,000 问题。您选择按键 (`[A-Za-z0-9_-]+`，最多 64 个字符）。答案会以相同的键返回。                     |

每个问题都有：

| 领域             | 类型                                    | 必填            | 说明                                                   |
| -------------- | ------------------------------------- | ------------- | ---------------------------------------------------- |
| `type`         | `noul`, `choice`, 或 `score`           | 是             | 问题类型。                                                |
| `instructions` | 字符串， `TextContent`, 或 `TextContent[]` | 是             | 根据输入评估的问题。仅文本。                                       |
| `criteria`     | 取决于类型                                 | 选择及评分：是。努尔：不。 | 可能的答案。参见 [问题类型](/docs/decisions-api#question-types). |

API 根据共享输入独立评估每个问题。问题不能互相看到，添加或删除一个问题不会改变其他答案。该模型永远不会看到问题键，因此请在说明字段中写入完整的问题。

响应包含：

| 领域        | 类型              | 说明                                                                                                               |
| --------- | --------------- | ---------------------------------------------------------------------------------------------------------------- |
| `answers` | 字符串映射到 `Answer` | 每个问题一个答案，使用与 `questions`。每个答案都有一个与其问题相匹配的类型。                                                                     |
| `usage`   | `Usage`         | 输入 token 按模态计数（文本、图像和音频，视频帧和 PDF 页面图像计为图像 token），0 输出 token。仅输入token进行计费；看到 [价格](/docs/pricing#gemini-decision). |

当输入安全过滤器阻止请求时，API 返回 HTTP `400 Bad Request` 错误而不是 `answers`。 JSON `error` 对象包括一个 `message` 和一个 `code` (`safety`, `prohibited_content`, `blocklist`, `image_safety`, 或 `content_blocked`):

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

## 限制  {% #limits %}

| 限制        | 价值                                                                      |
| --------- | ----------------------------------------------------------------------- |
| 每个请求的问题   | 1 至 1,000（以 262,144-token 上下文窗口为界）                                      |
| 每个选择题的选项  | 2 至 255                                                                 |
| 每个分数问题的级别 | 2 到 255 非空字符串（2 到 10 建议用于大多数评分标准）                                       |
| 问题键       | 1 到 64 ASCII 字符匹配 `[A-Za-z0-9_-]+`                                      |
| 选项键       | 1 到 128 字符（最多 512 UTF-8 字节）。允许内部 ASCII 空格。不允许使用前导或尾随空格、控制字符和非 ASCII 空格。 |
| 上下文窗口     | 262,144 token 跨共享输入和所有问题                                                |
| JSON 嵌套深度 | 100 级别                                                                  |
| 每个请求的媒体   | 与 [Interactions API](/docs/interactions-overview)                       |
| 问题说明      | 仅文本                                                                     |

当请求超出限制或密钥验证失败时，API 将返回 HTTP 400，并包含一条错误消息，指出您超出的规则。

## 限制  {% #limitations %}

* 可在 Gemini 开发者 API (v1beta) 上使用 [Gemini Decision 1](/docs/models/gemini-decision-1) 仅。
* 问题说明仅接受文本。不支持问题内的媒体。
* Decisions API 不支持 YouTube URL 或直接云存储（`gs://`) URI。使用传递媒体 [Files API](/docs/files) URI、公共或签名的 HTTPS URL、或内联 base64 字节。
* 不支持将对话历史记录、思想和工具调用块作为输入块。将多轮上下文序列化为文本。
* Decisions API不支持上下文缓存， [Batch API](/docs/batch-api)，或 Flex 或 Priority 推理。跨请求的重复输入将被完整计数。

## 后续步骤  {% #whats-next %}

* 在自定义文本和媒体上以交互方式测试是/否、选择和评分问题 [决策游乐场](https://aistudio.google.com/apps/f6cbef57-8bad-443a-813f-4d4c8f9750af?fullscreenApplet=true)，然后导出可运行的代码。
* 探索在 Google AI Studio 中使用 Gemini Decision 1 构建的示例应用程序，包括 [上门包裹](https://aistudio.google.com/apps/bdca3fee-8d0a-4663-b30e-73828a55c1e8?fullscreenApplet=true)
  和 [找到动物园管理员](https://aistudio.google.com/apps/b86d2f3b-c1d4-4d44-9198-5303a0cb65c1?fullscreenApplet=true).
* 查看型号规格 [Gemini Decision 1](/docs/models/gemini-decision-1) 模型页面，以及 [价格](/docs/pricing#gemini-decision) 和 [速率限制](/docs/rate-limits#gemini-decision).
* 构建自主工作流程 [托管智能体](/docs/agents) 在 Gemini API 上。
