Gemini API 參考文件¶
Gemini API 為 Gemini 模型與受管理代理提供單向 REST、串流與即時 WebSocket 端點。新專案建議從 Interactions API 開始,或依照 開始使用指南 送出你的第一個要求。
用戶端程式庫與編輯器工具請參閱 SDK 參考文件、 Gemini API 程式庫 或 程式設計代理設定。
最新版 Gemini API SDK 預設使用 API 版本 v1。部分功能(例如
Live API 與語音生成)僅在 v1beta 提供,請參閱
API 版本。
基礎 URL 與驗證¶
驗證方式:將你的 API 金鑰 放在 x-goog-api-key
標頭中傳遞(使用 SDK 時則設定 GEMINI_API_KEY)。
呼叫端點:將 HTTPS 要求送往
https://generativelanguage.googleapis.com/{version}/{endpoint},
版本使用 v1beta 或 v1。
| 設定 | 值 |
|---|---|
| Base URL | https://generativelanguage.googleapis.com |
| WebSocket | wss://generativelanguage.googleapis.com/ws/... |
| 驗證 | x-goog-api-key: $GEMINI_API_KEY |
| 版本 | v1beta(新功能與代理)、v1(穩定版) |
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3.8-flash",
"input": "Explain how TCP congestion control works in two sentences."
}'
# Set up your coding agent with these tools
# Search live docs with the MCP server
npx add-mcp "https://gemini-api-docs-mcp.dev"
# Add skills for current SDK syntax and rules
npx skills add google-gemini/gemini-skills --skill gemini-api-dev
# In Antigravity, install both with one plugin
agy plugin install https://github.com/google-gemini/gemini-skills
# Fetch any reference page as clean Markdown
curl -H "Accept: text/markdown" \
"https://aistudio.google.com/api-reference/interactions-api"
API 端點¶
從下方的核心介面開始、依類別瀏覽端點,或在 All methods 一頁中檢視每一個 REST 操作。
POST /v1beta/interactions
文字、多模態提示詞、思考、工具、有狀態輪次與代理的預設端點。
WSS BidiGenerate*
低延遲 WebSocket 工作階段,適用於即時語音、影片與互動式 Lyria 音樂。
POST /v1beta/agents
設定可重複使用的代理、佈建沙箱、排程 cron 執行,以及註冊 webhook。
/api-reference/all-methods
單頁索引,列出所有 Gemini API 服務的每一個 REST 操作。
| API | 端點 | 說明 |
|---|---|---|
| Interactions API | POST /v1beta/interactions |
文字、多模態提示詞、思考、工具、有狀態輪次、背景工作與 SSE 串流。 |
| Live API | WSS BidiGenerateContent |
低延遲 WebSocket 工作階段,適用於雙向語音、影片與工具呼叫。 |
| Live Music API | WSS BidiGenerateMusic |
即時 WebSocket 工作階段,用來操控互動式器樂音樂與 Lyria。 |
| Models API | GET /v1beta/models |
列出模型、檢視權杖上限,或執行媒體預測(predict、predictLongRunning)。 |
| API | 端點 | 說明 |
|---|---|---|
| Agents | POST /v1beta/agents |
建立、擷取、列出與刪除可重複使用的代理設定。 |
| Environments | POST /v1beta/environments |
佈建隔離的遠端沙箱,並管理代理執行所需的工作區檔案。 |
| Triggers | POST /v1beta/triggers |
排程週期性的 cron 執行,或依需求呼叫代理觸發器。 |
| Webhooks | POST /v1beta/webhooks |
註冊背景事件的回呼 URL,並輪替簽署密鑰。 |
| Credentials | POST /v1beta/credentials |
儲存並管理代理與工具使用的外部服務憑證。 |
| API | 端點 | 說明 |
|---|---|---|
| Files API | POST /v1beta/files |
上傳並管理提示詞使用的大型音訊、圖片、影片與文件檔案。 |
| File Search | POST /v1beta/fileSearchStores |
將文件分塊、建立索引並查詢,用於受管理的檢索接地。 |
| Caching | POST /v1beta/cachedContents |
在支援的模型上固定共用的提示詞上下文,降低重複輸入的成本。 |
| Voices | POST /v1beta/voices |
建立並管理文字轉語音用的自訂提示或複製聲音。 |
| Batch API | POST /v1beta/batches |
以較低成本提交非同步的內容生成與嵌入工作。 |
| Embeddings | POST /v1beta/models/{model}:embedContent |
產生向量嵌入,用於語意搜尋、分類與分群。 |
| Tokens | POST /v1beta/models/{model}:countTokens |
在送出要求前計算輸入權杖數。 |
新專案請使用 Interactions API,或依照 遷移指南。既有的整合仍可使用 下列端點。
| API | 端點 | 說明 |
|---|---|---|
generateContent |
POST /v1beta/models/{model}:generateContent |
供既有 generateContent 整合使用的單向文字與多模態生成。 |
streamGenerateContent |
POST /v1beta/models/{model}:streamGenerateContent |
供既有 generateContent 整合使用的伺服器送出事件串流。 |
createToken |
POST /v1alpha/auth_tokens |
為用戶端 Live API 工作階段佈建短期臨時驗證權杖。 |
SDK 參考文件¶
官方 Google GenAI SDK 的用戶端、方法與型別文件(自動產生)。
pip install google-genai
google-genai Python SDK 的參考文件,包含同步與非同步用戶端。
npm install @google/genai
@google/genai SDK(Node.js 與 TypeScript)的參考文件。
go get google.golang.org/genai
google.golang.org/genai 在 pkg.go.dev 上的套件參考文件。
com.google.genai:google-genai
com.google.genai Java SDK 的 Javadoc 參考文件。
dotnet add package Google.GenAI
Google.GenAI .NET SDK 的參考文件。
/docs/libraries
安裝 SDK 套件、設定環境變數,或從舊版程式庫遷移。