CloudInsight Logo
CloudInsight
返回首頁AI API

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

19 min 分鐘閱讀
#Gemini API#Python#Google AI SDK#API 串接#多模態#程式碼範例#Function Calling#Streaming#錯誤處理#教學

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

5 分鐘內讓 Gemini API 跑起來

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

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

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

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

Python 開發者串接 Gemini API

TL;DR

安裝 google-genai 套件 → 設定 API Key → 建立 genai.Client → 呼叫 client.models.generate_content() 就完成。本教學涵蓋文字生成、圖片理解、Streaming、Function Calling，附完整可執行程式碼。

Python 環境準備與 Gemini SDK 安裝

Answer-First： 你只需要 Python 3.9+、pip，以及一行 pip install google-genai 就能開始。舊的 google-generativeai 套件已停止維護，改用 Google 官方統一的 google-genai SDK。

環境需求

項目最低需求建議版本
Python3.93.11+
pip21.0最新版
google-genai1.0.0最新版
作業系統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-genai

安裝完成後，驗證一下：

python -c "from google import 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
from google import genai

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

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

from dotenv import load_dotenv
load_dotenv()

client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))

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

Answer-First： 用 genai.Client 建立 client，呼叫 client.models.generate_content() 並指定 model 與 contents，就能取得 AI 生成的文字回應。

最基本的文字生成

import os
from google import genai

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

# 呼叫 API（在 generate_content 直接指定 model 與 contents）
response = client.models.generate_content(
    model="gemini-3.6-flash",
    contents="請用 3 個重點介紹台灣的夜市文化"
)

# 印出結果
print(response.text)

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

調整生成參數

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

from google.genai import types

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

response = client.models.generate_content(
    model="gemini-3.6-flash",
    contents="寫一首關於台北下雨天的短詩",
    config=config
)

參數建議：

場景temperaturetop_p說明
翻譯、摘要0.1-0.30.8需要準確性
一般問答0.5-0.70.9平衡創意與準確
創意寫作1.0-1.50.95需要多樣性

多輪對話

chat = client.chats.create(model="gemini-3.6-flash")

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

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

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

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

Gemini API 多模態輸入處理流程

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

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

圖片理解

import PIL.Image

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

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

print(response.text)

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

多張圖片比較

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

response = client.models.generate_content(
    model="gemini-3.6-flash",
    contents=[
        "比較這兩個產品的外觀差異",
        img1,
        img2
    ]
)

影片分析

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

video_file = client.files.upload(file="demo.mp4")

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

