Python Gemini API 教學 — google-genai SDK 入門與免費額度

Python 串接 Gemini API

這篇 Gemini API 教學延續上一篇的模式，改串 Google 的 Gemini 模型。對個人開發者有個誘因：Google AI Studio 提供免費額度，拿來練習串接幾乎零成本。

事前準備：

到 Google AI Studio（aistudio.google.com）建立 API Key
安裝官方 SDK：uv add google-genai

套件名稱注意：要裝的是 google-genai（新版官方 SDK）。網路上大量舊教學用的 google-generativeai 已棄用，寫法完全不同，照舊教學做會走錯路——這是 Gemini 串接最常見的坑。

金鑰設定

SDK 預設讀取環境變數 GEMINI_API_KEY：

# Windows（PowerShell）
$env:GEMINI_API_KEY = "AIza..."

# macOS / Linux
export GEMINI_API_KEY="AIza..."

第一個請求

from google import genai

client = genai.Client()    # 自動讀取 GEMINI_API_KEY

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="用一句話解釋什麼是 Python 的 Dictionary",
)

print(response.text)

執行輸出（AI 回應每次不同）：

Dictionary 是以 key-value 配對儲存資料、可用鍵快速查值的容器。

結構跟 OpenAI 幾乎平行對應：

概念	OpenAI	Gemini
建立客戶端	`OpenAI()`	`genai.Client()`
發出請求	`client.responses.create()`	`client.models.generate_content()`
輸入	`input=`	`contents=`
取文字	`response.output_text`	`response.text`

模型名稱會隨版本更新（寫文當下 Flash 系列的最新版是 gemini-3.5-flash，適合一般用途；Pro 系列適合複雜推理），以官方文件的模型清單為準。

系統指示：system_instruction

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="怎麼合併兩個 dict？",
    config=types.GenerateContentConfig(
        system_instruction="你是繁體中文的 Python 家教，回答簡潔、附程式碼範例。",
    ),
)
print(response.text)

執行輸出（AI 回應每次不同）：

用 | 運算子最簡潔：

a = {"x": 1}
b = {"y": 2}
print(a | b)   # {'x': 1, 'y': 2}

多輪對話：chats

Gemini 的多輪對話用 chats 介面，歷史自動維護：

from google import genai

client = genai.Client()
chat = client.chats.create(model="gemini-3.5-flash")

r1 = chat.send_message("我叫小明，請記住。")
r2 = chat.send_message("我叫什麼名字？")
print(r2.text)

執行輸出（AI 回應每次不同）：

你叫小明。

錯誤處理

from google import genai
from google.genai import errors

client = genai.Client()

try:
    response = client.models.generate_content(
        model="gemini-3.5-flash",
        contents="你好",
    )
    print(response.text)
except errors.APIError as e:
    print("API 錯誤：", e.code, e.message)

常見的 e.code：401／403 金鑰問題、404 模型名稱錯誤、429 超出額度（免費額度有每分鐘請求數限制，被擋到等一下再試）。

常見錯誤

1. 裝錯套件

uv add google-generativeai 是舊版（已棄用）。認明 google-genai，import 寫法是 from google import genai。

2. 404 model not found

模型名稱拼錯或已退役。模型世代更新快，用官方文件確認當前名稱。

3. 429 RESOURCE_EXHAUSTED

免費額度的速率限制。請求之間加 time.sleep()，或升級付費方案。

總結

Gemini 串接三步：金鑰放 GEMINI_API_KEY → genai.Client() → generate_content(model, contents) 取 response.text；多輪用 chats；認明新套件 google-genai。學會 OpenAI 與 Gemini 後你會發現：LLM API 的套路是通用的，換家只是改名詞。最後一篇，我們讓 AI 直接幫你寫 Python——Claude Code 實戰。

延伸閱讀

ㄚ槌