如何使用 Gemini 3.1 pro API

CometAPI
AnnaFeb 21, 2026
如何使用 Gemini 3.1 pro API

面向 Gemini 3.1 Pro 的實用、以程式碼為中心的指南——它是什麼、如何呼叫（包含透過 CometAPI）、其多模態與「思考層級」控制、函式呼叫/工具使用、氛圍編碼技巧，以及與 GitHub Copilot、VS Code、Gemini CLI、Google Antigravity 的整合。Gemini 3.1 Pro 正在推進大型多模態模型的前沿，並以開發者為核心：更大的上下文視窗、可配置的「思考」模式、改進的工具與函式呼叫，以及明確支援代理型工作流程。

什麼是 Gemini 3.1 Pro？

Gemini 3.1 Pro 是 Gemini 3 系列最新的「Pro」等級：原生多模態、以推理為先，針對複雜的多步驟任務與代理型工具使用進行調校。它被呈現為在 Gemini 3 Pro 之上的精修版，實用重點包括：更強的推理／事實鍛造、更佳的 token 效率，以及可控的執行模式，鎖定開發者工作流程（程式碼、規劃、檢索增強任務）。模型卡與開發者頁面描述它對軟體工程行為、代理管線與多模態輸入（文字、影像、音訊、影片與版本庫）進行了最佳化。

為何這對你重要：結合百萬 token 的上下文視窗（在許多供應商變體上）、明確的函式呼叫原語，以及「思考層級」控制，讓團隊在從快速原型到生產級代理編排的各種場景中，獲得更可預測的成本與輸出。CometAPI 已透過 API 市場與 OpenAI 相容橋接呈現 3.1 Pro，提供隨用隨付的存取模式。

如何使用 Gemini 3.1 Pro API（CometAPI）？

在開始之前我需要什麼？

清單（前置條件）

  • 一個 CometAPI 帳戶與 CometAPI API 金鑰（存放於環境變數）。
  • （選用）若直接呼叫 Google，需準備 Google Cloud / Google AI Studio 專案與 Gemini API 金鑰（透過 Comet 時不需要）。
  • python 3.9+ 或 node 18+，並可使用 curl 進行快速測試。
  • 安全的機密管理機制：環境變數、金鑰保管庫或 CI 機密儲存。
  • 在你的 Comet 主控台確認 Gemini 3.1 Pro 的 Comet 模型 id（例如 "google/gemini-3.1-pro" 或 Comet 專用別名）。

CometAPI 支援 Gemini 原生格式的呼叫，也支援 OpenAI 的聊天格式呼叫。CometAPI 簡化模型切換，提供單一 base URL 與 SDK，能降低多供應商堆疊的整合摩擦。

以下是兩個具體、可複製貼上的範例：第一個透過 CometAPI（OpenAI 相容用戶端）呼叫 Gemini，第二個透過 Google 官方的 Gemini HTTP 端點呼叫。請將 YOUR_API_KEY 替換為你的供應商金鑰，並將模型名稱設定為供應商可用的變體（例如在曝光時使用 gemini-3.1-pro-preview）。

範例：使用 CometAPI 呼叫 Gemini 3.1 Pro（curl + Python）

Curl（OpenAI 相容包裝，使用 CometAPI 基底 URL）

# curl example: CometAPI (OpenAI-compatible)curl https://api.cometapi.com/v1/chat/completions \  -H "Authorization: Bearer YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "gemini-3.1-pro-preview",    "messages": [      {"role":"system","content":"You are a concise programming assistant."},      {"role":"user","content":"Write a Python function to fetch CSV from a URL and return pandas DataFrame."}    ],    "max_tokens": 800  }'

Python（OpenAI 相容客戶端，設定為 CometAPI base_url）

