Gemini 3 隆重登場！如要開始使用 Google 迄今最強大的模型，請參閱開發人員指南。

本頁面由 Cloud Translation API 翻譯而成。

Gemini 3 開發人員指南

Gemini 3 是我們迄今最強大的模型系列，以最先進的推理技術為基礎建構而成。這項產品旨在協助您掌握代理式工作流程、自主編碼和複雜的多模態工作，將任何想法付諸實現。本指南將介紹 Gemini 3 模型系列的主要功能，以及如何充分運用這些功能。

Gemini 3 Pro 預設會使用動態思考功能，根據提示進行推理。如果不需要複雜的推理，可以將模型的思考層級限制為 low，加快回應速度並縮短延遲時間。

Python

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="Find the race condition in this multi-threaded C++ snippet: [code here]",
)

print(response.text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents="Find the race condition in this multi-threaded C++ snippet: [code here]",
  });

  console.log(response.text);
}

run();

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Find the race condition in this multi-threaded C++ snippet: [code here]"}]
    }]
  }'

探索

Gemini 3 Applet 簡介

歡迎瀏覽我們的 Gemini 3 系列應用程式，瞭解模型如何處理進階推理、自主程式設計和複雜的多模態工作。

認識 Gemini 3

Gemini 3 Pro 是新系列的第一個模型。gemini-3-pro-preview 最適合處理複雜工作，這類工作需要廣泛的世界知識，以及跨模式的進階推理能力。

模型 ID	背景期間 (進入 / 離開)	知識截點	定價 (輸入 / 輸出)*
gemini-3-pro-preview	100 萬次 / 6.4 萬次	2025 年 1 月	$2 美元 / $12 美元 (少於 20 萬個權杖) $4 美元 / $18 美元 (超過 20 萬個權杖)

* 價格以每 100 萬個權杖為單位。所列價格為標準文字價格，多模態輸入費率可能有所不同。

如需詳細的速率限制、批次定價和其他資訊，請參閱模型頁面。

Gemini 3 的新 API 功能

Gemini 3 推出全新參數，讓開發人員進一步掌控延遲時間、費用和多模態準確度。

思考程度

thinking_level 參數可控制模型產生回覆前，內部推理過程的最大深度。Gemini 3 會將這些層級視為相對的思考配額，而非嚴格的權杖保證。如未指定 thinking_level，Gemini 3 Pro 預設會使用 high。

low：盡量減少延遲時間和成本。最適合簡單的指令遵循、聊天或高總處理量應用程式
medium：(即將推出)，推出時不支援
high (預設)：盡可能深入推理。模型可能需要較長時間才能產生第一個權杖，但輸出內容會經過更仔細的推論。

媒體解析度

Gemini 3 透過 media_resolution 參數，精細控管多模態視覺處理作業。解析度越高，模型就越能辨識細小文字或細節，但也會增加權杖用量和延遲時間。media_resolution 參數會決定每個輸入圖片或影片影格可分配到的詞元數量上限。

現在可以為個別媒體部分或全域 (透過 generation_config) 設定 media_resolution_low、media_resolution_medium 或 media_resolution_high 解析度。如未指定，模型會根據媒體類型使用最佳預設值。

建議設定

媒體類型	建議設定	最多權杖	使用指南
圖片	`media_resolution_high`	1120	建議用於大多數圖片分析工作，確保最高品質。
PDF	`media_resolution_medium`	560	最適合用於瞭解文件內容，品質通常會在 `medium` 達到飽和。增加至 `high` 很少能改善標準文件的 OCR 結果。
影片 (一般)	`media_resolution_low` (或 `media_resolution_medium`)	70 (每格)	注意：對於影片，`low` 和 `medium` 設定會視為相同 (70 個權杖)，以最佳化情境使用情形。這足以應付大多數的動作辨識和描述工作。
影片 (文字內容較多)	`media_resolution_high`	280 (每格)	只有在用途涉及讀取密集文字 (OCR) 或影片影格中的細微細節時，才需要此功能。

Python

from google import genai
from google.genai import types
import base64

# The media_resolution parameter is currently only available in the v1alpha API version.
client = genai.Client(http_options={'api_version': 'v1alpha'})

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents=[
        types.Content(
            parts=[
                types.Part(text="What is in this image?"),
                types.Part(
                    inline_data=types.Blob(
                        mime_type="image/jpeg",
                        data=base64.b64decode("..."),
                    ),
                    media_resolution={"level": "media_resolution_high"}
                )
            ]
        )
    ]
)

