Gemini API Python 串接教學：2026 從零開始呼叫 Google AI 模型

5 分鐘內讓 Gemini API 跑起來

你已經聽說 Gemini API 很強、很便宜。

但你打開 Google 的官方文件，發現它又長又散，不知道從哪裡開始。

這篇教學幫你省掉翻文件的時間。我會用最簡單的步驟，帶你從零開始完成 Gemini API 的 Python 串接——從安裝 SDK 到多模態應用，每一步都附上可以直接複製貼上的程式碼。

需要 Gemini API 企業方案？透過 CloudInsight 取得更優價格，免煩惱海外付款問題。

TL;DR

安裝 google-generativeai 套件 → 設定 API Key → 用 GenerativeModel 建立模型實例 → 呼叫 generate_content() 就完成。本教學涵蓋文字生成、圖片理解、Streaming、Function Calling，附完整可執行程式碼。

---

Python 環境準備與 Gemini SDK 安裝

Answer-First： 你只需要 Python 3.9+、pip，以及一行 pip install google-generativeai 就能開始。

環境需求

項目	最低需求	建議版本
Python	3.9	3.11+
pip	21.0	最新版
google-generativeai	0.8.0	0.8.x 最新
作業系統	Windows / macOS / Linux	皆可

安裝步驟

建議先建立虛擬環境，避免套件衝突：

# 建立虛擬環境
python -m venv gemini-env

# 啟動虛擬環境（macOS / Linux）
source gemini-env/bin/activate

# 啟動虛擬環境（Windows）
gemini-env\Scripts\activate

# 安裝 Gemini SDK
pip install google-generativeai

安裝完成後，驗證一下：

python -c "import google.generativeai as genai; print(genai.__version__)"

如果看到版本號，代表安裝成功。

常見安裝問題

• pip 版本太舊：先執行 pip install --upgrade pip
• SSL 錯誤：公司內網可能需要設定 proxy
• M1/M2 Mac 相容性：目前 SDK 完全支援 Apple Silicon

---

取得 Gemini API Key 並設定驗證

Answer-First： 到 Google AI Studio 點兩下就能拿到 API Key，用環境變數存放是最安全的做法。

取得 API Key

1. 前往 Google AI Studio
2. 登入你的 Google 帳號
3. 點選「Get API Key」→「Create API Key」
4. 複製產生的 Key

不需要綁信用卡就能取得免費 API Key。完整的申請步驟，請參考 Gemini API 官方文件與功能導覽。

設定 API Key（安全做法）

千萬不要把 API Key 直接寫在程式碼裡。

正確做法是用環境變數：

# macOS / Linux
export GEMINI_API_KEY="your-api-key-here"

# Windows PowerShell
$env:GEMINI_API_KEY="your-api-key-here"

然後在 Python 中讀取：

import os
import google.generativeai as genai

genai.configure(api_key=os.environ["GEMINI_API_KEY"])

如果你用 .env 檔案管理環境變數，搭配 python-dotenv 也可以：

from dotenv import load_dotenv
load_dotenv()

genai.configure(api_key=os.getenv("GEMINI_API_KEY"))

---

文字生成 API 呼叫實作與程式碼範例

Answer-First： 用 GenerativeModel 建立模型實例，呼叫 generate_content() 傳入 Prompt，就能取得 AI 生成的文字回應。

最基本的文字生成

import os
import google.generativeai as genai

genai.configure(api_key=os.environ["GEMINI_API_KEY"])

# 建立模型實例
model = genai.GenerativeModel("gemini-2.0-flash")

# 呼叫 API
response = model.generate_content("請用 3 個重點介紹台灣的夜市文化")

# 印出結果
print(response.text)

這就是最簡單的用法。6 行程式碼就能讓 Gemini API 跑起來。

調整生成參數

你可以透過 GenerationConfig 控制生成結果：

config = genai.GenerationConfig(
    temperature=0.7,       # 創意程度（0-2，越高越有創意）
    top_p=0.9,             # 取樣範圍
    top_k=40,              # 候選 Token 數量
    max_output_tokens=1024 # 最大輸出長度
)

response = model.generate_content(
    "寫一首關於台北下雨天的短詩",
    generation_config=config
)

參數建議：