from openai import OpenAI  # or openai-python-compatible SDK offered by your platformclient = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.cometapi.com/v1")resp = client.chat.completions.create(    model="gemini-3.1-pro-preview",    messages=[        {"role": "system", "content": "You are a concise programming assistant."},        {"role": "user", "content": "Write a Python function to fetch CSV from a URL and return pandas DataFrame."}    ],    max_tokens=800,)print(resp.choices[0].message.content)

理由：CometAPI 在許多文件中提供 OpenAI 相容的橋接，讓你只需變更 base_url 與模型名稱，即可重用既有的 OpenAI 客戶端程式碼。這對多供應商實驗與快速原型很方便。

範例：透過官方 Gemini API 呼叫（Node.js / HTTP）

Google 的官方 Gemini 端點最適合使用完整的功能集（思考層級控制、函式呼叫、多模態上傳）。以下是使用 Google AI 開發者文件描述的 Gemini API 介面的最小化 HTTP 範例。

只需在官方 SDK 或請求中替換 Base URL 與 API Key 即可：

  • Base URL：https://api.cometapi.com（將 generativelanguage.googleapis.com 替換）
  • API Key：將 $GEMINI_API_KEY 替換為你的 $COMETAPI_KEY

Curl（官方 Gemini API — 示意）

curl "https://api.cometapi.com/v1beta/models/gemini-3-1-pro-preview:generateContent" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "How does AI work?"
          }
        ]
      }
    ]
  }'

常用參數設定

  • temperature（0.0–1.0）— 隨機性。對程式碼輸出，使用 0.0 以獲得決定性結果。
  • max_output_tokens / max_tokens — 輸出長度預算。
  • top_p — 核心取樣（nucleus sampling）。
  • presence_penalty / frequency_penalty — 降低重複。
  • thinking_level 或模型變體 — 決定推理深度（例如 -low、-medium、-high 或明確的 thinking_level）。為控制成本／延遲，使用能滿足準確度需求的最低思考層級。

Gemini 3.1 Pro 的多模態能力是什麼？

Gemini 3.1 Pro 支援哪些模態？

Gemini 3.1 Pro 在許多預覽版本中可接收文字、影像、影片、音訊與 PDF，並可生成參考或摘要多模態內容的文字輸出。Comet 支援將多模態輸入轉送至 Gemini——可透過「影像 URL」、「檔案上傳」（Comet 檔案 API），或讓 Gemini 讀取雲端儲存中的檔案。

開發者該如何設計多模態提示？

  • 以清晰的脈絡區塊來結構化多模態提示：例如先提供簡短文字指令，再附上影像／影片／PDF 的中介資料或指標。
  • 使用 SDK 的媒體附件與檔案上傳欄位，而非將二進位資料嵌入文字欄位——官方客戶端與 Vertex AI / Gemini API 範例示範了如何乾淨地傳遞媒體附件。

實務範例（偽程式碼）：顯示圖片並提出問題

# Pseudocode — attach an image with a caption and ask a questionfrom google.gemini import GemSDK  # conceptual import; use official client per docsresponse = client.generate(    model="gemini-3.1-pro-preview",    inputs = [        {"type": "text", "content": "Summarize the visual diagram and list actionable next steps."},        {"type": "image", "uri": "gs://my-bucket/diagram.png", "alt": "system architecture diagram"}    ])print(response.text)

實用提示：

  • 將影像附件用於 UI bug 分析：附上螢幕截圖並請求差異或可能原因。
  • 結合音訊逐字稿與程式碼範例，進行面試錄音的摘要。
  • 在傳送大型素材（影片、大型程式碼庫）時，偏好分段方式：先上傳資產（雲端儲存），傳遞 URL + 短清單，並讓模型驅動檢索增強的管線，而非把所有內容塞進單一提示中。

什麼是思考層級（Low、Medium、High），應該何時使用？

什麼是「思考層級」？