print(response.text)

JavaScript

import { GoogleGenAI } from "@google/genai";

// The media_resolution parameter is currently only available in the v1alpha API version.
const ai = new GoogleGenAI({ apiVersion: "v1alpha" });

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents: [
      {
        parts: [
          { text: "What is in this image?" },
          {
            inlineData: {
              mimeType: "image/jpeg",
              data: "...",
            },
            mediaResolution: {
              level: "media_resolution_high"
            }
          }
        ]
      }
    ]
  });

  console.log(response.text);
}

run();

REST

curl "https://generativelanguage.googleapis.com/v1alpha/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [
        { "text": "What is in this image?" },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "..."
          },
          "mediaResolution": {
            "level": "media_resolution_high"
          }
        }
      ]
    }]
  }'

溫度

對於 Gemini 3，我們強烈建議將溫度參數維持預設值 1.0。

先前的模型通常會調整溫度，以控制創意與決定性，但 Gemini 3 的推理能力已針對預設設定進行最佳化。變更溫度 (設為低於 1.0) 可能會導致非預期的行為，例如迴圈或效能降低，尤其是在複雜的數學或推理工作。

思想簽名

Gemini 3 會使用思維簽章，在 API 呼叫之間維持推理情境。這些簽章是模型內部思考過程的加密表示法。為確保模型維持推理能力，您必須在要求中將這些簽章傳回模型，且簽章內容必須與收到的完全一致：

函式呼叫 (嚴格)：API 會對「目前回合」強制執行嚴格驗證。如果缺少簽章，系統會顯示 400 錯誤。
文字/即時通訊：系統不會嚴格執行驗證，但如果省略簽章，模型推理和回覆品質就會下降。

函式呼叫 (嚴格驗證)

Gemini 生成 functionCall 時，會依據 thoughtSignature 在下一個回合中正確處理工具的輸出內容。「目前回合」包含自上次標準「使用者」text訊息以來，發生的所有「模型」functionCall和「使用者」functionResponse步驟。

單一函式呼叫：functionCall 部分包含簽章。你必須歸還。
平行函式呼叫：清單中只有第一個 functionCall 部分會包含簽章。請務必依原樣退回零件。
多步驟 (循序)：如果模型呼叫工具、收到結果，然後呼叫另一個工具 (在同一回合內)，兩個函式呼叫都會有簽章。您必須退回記錄中所有累積的簽章。

文字和串流

如果是標準即時通訊或文字生成，系統不保證會顯示簽名。

非串流：回應的最終內容部分可能包含 thoughtSignature，但並非一律如此。如果退回其中一個，請務必寄回，以維持最佳成效。
串流：如果系統產生簽章，簽章可能會出現在含有空白文字部分的最後一個區塊。確認串流剖析器會檢查簽章，即使文字欄位空白也一樣。

程式碼範例

多步驟函式呼叫 (循序)

使用者在同一回合中提出需要兩個不同步驟的問題 (查看航班 -> 預訂計程車)。

步驟 1：模型呼叫 Flight Tool。
模型會傳回簽章 <Sig_A>

// Model Response (Turn 1, Step 1)
  {
    "role": "model",
    "parts": [
      {
        "functionCall": { "name": "check_flight", "args": {...} },
        "thoughtSignature": "<Sig_A>" // SAVE THIS
      }
    ]
  }

步驟 2：使用者傳送航班結果
我們必須傳回 <Sig_A>，才能維持模型的思路。

