本文根據 Gemini API 官方文檔（Quickstart、Interactions API、Text generation、Files API、Libraries）和官方 SDK 倉庫 googleapis/python-genai 整理，資料核對於 2026-10-10。示例代碼基於官方示例改寫並加了中文註釋；模型 ID 更新很快，以官方 Models 頁為準。
適用於誰
- 會一點 Python，想在腳本或後端裏調用 Gemini 的開發者；
- 搜「gemini api python」「python sdk」「python 調用」的人；
- 看過舊教學裏的
google.generativeai或generate_content，不確定現在該用哪種寫法的人。
還沒有密鑰的，先看本站《Gemini API Key 怎麼獲取：在 AI Studio 創建密鑰、設定環境變量與安全限制》。
結論先說
- 官方 SDK 是
google-genai：pip install -U google-genai，導入寫from google import genai。舊的google-generativeai包已棄用，不再提供新功能。 - 官方現在預設推薦 Interactions API：
client.interactions.create(model=..., input=...)，回覆文本在interaction.output_text。官方說明它自 2026 年 6 月起正式可用（GA），建議所有新項目使用。 - 舊的 generateContent 寫法仍然完全受支持，官方稱它為 legacy（舊版）接口，老項目不用急着改。
- 多輪對話可以讓伺服器記歷史：把上一輪的
interaction.id傳給previous_interaction_id即可；但系統指令和生成參數每一輪都要重新傳。 - 密鑰放環境變量
GEMINI_API_KEY，SDK 自動讀取。
一、安裝與配置
bash
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -U google-genai
export GEMINI_API_KEY="你的API密鑰" # Windows PowerShell: $env:GEMINI_API_KEY="你的API密鑰"- Python 版本：SDK 倉庫要求 3.10 及以上。
- 官方說明 Interactions API 需要
google-genai2.3.0 及以上版本，裝最新版即可。 - 環境變量
GEMINI_API_KEY和GOOGLE_API_KEY都能被自動識別，兩個都設時後者優先。
二、第一個請求
新建 quickstart.py：
python
from google import genai
client = genai.Client() # 自動讀取環境變量裏的密鑰
interaction = client.interactions.create(
model="gemini-3.8-flash",
input="用三句話解釋什麼是向量數據庫",
)
print(interaction.output_text)運行 python quickstart.py。幾個要點：
output_text是 SDK 提供的便捷屬性，直接給出最終文本；- 完整結果在
interaction.steps裏，是一個按時間排列的「步驟」列表，包括模型的思考（thought）、工具調用和最終輸出（model_output）； - 模型 ID 用官方 Models 頁列出的名字。截至 2026-10-10，最新的穩定版文本模型是
gemini-3.8-flash，更便宜的是gemini-3.5-flash-lite，gemini-3.1-pro-preview是預覽版。
三、系統指令與思考等級
python
interaction = client.interactions.create(
model="gemini-3.8-flash",
system_instruction="你是一名耐心的 Python 老師，用中文回答，並配一個最小可運行的例子。",
input="列表推導式怎麼用？",
generation_config={
"thinking_level": "low", # gemini-3.8-flash 可選 low / medium / high，預設 medium
},
)
print(interaction.output_text)- Gemini 3 系列預設開啟思考。想更快、更省，把
thinking_level調低；複雜推理再調高。Gemini 3.8 Flash 不支持minimal。 - 舊教學裏常見的
temperature、top_p、top_k：官方說明從 Gemini 3.6 Flash、3.5 Flash-Lite 起已棄用並被忽略，新代碼不要再傳。 - 系統指令的寫法見本站《Google AI Studio 系統指令怎麼寫：System instructions 與運行設定（思考等級、溫度、聯網搜尋）》。
四、流式輸出
加上 stream=True，返回的是一串事件，文本片段在 step.delta 事件裏：
python
stream = client.interactions.create(
model="gemini-3.8-flash",
input="寫一段 200 字左右的秋天散文",
stream=True,
)
for event in stream:
if event.event_type == "step.delta" and event.delta.type == "text":
print(event.delta.text, end="", flush=True)
print()流裏還會有 interaction.created、step.start、step.stop、interaction.completed 等事件，只想顯示文字時按上面這樣過濾就夠了。
五、多輪對話
方式一：伺服器儲存歷史（官方推薦）
python
first = client.interactions.create(
model="gemini-3.8-flash",
input="我家裏有 2 只狗。",
)
print(first.output_text)
second = client.interactions.create(
model="gemini-3.8-flash",
input="那我家一共有多少隻爪子？",
previous_interaction_id=first.id, # 接上一輪
)
print(second.output_text)要知道的三件事：
previous_interaction_id只帶上對話歷史。system_instruction、generation_config、tools只對當次請求生效，每一輪都要重新傳。- 預設
store=true，交互記錄會儲存在伺服器上：官方寫明免費層保留 1 天，付費層保留 55 天，到期自動刪除，也可以調用刪除接口提前刪。過了保留期的對話就接不上了。 - 官方說這種方式更容易命中隱式緩存，有助於降低多輪對話的成本。
方式二：自己管理歷史（無狀態）
不想把對話存在伺服器上，就設 store=False，每次把完整歷史傳過去。官方強調：模型返回的所有步驟（包括 thought 思考步驟）必須原樣放回歷史裏，不能刪改，因為裏面帶有延續推理所需的簽名。
python
history = [
{"type": "user_input", "content": [{"type": "text", "text": "我家裏有 2 只狗。"}]}
]
first = client.interactions.create(model="gemini-3.8-flash", store=False, input=history)
for step in first.steps: # 把模型返回的步驟原樣追加
history.append(step.model_dump())
history.append(
{"type": "user_input", "content": [{"type": "text", "text": "一共有多少隻爪子？"}]}
)
second = client.interactions.create(model="gemini-3.8-flash", store=False, input=history)
print(second.steps[-1].content[0].text) # 官方示例的取法：最後一個步驟裏的文本六、傳圖片和文件
先用 Files API 上載，再把文件地址放進 input：
python
uploaded = client.files.upload(file="photo.jpg")
interaction = client.interactions.create(
model="gemini-3.8-flash",
input=[
{"type": "text", "text": "這張圖裏有什麼？用中文描述。"},
{"type": "image", "uri": uploaded.uri, "mime_type": uploaded.mime_type},
],
)
print(interaction.output_text)小圖片也可以不上載，讀成 base64 後用 {"type": "image", "data": 圖片的base64字符串, "mime_type": "image/jpeg"} 直接放進請求。官方給出的邊界：
- 整個請求（文件、提示詞、系統指令加在一起）超過 100 MB 時必須用 Files API，PDF 的界限是 50 MB；
- Files API 每個項目可存 20 GB，單個文件最大 2 GB，文件儲存 48 小時後自動刪除；
- Files API 本身不收費，在 Gemini API 可用的地區都能用。
同樣的寫法可以傳音頻（"type": "audio"）等其他類型，Gemini 3.8 Flash 支持文本、圖片、影片、音頻和 PDF 輸入。
七、看 token 用量
python
print(interaction.usage) # 含輸入、輸出、思考 token 數
# 發送前先估算輸入 token
count = client.models.count_tokens(model="gemini-3.8-flash", contents="你好，世界")
print(count.total_tokens)官方說明開啟思考時，輸出費用按「輸出 token + 思考 token」計算，思考 token 數在 interaction.usage.total_thought_tokens。統計 token 的請求本身不計費。
八、報錯和重試
- 官方排錯頁說明，Python SDK 預設會對超時、網絡問題、429 和 5xx 這類暫時性錯誤自動重試，最多 4 次，首次等待約 1 秒，最長 60 秒。
- 400、402、403 這類錯誤重試沒有用，要先解決問題本身（參數寫錯、預付餘額用完、密鑰無權限）。
- 遇到 429 的完整排查方法見本站《Gemini API 429 錯誤怎麼解決：RESOURCE_EXHAUSTED 的原因與 400 / 403 / 503 排查表》。
九、舊寫法 generateContent 還能用嗎
能用。官方的說法是 generateContent 現在屬於 legacy 接口，但仍然完全受支持；同時也說明今後新模型、新工具和智能體功能會先在 Interactions API 上線。舊寫法長這樣：
python
response = client.models.generate_content(
model="gemini-3.8-flash",
contents="用三句話解釋什麼是向量數據庫",
)
print(response.text)
chat = client.chats.create(model="gemini-3.8-flash") # SDK 在本地幫你記歷史
print(chat.send_message("我家裏有 2 只狗。").text)反過來，有幾項功能官方寫明目前只有 generateContent 支持：Batch API、Python 的自動函數調用、顯式上下文緩存、自定義安全設定。用到這些就繼續用舊接口。
如果你的代碼裏還是 import google.generativeai as genai，那是更早的舊 SDK，官方已在 2025 年 11 月 30 日棄用，建議按遷移指南換到 google-genai。
常見問題
Q：報找不到模型（404）？
檢查模型 ID 是否和官方 Models 頁一致。預覽版模型的名字帶 -preview 後綴，下線後會直接不可用，下線時間表在官方 Deprecations 頁。
Q：能在 Jupyter / Colab 裏用嗎？
能。官方提醒 Colab 的地區限制按 Colab 實例所在的地區判斷，而不是按用戶所在地。
Q：免費能調用嗎？
項目沒綁定結算帳號時處於免費層，可以免費調用部分模型，但有速率限制，而且提交的內容會被 Google 用於改進產品。詳見本站《Gemini API 免費額度是多少：免費層級、RPM / TPM / RPD 速率限制與限額查詢》。
Q：Gemini API 在哪些地區可用？
以官方 Available regions 頁面的列表為準，目前沒有列出中國大陸。請遵守所在地法律和服務條款。
參考資料
- Gemini API quickstart（官方）：https://ai.google.dev/gemini-api/docs/quickstart
- Gemini API quickstart（generateContent 版，官方）：https://ai.google.dev/gemini-api/docs/generate-content/quickstart
- Interactions API（官方）：https://ai.google.dev/gemini-api/docs/interactions-overview
- Text generation（官方）：https://ai.google.dev/gemini-api/docs/text-generation
- Gemini API libraries（官方）：https://ai.google.dev/gemini-api/docs/libraries
- Migrate to the Google GenAI SDK（官方）：https://ai.google.dev/gemini-api/docs/migrate
- Files API（官方）：https://ai.google.dev/gemini-api/docs/files
- Gemini thinking（官方）：https://ai.google.dev/gemini-api/docs/thinking
- Understand and count tokens（官方）：https://ai.google.dev/gemini-api/docs/tokens
- Models（官方）：https://ai.google.dev/gemini-api/docs/models
- Gemini deprecations（官方）：https://ai.google.dev/gemini-api/docs/deprecations
- Troubleshooting guide（官方）：https://ai.google.dev/gemini-api/docs/troubleshooting
- googleapis/python-genai（官方 SDK 倉庫）：https://github.com/googleapis/python-genai
需要開通或續費？谷歌帳號 →
0 條評論
還沒有評論，來搶沙發～