response = client.models.generate_content(
    model="gemini-3.6-flash",
    contents=[
        "請為這段影片生成 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 = client.models.generate_content_stream(
    model="gemini-3.6-flash",
    contents="詳細介紹 5 個台灣必去的旅遊景點"
)

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

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

Function Calling

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

from google.genai import types

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

# 把 Python 函式直接交給 SDK，啟用自動 Function Calling
chat = client.chats.create(
    model="gemini-3.6-flash",
    config=types.GenerateContentConfig(tools=[get_weather])
)
response = chat.send_message("台北今天天氣如何？")

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

錯誤處理

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

from google.genai import errors

try:
    response = client.models.generate_content(
        model="gemini-3.6-flash",
        contents="你的 Prompt"
    )
    print(response.text)
except errors.ClientError as e:
    # 4xx 請求端錯誤（例如 429 超過速率限制、400 參數錯誤、403 權限不足）
    print(f"請求錯誤（{e.code}）：{e.message}")
except errors.ServerError as e:
    # 5xx 伺服器端錯誤
    print(f"伺服器錯誤（{e.code}）：{e.message}")
except Exception as e:
    print(f"未知錯誤：{e}")

常見錯誤碼：

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

API 錯誤處理流程

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

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

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

  • API Key 安全：絕對不要 commit 到 Git，使用環境變數或 Secret Manager。更多安全管理技巧請參考 API Key 管理與安全最佳實踐
  • 成本監控：設定每日用量上限，避免意外超支。各家 API 的成本差異請參考 AI API 費用比較完整攻略
  • 模型選擇：開發測試用 Flash 系列（便宜），正式產品依品質需求選 Pro 級機種；現行在售機種與單價以 Gemini API 官方定價頁為準（Gemini 2.0 系列已於 2026-06-01 停用，不要再指定 gemini-2.0-*）
  • 速率限制：加入 exponential backoff 的重試機制

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

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

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

常見問題 FAQ

Q1: 呼叫 Gemini 該連哪個 endpoint？Google AI Studio 還是 Vertex AI？

SDK 已經統一成 google-genai，差別只在你要連哪個 endpoint。舊的 google-generativeai 已停止維護，Google 在 2025 年推出統一的 google-genai SDK 同時支援兩個後端，新專案一律用它。(1) Google AI Studio endpoint（推薦入門）——client = genai.Client(api_key='YOUR_API_KEY')，呼叫 generativelanguage.googleapis.com、只需 API key 認證、最適合個人 / 原型開發；範例：client.models.generate_content(model='gemini-3.6-flash', contents=...)。(2) Vertex AI endpoint——client = genai.Client(vertexai=True, project='my-project', location='us-central1')，需要 GCP 帳號和 Application Default Credentials、適合企業 production。選擇原則：(A) 個人 / 學習 / 原型 → AI Studio endpoint；(B) 公司商業產品、需要 audit log、資料保護 → Vertex AI endpoint；(C) 已在 GCP、想用 IAM 統一管理 → Vertex AI endpoint。遷移注意：同一套 google-genai SDK，兩個 endpoint 只差在 genai.Client() 初始化參數，generate_content() 呼叫完全相同，切換只需改一行。

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

Gemini SDK 支援 streaming，結合 SSE（Server-Sent Events）送給前端最常見。Python 實作：response = client.models.generate_content_stream(model='gemini-3.6-flash', contents=prompt) → 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 依帳號的使用層級（Tier）而定，Google 目前不公佈固定數字：實際的每分鐘請求數與每日上限請查官方 Rate Limits 文件，或登入 AI Studio 的 rate limit 頁面查自己帳號的即時額度。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 = client.models.generate_content(model='gemini-3.6-flash', contents=...); return response。或用 Google 原生的 google.api_core.retry。避免 rate limit 的預防策略：(1) caching 相同 query——identical prompt 存 Redis 60 分鐘；(2) Batch API——非即時任務改走 Batch API（折扣與額度以官方定價頁為準）；(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 現行機種都提供長 context，實際上限依機種而異（以官方模型文件為準），100 頁 PDF、1 小時影片都可以一次餵進去。做法：client.files.upload(file='report.pdf') 上傳後直接在 prompt 裡 reference，影片同理用 client.files.upload(file='video.mp4')。成本怎麼抓：長文件和影片的 token 量很大（例如 1 小時影片依解析度可到數十萬 token），費用＝token 量 × 該機種單價；單價請查 Gemini API 官方定價頁，並在上線前用 client.models.count_tokens(model='gemini-3.6-flash', contents=prompt) 實際估一次，不要憑感覺。實戰策略：(1) Context Caching——要對同一份長文件多次 query 時開啟 cached_content，快取命中的折扣以官方定價頁為準；(2) 不要盲目塞全文——只塞相關部分、用 chunking + retrieval（RAG）在某些情境更省錢；(3) 分塊 summarize 再分析——先每章摘要 → 再整體分析，超過單次 context 上限時必要；(4) File API 重複使用——upload 一次後可多次引用，過期前免重傳；(5) watch token count——每次改 prompt 都重估。限制（以官方 File API 文件為準）：上傳檔案有保存期限、單一檔案有大小上限，不同機種的 context 上限也不同。

參考資料

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

需要專業的雲端建議？

無論您正在評估雲平台、優化現有架構，或尋找節費方案，我們都能提供協助

預約免費諮詢

相關文章

AI API

OpenAI API 串接教學｜2026 年 Python SDK 從零開始完整指南

2026 年 OpenAI API Python SDK 串接完整教學。從安裝 SDK、取得 API Key 到實作文字生成、圖片分析和 Function Calling，附完整程式碼範例。

AI API

AI API 入門教學｜2026 年從零開始學會串接 OpenAI、Claude、Gemini API

2026 年 AI API 入門教學！從 API 基礎概念、串接教學到實戰練習，手把手帶你學會使用 OpenAI、Claude、Gemini API。

AI API

Gemini API 是什麼？2026 最新 Google Gemini API 串接、定價與開發完整指南

2026 年最完整 Gemini API 開發指南。詳解 Google Gemini API 申請流程、Python 串接教學、模型版本比較、Token 定價與企業應用案例，助你快速上手 AI 開發。