// User Request (Turn 1, Step 2)
[
  { "role": "user", "parts": [{ "text": "Check flight AA100..." }] },
  { 
    "role": "model", 
    "parts": [
      { 
        "functionCall": { "name": "check_flight", "args": {...} }, 
        "thoughtSignature": "<Sig_A>" // REQUIRED
      } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": { "name": "check_flight", "response": {...} } }] }
]

步驟 3：模型呼叫 Taxi Tool
模型透過 <Sig_A> 記住航班延誤資訊，現在決定預約計程車。系統會產生新簽章 <Sig_B>。

// Model Response (Turn 1, Step 3)
{
  "role": "model",
  "parts": [
    {
      "functionCall": { "name": "book_taxi", "args": {...} },
      "thoughtSignature": "<Sig_B>" // SAVE THIS
    }
  ]
}

步驟 4：使用者傳送 Taxi Result
如要完成回合，你必須傳回整個鏈結：<Sig_A> 和 <Sig_B>。

// User Request (Turn 1, Step 4)
[
  // ... previous history ...
  { 
    "role": "model", 
    "parts": [
       { "functionCall": { "name": "check_flight", ... }, "thoughtSignature": "<Sig_A>" } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": {...} }] },
  { 
    "role": "model", 
    "parts": [
       { "functionCall": { "name": "book_taxi", ... }, "thoughtSignature": "<Sig_B>" } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": {...} }] }
]

平行函式呼叫

使用者詢問：「Check the weather in Paris and London.」(查看巴黎和倫敦的天氣)。模型會在一個回覆中傳回兩個函式呼叫。

// User Request (Sending Parallel Results)
[
  {
    "role": "user",
    "parts": [
      { "text": "Check the weather in Paris and London." }
    ]
  },
  {
    "role": "model",
    "parts": [
      // 1. First Function Call has the signature
      {
        "functionCall": { "name": "check_weather", "args": { "city": "Paris" } },
        "thoughtSignature": "<Signature_A>" 
      },
      // 2. Subsequent parallel calls DO NOT have signatures
      {
        "functionCall": { "name": "check_weather", "args": { "city": "London" } }
      } 
    ]
  },
  {
    "role": "user",
    "parts": [
      // 3. Function Responses are grouped together in the next block
      {
        "functionResponse": { "name": "check_weather", "response": { "temp": "15C" } }
      },
      {
        "functionResponse": { "name": "check_weather", "response": { "temp": "12C" } }
      }
    ]
  }
]

文字/情境內推理 (無驗證)

使用者提出的問題需要根據情境推理，但不得使用外部工具。雖然系統不會嚴格驗證簽章，但加入簽章有助於模型保留後續問題的推理鏈。

// User Request (Follow-up question)
[
  { 
    "role": "user", 
    "parts": [{ "text": "What are the risks of this investment?" }] 
  },
  { 
    "role": "model", 
    "parts": [
      {
        "text": "I need to calculate the risk step-by-step. First, I'll look at volatility...",
        "thoughtSignature": "<Signature_C>" // Recommended to include
      }
    ]
  },
  { 
    "role": "user", 
    "parts": [{ "text": "Summarize that in one sentence." }] 
  }
]

從其他機型遷移

如要從其他模型 (例如 Gemini 1.0 Pro) 轉移對話記錄，Gemini 2.5) 或插入非由 Gemini 3 生成的自訂函式呼叫，您將無法取得有效簽章。

如要在這些特定情境中略過嚴格驗證，請在欄位中填入這個特定虛擬字串："thoughtSignature": "context_engineering_is_the_way_to_go"

使用工具產生結構化輸出內容

Gemini 3 可讓您將結構化輸出與內建工具結合使用，包括以 Google 搜尋為基礎、網址內容和程式碼執行。

Python

from google import genai
from google.genai import types
from pydantic import BaseModel, Field
from typing import List

class MatchResult(BaseModel):
    winner: str = Field(description="The name of the winner.")
    final_match_score: str = Field(description="The final match score.")
    scorers: List[str] = Field(description="The name of the scorer.")

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="Search for all details for the latest Euro.",
    config={
        "tools": [
            {"google_search": {}},
            {"url_context": {}}
        ],
        "response_mime_type": "application/json",
        "response_json_schema": MatchResult.model_json_schema(),
    },  
)

result = MatchResult.model_validate_json(response.text)
print(result)

JavaScript

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const ai = new GoogleGenAI({});

const matchSchema = z.object({
  winner: z.string().describe("The name of the winner."),
  final_match_score: z.string().describe("The final score."),
  scorers: z.array(z.string()).describe("The name of the scorer.")
});

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents: "Search for all details for the latest Euro.",
    config: {
      tools: [
        { googleSearch: {} },
        { urlContext: {} }
      ],
      responseMimeType: "application/json",
      responseJsonSchema: zodToJsonSchema(matchSchema),
    },
  });

  const match = matchSchema.parse(JSON.parse(response.text));
  console.log(match);
}

run();

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Search for all details for the latest Euro."}]
    }],
    "tools": [
      {"googleSearch": {}},
      {"urlContext": {}}
    ],
    "generationConfig": {
        "responseMimeType": "application/json",
        "responseJsonSchema": {
            "type": "object",
            "properties": {
                "winner": {"type": "string", "description": "The name of the winner."},
                "final_match_score": {"type": "string", "description": "The final score."},
                "scorers": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "The name of the scorer."
                }
            },
            "required": ["winner", "final_match_score", "scorers"]
        }
    }
  }'