場景	temperature	top_p	說明
翻譯、摘要	0.1-0.3	0.8	需要準確性
一般問答	0.5-0.7	0.9	平衡創意與準確
創意寫作	1.0-1.5	0.95	需要多樣性

多輪對話

chat = model.start_chat(history=[])

response = chat.send_message("你好！我想學習 Python")
print(response.text)

response = chat.send_message("可以推薦入門書籍嗎？")
print(response.text)

start_chat() 會自動維護對話歷史，你不需要手動管理上下文。

透過 CloudInsight 採購 Gemini API，享企業專屬折扣與統一發票。了解企業方案

---

多模態應用：圖片理解與影片分析

Answer-First： Gemini API 原生支援多模態輸入，你可以同時傳入文字 + 圖片（或影片），讓 AI 理解視覺內容並生成文字回應。

圖片理解

import PIL.Image

model = genai.GenerativeModel("gemini-2.0-flash")

# 載入本地圖片
img = PIL.Image.open("receipt.jpg")

# 傳入圖片 + 文字提示
response = model.generate_content([
    "請辨識這張收據上的商品名稱和金額，以表格格式輸出",
    img
])

print(response.text)

支援的圖片格式：JPEG、PNG、GIF、WebP。單張圖片最大 20MB。

多張圖片比較

img1 = PIL.Image.open("product_a.jpg")
img2 = PIL.Image.open("product_b.jpg")

response = model.generate_content([
    "比較這兩個產品的外觀差異",
    img1,
    img2
])

影片分析

Gemini API 支援直接上傳影片檔案：

video_file = genai.upload_file("demo.mp4")

# 等待檔案處理完成
import time
while video_file.state.name == "PROCESSING":
    time.sleep(2)
    video_file = genai.get_file(video_file.name)

response = model.generate_content([
    "請為這段影片生成 5 個重點摘要",
    video_file
])

影片分析是 Gemini API 目前獨有的優勢——OpenAI 和 Claude 都還不支援直接上傳影片。

但要注意：影片分析會消耗大量 Token。一段 1 分鐘的影片大約消耗 4,000-8,000 Token。長影片的成本會很高。

如果你也想學習 OpenAI 的 Python 串接方式，可以參考 OpenAI API Python SDK 串接完整教學。兩套 API 的設計邏輯不同，同時學習可以幫助你選出最適合專案的方案。

---

進階技巧：Streaming、Function Calling 與錯誤處理

Answer-First： Streaming 讓回應即時顯示、Function Calling 讓 AI 呼叫自定義函式、錯誤處理確保程式穩定運行。這三個進階技巧是正式上線必備的。

Streaming 回應

不想等 AI 想完才看到結果？用 Streaming：

response = model.generate_content(
    "詳細介紹 5 個台灣必去的旅遊景點",
    stream=True
)

for chunk in response:
    print(chunk.text, end="", flush=True)

Streaming 在聊天機器人場景特別有用。使用者不用盯著空白畫面等 AI 回完。

Function Calling

讓 AI 可以呼叫你定義的函式：

def get_weather(city: str) -> dict:
    """取得指定城市的天氣資訊"""
    # 實際上會呼叫天氣 API
    return {"city": city, "temp": 28, "condition": "晴天"}

model = genai.GenerativeModel(
    "gemini-2.0-flash",
    tools=[get_weather]
)

chat = model.start_chat()
response = chat.send_message("台北今天天氣如何？")

Gemini 會自動判斷什麼時候該呼叫 get_weather，並帶入正確的 city 參數。

錯誤處理

正式環境一定要做錯誤處理：

import google.api_core.exceptions as exceptions

try:
    response = model.generate_content("你的 Prompt")
    print(response.text)
except exceptions.ResourceExhausted:
    print("超過速率限制，請稍後再試")
except exceptions.InvalidArgument as e:
    print(f"請求參數有誤：{e}")
except exceptions.PermissionDenied:
    print("API Key 無效或權限不足")
except Exception as e:
    print(f"未知錯誤：{e}")

常見錯誤碼：

錯誤碼	原因	解決方式
429	超過速率限制	加入重試邏輯，間隔遞增
400	請求格式錯誤	檢查 Prompt 和參數
403	API Key 無效	確認 Key 是否正確、是否有效
500	伺服器端錯誤	稍後重試

---

下一步：從練習到正式上線