Gemini 3 系列引入 thinking_level 參數，用來引導模型的內部運算／思維鏈預算。可將它視為在延遲與成本與推理深度之間調節的旋鈕：

  • Low：最小推理，針對吞吐量與短、決定性任務最佳化。
  • Medium：平衡推理——3.1 新增，適合多數工程與分析工作流程。
  • High：更深層推理，動態思維鏈風格；最適合複雜多步驟問題。
    （部分變體也有 minimal／max 的命名——請參閱該變體的模型文件以確認可用選項。）

我該如何選擇思考層級？

  • Low：用於高吞吐量的使用者聊天、短指令，或當成本／延遲至關重要時。
  • Medium：作為多數需要適度推理的開發者任務的預設選擇（這是 3.1 的新「甜蜜點」）。
  • High：用於解題、長邏輯鏈、規劃，或當你明確需要高保真且可接受更高延遲與 token 消耗時。

如何在請求中設定思考層級

curl "https://api.cometapi.com/v1beta/models/gemini-3-1-pro-preview:generateContent" \
  -H "x-goog-api-key: $COMETAPI_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{ "parts": [{ "text": "Explain quantum physics simply." }] }],
    "generationConfig": {
      "thinkingConfig": {
        "thinkingLevel": "LOW"
      }
    }
  }'

如何在 Gemini 3.1 Pro 中實作函式呼叫與工具使用？

什麼是函式呼叫／工具使用？

函式呼叫（也稱工具使用）讓模型輸出結構化的「呼叫」物件，告訴你的應用該呼叫哪一個外部工具或函式（例如 get_current_weather(location)），以及其參數。模型可以串連多次呼叫、接收工具輸出並持續推理——從而啟用代理型行為。Gemini SDK 提供模型到工具迴圈（MCP／工具登錄）的內建支援，幫助你安全地自動化執行。

你可以在設定中宣告工具以啟用代理行為。支援的內建工具包含 google_search、code_execution 與 url_context 自訂函式。

工具使用的安全範式

  1. 宣告工具介面：以清晰的結構與驗證過的參數型別來註冊函式／工具。
  2. 讓模型提出呼叫：模型輸出描述要呼叫哪個工具的結構化 JSON。
  3. 主機僅執行白名單工具：強制允許清單與嚴格驗證。
  4. 將工具輸出回傳給模型：SDK 迴圈會把工具回應餵回模型，使其能持續規劃／執行更多呼叫。

Gemini 3.1 Pro 整合指南

GitHub Copilot

GitHub Copilot（Copilot）已在進階方案中新增對 Gemini 系列模型的支援，允許團隊選用 Gemini 作為 Copilot 聊天與建議的底層模型。這表示符合資格的使用者可在 Copilot 的模型選單中挑選 Gemini 變體，在不更改 IDE 擴充的情況下享受模型層級的改進。對團隊而言，Copilot 仍是把 Gemini 推理帶入 VS Code 與其他支援編輯器的便利託管途徑。

Gemini CLI 與 Code Assist

開源的 Gemini CLI 將 Gemini 模型帶到終端機；它輕量並與既有工作流程（diff、提交、CI、無頭伺服器執行）整合。使用 CLI 可進行快速迭代、腳本化代理執行，或將模型嵌入 DevOps 流程。Gemini Code Assist 是 VS Code 擴充與更廣泛的 IDE 整合，將具脈絡的程式碼建議、PR 審查與自動修正直接帶入編輯器。這些工具讓你可控模型選擇、上下文視窗與思考層級偏好。

Visual Studio Code

Visual Studio Code 與其市集同時提供 GitHub Copilot 與 Gemini Code Assist。你可以安裝 Gemini 的 Code Assist 或持續使用 Copilot；兩者各有取捨（速度、深度、隱私）。VS Code 仍是互動式程式碼生成、編輯器內聊天與直接整合本機執行或測試框架的最成熟介面。

Google Antigravity

