Gemini APIGoogle GenAITutorial

Gemini API 教學 2026：從第一次呼叫到正式上線

Q: 我可以用 OpenAI SDK 呼叫 Gemini 嗎？

可以——Google 提供 OpenAI 相容的 endpoint，所以只要改 base_url，既有的程式碼大多直接就能跑。統一 gateway 提供同樣的相容性，而且只有一份帳單關係。

2026年8月15日閱讀 1 分鐘

你打開 Gemini 文件，第一個決定就迎面而來：AI Studio 還是 Vertex AI？接著是第二個：該用哪個 SDK？然後是第三個：為什麼定價頁面上列了三款 Flash 模型，而你找到的教學卻是針對 Gemini 1.5 寫的？

Gemini 是文件最齊全、但教學資源最糟糕的 AI 平台。官方文件鉅細靡遺卻零散凌亂；第三方教學不是兩分鐘的「免費 Key」廢文，就是以早已不存在的模型為對象的 2024 年過期內容。與此同時，平台本身前進得很快——Gemini 3.7 Flash 上市時 API 定價大約砍半，而 Flash 產品線現在的發佈節奏已經領先旗艦模型。

這份教學補上的正是中間空缺的那一塊：一條從第一次呼叫到正式上線的完整路徑，涵蓋 Python 與 Node.js，以及 Gemini 的六大差異化功能——thinking budget、context caching、Google Search grounding、structured output、原生多模態與 live API——外加正式上線檢查清單，和那些會花掉真金白銀的錯誤。這是我們平台系列教學的第三篇，與 OpenAI 教學及 Claude 指南並列。

2026 年的 Gemini API 是什麼

重點：Gemini 是三個入口、一個模型家族——而價值就在 Flash 產品線。

通往同一批模型有三條路：

AI Studio——開發者入口。提供免費額度做實驗、發放 API Key，也是通往第一次呼叫最快的一條路。從這裡開始。
Vertex AI——企業入口。具備治理、VPC、稽核控制與按專案劃分的 quota 管理。當合規要求浮上檯面時，再移過來。
統一的 endpoint——透過 OpenAI 相容的 gateway，你可以用既有的 SDK 呼叫 Gemini。同一批模型，一份帳單關係。

2026 年的產品陣容：Gemini 3.7 Flash 是目前的主力——那次讓 API 定價大約砍半的發佈，把價格帶到約 每百萬 input tokens $0.75（最新費率請見定價參考）；Flash-Lite 位居其下，負責高吞吐的簡單任務；Pro 層級守住品質天花板，模型目錄則記錄了透過單一 endpoint 可取用的模型。實用的心智模型是：正式環境預設用 Flash，量測過品質差距的任務用 Pro，沒量測過的任務用 Lite。

為什麼 Gemini 值得一席之地

重點：四項結構性優勢——免費額度、快取定價、原生多模態與 grounding——讓 Gemini 成為 OpenAI 與 Anthropic 之外，成本與能力上的制衡力量。

免費額度是真的。 AI Studio 的免費額度涵蓋原型開發與評估，而且不需要綁卡。這不是行銷上的註腳；這正是你在投入任何資源之前，拿 Gemini 跟現有供應商做基準測試的方法。
約 0.1 倍的 context caching。 快取命中的 input tokens 大約只按標準 input 費率的一成計費——每家供應商的快取都是同樣的模式，機制細節見我們的文件。
原生多模態。 圖片與音訊輸入是一等公民，不是附加功能——含有圖表的文件，一個 prompt 就能處理，不需要另外一條 vision pipeline。
Google Search grounding。 即時檢索搜尋結果並附上引用來源，是平台內建功能，不是一個整合專案。

以上任何一項都不是「最好的模型」。四者加在一起，讓 Gemini 成為大多數技術棧裡最強的第二供應商——而我們的四家供應商比較早已說明，為什麼「第二供應商」是一種策略，不是一句貶抑。

第一次呼叫：Python 與 Node.js

重點：第一次呼叫只要五分鐘——真正的教學在於圍繞它的正式環境習慣。

Python，使用官方的 Google GenAI SDK：

from google import genai