你現在已經學會了 Gemini API Python 串接的完整流程。

但從「能跑」到「上線」之間，還有幾件事要注意：

• API Key 安全：絕對不要 commit 到 Git，使用環境變數或 Secret Manager。更多安全管理技巧請參考 API Key 管理與安全最佳實踐
• 成本監控：設定每日用量上限，避免意外超支。各家 API 的成本差異請參考 AI API 費用比較完整攻略
• 模型選擇：開發測試用 Flash（便宜），正式產品根據品質需求選 Pro 或 Ultra
• 速率限制：加入 exponential backoff 的重試機制

想了解 Gemini API 的完整功能和定價方案，請參考 Gemini API 完整開發指南。

如果你對 Python AI 開發有更廣泛的興趣，Python AI API 串接入門教學涵蓋了各家 API 的共通概念和比較。想進一步了解各家 API 的費用差異，AI API 費用比較完整攻略會很有幫助。

需要企業級的 Gemini API 方案？CloudInsight 提供批量 Token 採購折扣、統一發票和中文技術支援。立即諮詢企業方案，或加入 LINE 官方帳號即時獲得技術支援。

常見問題 FAQ

Q1: google-generativeai 和 vertexai SDK 差在哪？我該用哪個？

看你要用哪個 endpoint。Gemini API 現在有兩個主要 Python SDK：(1) google-generativeai（推薦入門）——呼叫 Google AI Studio 的 API endpoint（generativelanguage.googleapis.com）、只需 API key 認證、最適合個人 / 原型開發；安裝：pip install google-generativeai；範例：genai.GenerativeModel('gemini-2.0-flash').generate_content(...)。(2) google-cloud-aiplatform (vertexai)——呼叫 Vertex AI 的 endpoint、需要 GCP 帳號和 Application Default Credentials、適合企業 production；安裝：pip install google-cloud-aiplatform；範例：vertexai.init(project='my-project', location='us-central1'); model = GenerativeModel('gemini-2.0-flash')。選擇原則：(A) 個人 / 學習 / 原型 → google-generativeai；(B) 公司商業產品、需要 audit log、資料保護 → vertexai；(C) 已在 GCP、想用 IAM 統一管理 → vertexai。遷移注意：兩者 API 設計類似但不完全一樣，code 不能直接搬，但基本呼叫模式很接近，一天內可重構。新 SDK：2025 年 Google 推出統一的 google-genai SDK（取代 google-generativeai），支援兩個 endpoint，若是新專案直接用這個。

Q2: Streaming response 要怎麼實作？Flask / FastAPI 要怎麼傳給前端？

Gemini SDK 支援 streaming，結合 SSE（Server-Sent Events）送給前端最常見。Python 實作：response = model.generate_content(prompt, stream=True) → for chunk in response: print(chunk.text)。FastAPI + SSE 完整範例：(1) Backend：from fastapi.responses import StreamingResponse; async def generate(): for chunk in response: yield f"data: {chunk.text}\n\n"; return StreamingResponse(generate(), media_type="text/event-stream")；(2) Frontend：const eventSource = new EventSource('/api/chat'); eventSource.onmessage = (e) => { document.getElementById('output').innerText += e.data; }。Flask 版本：類似但用 yield + Response(stream_with_context(...), mimetype='text/event-stream')。注意事項：(1) CORS headers——SSE 可能被瀏覽器阻擋；(2) timeout——某些 reverse proxy（nginx）預設 60 秒 timeout，長回覆要設更長；(3) error handling——串流中途斷掉要處理好，不要 silent fail；(4) testing——用 curl -N http://localhost:8000/chat 測試 streaming。什麼時候不用 streaming：(A) 結構化輸出（JSON mode）不需要 streaming，等完整再 parse；(B) 短回覆（< 100 tokens）streaming 反而複雜度 > 收益。

Q3: API Key 管理最安全的做法是什麼？不同環境（dev/staging/prod）怎麼處理？

