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 官方帳號即時獲得技術支援。

---

參考資料

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）

---