client = genai.Client(api_key="YOUR_AI_STUDIO_KEY")
response = client.models.generate_content(
    model="gemini-3.7-flash",
    contents="Explain why caching cuts token costs, in one sentence.",
)
print(response.text)

Node.js，同樣的寫法：

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

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const response = await ai.models.generateContent({
  model: "gemini-3.7-flash",
  contents: "Explain why caching cuts token costs, in one sentence.",
});
console.log(response.text);

已經在用 OpenAI 的 SDK？相容 endpoint 只要改一個 base_url 就能接受同樣的呼叫——統一 gateway 也是用這個方式提供 Gemini（快速上手示範了這個模式）。第一次呼叫就要養成的正式環境習慣：從第一天就記錄 usage 欄位。 usage_metadata（prompt tokens、candidates tokens、cached tokens）是成本核算的基礎——每一本 observability 手冊都是從這個習慣開始的。

如何運用 Gemini 的六大差異化功能

重點：六項功能讓 Gemini 有別於「又一個聊天 API」——每一項都是一個設定，不是一個專案。

Thinking budget。 Gemini 的 thinking 模型在回答之前會配置 reasoning tokens，而 thinking tokens 是要計費的。正式環境要設定明確的預算；預設值拿來探索還行，拿來做分類就很貴。簡單任務應該走 non-thinking 路徑。
Context caching。 快取穩定的 prompt prefix（system prompts、文件模板），命中時只要付約 0.1 倍的價格。快取 key 就是確切的 token prefix——prefix 有任何變動都會完全失配，這正是「快取沒用」回報的頭號原因。這項設定是內容上的一個旗標，不是獨立的 API（以下為 2026 年中 SDK 的寫法；固定 SDK 版本時請再對照官方文件）：

from google import genai
from google.genai import types

client = genai.Client(api_key="YOUR_AI_STUDIO_KEY")

# 1) Create the cache once, tied to your stable system prompt
cache = client.caches.create(
    model="gemini-3.7-flash",
    config=types.CreateCachedContentConfig(
        display_name="support-template",
        system_instruction="You are a support assistant for Acme.",
        contents=[types.Content(role="user",
                                parts=[types.Part.from_text(text="REPEATED_BOILERPLATE")])],
        ttl="3600s",
    ),
)

# 2) Reference it by resource name on every call
resp = client.models.generate_content(
    model="gemini-3.7-flash",
    contents="Refund policy, please.",
    config=types.GenerateContentConfig(cached_content=cache.name),
)

Google Search grounding。 對時效敏感的查詢啟用 grounding，就能在答案之外拿到引用來源——本系列其他文章已涵蓋通用的 grounding 模式。留意 grounding 的費用項目；它與 generation 分開計費。

resp = client.models.generate_content(
    model="gemini-3.7-flash",
    contents="What is the current limit for...?",
    config=types.GenerateContentConfig(
        tools=[types.Tool(google_search=types.GoogleSearch())],
    ),
)
# resp.candidates[0].grounding_metadata holds the citations

Structured output。 綁定 JSON schema，Gemini 就會遵守——但有一條鐵律：使用 schema binding 時，temperature 要維持在預設值，因為改動它會破壞保證。這正是我們的structured output 指南記錄過的那個陷阱。

resp = client.models.generate_content(
    model="gemini-3.7-flash",
    contents="Extract the invoice total and currency.",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_schema=types.Schema(
            type=types.Type.OBJECT,
            properties={
                "total": types.Schema(type=types.Type.NUMBER),
                "currency": types.Schema(type=types.Type.STRING),
            },
            required=["total", "currency"],
        ),
        temperature=1.0,  # default — do not change with schema binding
    ),
)

原生多模態。 圖片與音訊輸入走同一套 API——一張截圖、一張圖表、一段錄音，都只是一個 contents 參數。
Live/audio API。 即時語音對話存在於平台自己的介面上；在圍繞它設計架構之前，先確認目前的可用性與區域支援（而且要記住，endpoint 的能力就是那樣——自己驗證，不要假設）。

如何把 Gemini 帶上正式環境

重點：正式上線的路徑是 quota、成本控制、eval 與 Key——依這個順序。