Google Antigravity 是以代理為先的 IDE 與平台，將代理視為一等公民，提供用於代理編排的「任務控制台」、內建瀏覽器自動化，以及用於多代理專案的 UI。Antigravity 與 Gemini CLI 滿足不同需求：Antigravity 是完整的代理型 IDE 介面；Gemini CLI 則是終端機原生，但可透過擴充與 MCP（Model Context Protocol）伺服器整合進 Antigravity 與 VS Code。Antigravity 生態系適合希望進行重度代理編排且偏好更具主見、可視化介面的團隊。

誰該用哪一種？

  • 快速原型與單檔編輯：Gemini CLI + 本機測試，或使用 Copilot 以求速度。
  • 深度推理、長時間研究：Gemini API（Vertex）搭配高思考層級與函式呼叫。
  • 代理編排與多步驟自動化：Antigravity 進行可視化管理，或使用函式呼叫 + MCP 建立自訂代理管線。
  • 多供應商實驗／成本控制：使用 CometAPI 或類似聚合器在模型間切換，或經濟地嘗試 Flash 與 Pro。

整合的設計考量：

  • 安全性：避免在提示中傳送機密或個資。對伺服器端呼叫使用具 token 範圍的服務帳戶。
  • 本機 vs 雲端：在本機運行輕量助理功能（快速補全），但將重度多模態分析導向雲端。
  • 使用者控制：為模型產生的程式碼變更提供「解釋此建議」與易於回滾的控制。

整合模式與推薦架構

輕量型應用（聊天或助理）

  • Client（瀏覽器／行動）→ 後端微服務 → Gemini API（thinking_level=low）
  • 為聊天 UX 使用串流／部分輸出。驗證使用者輸入，且切勿允許來自不受信任客戶端的原始工具呼叫。

代理型後端（自動化工作流程）

  • 編排服務：註冊一小組白名單工具（DB 讀取、CI 工作觸發器、內部 API）。
  • 讓 Gemini 規劃並輸出工具呼叫；由編排器執行已驗證的呼叫並回傳結果。規劃階段使用高思考層級，執行步驟使用中等層級。

多模態導入管線

先行處理並索引大型文件、圖片或影片。

什麼時候應選擇 Gemini 3.1 Pro？

在以下需求下選擇 Gemini 3.1 Pro：

  • 跨多模態輸入的高保真多步驟推理；
  • 可靠的工具編排與代理型工作流程；
  • 透過 IDE（Copilot／CLI／Antigravity）進行更佳的程式碼生成／編輯迴圈；或
  • 以 CometAPI 等閘道進行跨供應商比較原型。

若你在乎吞吐量與成本，採用混合策略：多數工作流程以 medium 思考層級為預設，高吞吐量使用者聊天用 low，而只有在確實需要更深推理（規劃、證明、多步驟綜整）時才使用 high。

最後想法：Gemini 3.1 Pro 在技術棧中的定位

Gemini 3.1 Pro 強化了現代面向開發者的 LLM 所必須具備的能力：多模態理解、明確的工具編排，以及對推理預算的務實控制。無論你是直接透過 Google 的 API 與 Vertex 存取、在進階方案中透過 Copilot 使用，或透過 CometAPI 等多模型平台接入，對團隊而言關鍵技能都是一致的：謹慎的思考層級編排、安全的函式呼叫範式，並將其整合進穩健的開發者工作流程（CLI、IDE、自動化測試）。

開發者現在即可透過 Gemini 3.1 Pro 與 CometAPI 存取。開始前，請在 Playground 探索模型能力，並參考 API 指南 取得詳細說明。存取前請先登入 CometAPI 並取得 API 金鑰。CometAPI 提供遠低於官方價格的方案，協助你整合。

Ready to Go?→ 立即註冊 Gemini 3.1 Pro！

若想獲取更多 AI 技巧、指南與新聞，請在 VK、X 與 Discord 關注我們！

以低成本 存取頂級模型

閱讀更多