從 Gemini 2.5 遷移

Gemini 3 是我們目前最強大的模型系列，相較於 Gemini 2.5 Pro，效能有顯著提升。遷移時，請注意以下事項：

思考：如果您先前使用複雜的提示工程 (例如連鎖思考) 強迫 Gemini 2.5 推理，請試用 Gemini 3 和簡化提示。thinking_level: "high"
溫度設定：如果現有程式碼明確設定溫度 (尤其是確定性輸出結果的低值)，建議移除這個參數並使用 Gemini 3 的預設值 1.0，以免發生潛在的迴圈問題，或複雜工作效能降低。
PDF 和文件理解：PDF 的預設 OCR 解析度已變更。如果您依賴特定行為來剖析密集文件，請測試新的 media_resolution_high 設定，確保準確度不受影響。
權杖用量：改用 Gemini 3 Pro 預設模型後，PDF 的權杖用量可能會增加，但影片的權杖用量會減少。如果預設解析度提高後，要求超出脈絡窗口，建議您明確降低媒體解析度。
圖片區隔：Gemini 3 Pro 不支援圖片區隔功能 (傳回物件的像素層級遮罩)。如果工作負載需要原生圖像分割功能，建議繼續使用 Gemini 2.5 Flash 並關閉思考模式，或使用 Gemini Robotics-ER 1.5。

OpenAI 相容性

如果使用者採用 OpenAI 相容層，系統會自動將標準參數對應至 Gemini 的對等項目：

reasoning_effort (OAI) 對應至 thinking_level (Gemini)。請注意，reasoning_effort 中等會對應至 thinking_level 高。

提示最佳做法

Gemini 3 是推理模型，因此提示方式與以往不同。

明確的指令：輸入提示時請簡潔扼要。Gemini 3 最適合直接且清楚的指令。如果使用舊版模型，系統可能會過度分析冗長或過於複雜的提示工程技術。
輸出內容詳細程度：Gemini 3 預設會提供較簡潔的答案，偏好直接且有效率地回答問題。如果您的用途需要更具對話感或「健談」的角色，您必須在提示中明確引導模型 (例如「請以健談的語氣回覆」)。「以親切健談的助理身分說明這件事」)。
脈絡管理：處理大型資料集 (例如整本書、程式碼集或長影片) 時，請將具體指示或問題放在提示結尾，也就是資料脈絡之後。在問題開頭使用「根據上述資訊...」等詞組，讓模型根據提供的資料進行推論。

如要進一步瞭解提示設計策略，請參閱提示工程指南。

常見問題

Gemini 3 Pro 的知識截止日期為何？Gemini 3 的知識截止日期為 2025 年 1 月。如要取得最新資訊，請使用「搜尋基礎」工具。
脈絡窗口的限制為何？Gemini 3 Pro 支援 100 萬個詞元的輸入脈絡窗口，以及最多 64,000 個詞元的輸出內容。
Gemini 3 Pro 是否提供免費方案？您可以在 Google AI Studio 中免費試用這個模型，但目前 Gemini API 中的 gemini-3-pro-preview 沒有免費方案。
舊的 thinking_budget 程式碼是否仍可運作？可以，為了回溯相容性，系統仍支援 thinking_budget，但建議您遷移至 thinking_level，以獲得更可預測的成效。請勿在同一要求中使用這兩者。
Gemini 3 是否支援 Batch API？是，Gemini 3 支援 Batch API。
是否支援脈絡快取？可以，Gemini 3 支援脈絡快取。如要啟動快取，至少需要 2,048 個權杖。
Gemini 3 支援哪些工具？Gemini 3 支援 Google 搜尋、檔案搜尋、程式碼執行和網址脈絡。此外，也支援標準的函式呼叫，方便您使用自訂工具。請注意，目前不支援 Google 地圖和電腦使用。

後續步驟

開始使用 Gemini 3 食譜
請參閱專屬的 Cookbook 指南，瞭解思考層級，以及如何從思考預算遷移至思考層級。