Quota 與限制。 AI Studio 和 Vertex 的內建預設 rate limit 不同；正式環境的工作負載要在上線週之前提出 quota 調升申請，而不是收到第一個 429 之後。標準的 rate-limit 處理手冊——exponential backoff、header-aware 重試、multi-provider fallback——原封不動地適用。
成本控制。 三個槓桿，全都是設定：快取穩定的 prefix、把簡單任務路由到 Flash-Lite、在儀表板上設定花費警示。組合起來通常能把一份未經優化的 Gemini 帳單砍掉 60-80%——每一本成本優化手冊排名最高的那組策略。
上線前先 eval。 一組固定的 eval set 加上 pass/fail 門檻，能攔下「模型感覺沒問題」這種判斷漏掉的回歸問題。CI 式的 eval 紀律與供應商無關——在切換到 Gemini 之前跑，而不是之後。
Key 與安全。 AI Studio 的 Key 以專案為範圍；把它們當成任何憑證一樣對待——只放後端、定期輪換、絕不進客戶端程式碼。標準的 API Key 安全檢查清單完整適用。

浪費時間與 Token 的常見錯誤

重點：四個 Gemini 特有的錯誤——全部都有紀錄在供應商論壇上，全部都可以避免。

Temperature 陷阱。 在綁定 schema 的 structured output 上改動 temperature，會默默破壞輸出保證。structured 呼叫永遠用預設值。
沒有編預算的 thinking tokens。 thinking 路徑是要計費的；開啟 thinking 的分類工作負載，會為它不需要的推理付錢。針對每種任務類型設定預算。
快取 key 不穩定。 附加時間戳記或重新排列 prompt 的組成部分，都會讓快取完全失配。把 prompt prefix 設計成穩定的單位；把命中率當成指標來量測。
跟著 2024 年的教學走。 Gemini 1.5 時代的指南描述的是早已不存在的參數與模型。如果教學沒提到 3.x 的模型，那它就是考古文獻——請改查官方文件，以及這份指南的日期。

常見問題

Gemini API 免費嗎？

AI Studio 提供免費額度，供實驗與原型開發使用，正式環境則按 token 計費。免費額度是真的，而且不需要綁卡——在投入之前用它來做評估。

AI Studio 還是 Vertex AI——我該用哪一個？

原型開發與個人專案用 AI Studio；企業治理、VPC 與稽核需求用 Vertex AI。如果你是透過統一 gateway 路由，這個區別大多會消失——一個 endpoint，同一批模型。

Gemini 的 context caching 真的約 0.1 倍嗎？

是的——快取命中的 input tokens 大約只按標準費率的一成計費。關鍵在於 key 的穩定性：快取只會在確切的 token prefix 上命中，所以穩定的 prompt 結構就是一切。

我可以用 OpenAI SDK 呼叫 Gemini 嗎？

可以——Google 提供 OpenAI 相容的 endpoint，所以只要改 base_url，既有的程式碼大多直接就能跑。統一 gateway 提供同樣的相容性，而且只有一份帳單關係。

Thinking mode 什麼時候值得用？

複雜推理、程式碼生成與多步驟任務——以你的 eval set 來衡量。至於分類、抽取，以及任何答案有明確範圍的任務，non-thinking 路徑更快、更便宜，品質通常也一樣。

Gemini 的 structured output 有多穩定？

只要遵守兩條規則就很穩定：綁定 schema，並讓 temperature 維持在預設值。違反任何一條，你就會得到默默的偏移——這是每家供應商 structured output 都有的失敗模式，上面連結的 JSON mode 比較文章有完整記錄。

總結

2026 年的 Gemini API 是以 Flash 為主的平台：現行 Flash 模型大約砍半的定價、真實的免費額度、約 0.1 倍快取經濟學、原生多模態與內建 grounding——還有六項「設定而非專案」的差異化功能。從 AI Studio 開始，從第一次呼叫就記錄 usage、為 thinking tokens 編列預算、保持快取 key 穩定，並在切換之前先 eval。接下來，它就只是你統一 endpoint後面的另一個優秀模型。

五分鐘就能拿到你的第一批 Gemini tokens——不需要 Google Cloud 帳號。立即取得你的 TokSpan API Key，用你既有的 SDK 呼叫 Gemini；$5 免費額度就夠跑完整份教學。