三階段安全升級。(1) 絕對不要做——(A) 寫死在 code 裡、(B) commit 到 git、(C) 放到 frontend JavaScript（會被看到）、(D) 貼在 Slack / email。(2) 基礎做法（個人 / 小專案）——(A) .env 檔案 + .gitignore——GEMINI_API_KEY=xxx 在 .env，code 用 os.getenv() 讀；(B) 使用 python-dotenv——from dotenv import load_dotenv; load_dotenv()。(3) 進階做法（團隊 / production）——(A) GCP Secret Manager——from google.cloud import secretmanager; client.access_secret_version(...)；(B) AWS Secrets Manager / Azure Key Vault——類似；(C) 環境變數注入——Kubernetes Secrets、Cloud Run env vars、GitHub Actions secrets。不同環境管理：(A) dev：個人 API key（每人一支，額度較小）；(B) staging：共用測試 key，限制 domain whitelist；(C) prod：正式 key 放 Secret Manager + rotation policy（每 90 天輪替）；(D) CI/CD：GitHub Secrets、GCP Secret Manager，絕不 hardcode。洩漏後急救：(1) 立刻 revoke key（AI Studio / GCP console 一鍵）；(2) rotate 所有應用的 key；(3) check logs 看有沒有異常使用；(4) git history 清洗（用 BFG Repo-Cleaner）。Google 有自動掃描 GitHub，發現 Gemini API key 會自動 disable 並通知，但不要依賴這個。

Q4: 速率限制（Rate Limit）出現了怎麼辦？要用什麼策略處理 429 error？

Exponential backoff + Retry 是黃金標準。Gemini API 的 rate limit：(1) 免費額度：每分鐘 15 req、每天 1500 req（Flash）；(2) 付費 Tier 1：每分鐘 1000 req；(3) 付費 Tier 2–5：每分鐘 10,000–2,000,000 req，依信用度和用量升級。Python 實作：from tenacity import retry, stop_after_attempt, wait_exponential; @retry(stop=stop_after_attempt(5), wait=wait_exponential(multiplier=1, min=2, max=60)) def call_gemini(): response = model.generate_content(...); return response。或用 Google 原生的 google.api_core.retry。避免 rate limit 的預防策略：(1) caching 相同 query——identical prompt 存 Redis 60 分鐘；(2) Batch API——非即時任務用 Batch API（便宜 50%、無 rate limit）；(3) queue 化 request——用 Celery / RQ 統一排程；(4) 多 project 分流——每個 GCP project 有獨立 quota，多 project 可線性擴展（但要付費）；(5) 升級 Tier——持續用滿會自動升級，也可以提 request 加速。監控：設定 Cloud Monitoring 在「request rate 接近 limit」時告警（如 > 80% quota），提前加資源。

Q5: 處理長文件（100 頁 PDF、1 小時影片）Gemini 的 context 真的能吃下去嗎？

真的能，但要注意成本和策略。Gemini 2.0 Pro 原生支援 2M token context，相當於 約 1.5M 中文字 / 800 頁 PDF / 2 小時影片。實測範例：(1) 處理 100 頁 PDF：約 40,000 tokens，使用 genai.upload_file('report.pdf') 上傳後，直接在 prompt 裡 reference。成本：Flash 約 $0.003、Pro 約 $0.05 per query。(2) 1 小時影片分析：約 500,000 tokens（依 resolution），genai.upload_file('video.mp4')。成本：Flash 約 $0.04、Pro 約 $0.6 per query。(3) 10 本書全文：若每本 100K tokens，10 本 1M tokens，一次塞進去可行。實戰策略：(1) Context Caching 省 75%——如果要多次 query 同樣的長 document，開啟 cached_content 功能，第二次以後只收 25% 費用；(2) 不要盲目塞全文——只塞相關部分用 chunking + retrieval（RAG）在某些情境更省錢；(3) 分塊 summarize 再分析——先每章摘要 → 再整體分析，處理 > 2M tokens 文件時必要；(4) File API 重複使用——upload 一次後可多次引用，過期前都免上傳時間；(5) watch token count——model.count_tokens(prompt) 預估成本。限制：（A）上傳檔案 48 小時後過期；(B) 單 file 最大 2GB；(C) Flash context 最多 1M，Pro 最多 2M。

---

參考資料

1. Google AI for Developers — Gemini API Quickstart with Python（https://ai.google.dev/gemini-api/docs/quickstart?lang=python）
2. google-generativeai PyPI 套件（https://pypi.org/project/google-generativeai/）
3. Gemini API Cookbook — GitHub（https://github.com/google-gemini/cookbook）
4. Google AI Studio（https://aistudio.google.com）

---