Gemini SDK

使用 Google Gen AI Python 或 TypeScript SDK 呼叫 AGTCloud Gemini Generate Content 相容介面。

Google Gen AI SDK 提供 Python 和 TypeScript 用戶端。透過 SDK 的自訂 HTTP 設定，可以將 Generate Content 請求傳送到 AGTCloud 的 Gemini 相容入口。

本頁只覆蓋 generateContent 與 streamGenerateContent。檔案、快取、Live API、模型管理及其他 Google 平台資源是否可用，應以 AGTCloud API Reference 為準。

準備工作

開始前，請確認你已經：

在 API Keys 頁面建立 AGTCloud API Key；
從模型廣場複製支援 Gemini Generate Content 的完整模型 ID；
準備受支援的伺服器端執行環境。目前 @google/genai 2.x 要求 Node.js 20+；升級主版本前請重新核對執行環境要求。

本頁使用 MODEL_ID 和 your-api-key 作為預留位置。請勿在瀏覽器、用戶端安裝套件或公開倉庫中儲存真實 API Key。

安裝 SDK

python -m pip install google-genai

請使用目前穩定版 google-genai 或 @google/genai。本教學需要 SDK 支援自訂 Base URL、API 版本和請求 Header；如果建構函式不辨識下文的 http_options / httpOptions，請先升級 SDK。

設定 API Key

將 API Key 儲存到伺服器端環境變數：

export AGTCLOUD_API_KEY="your-api-key"

AGTCloud 的 Gemini 相容入口使用 Bearer API Key。下面的用戶端設定會保留 Google Gen AI SDK 的請求結構，並明確新增 Authorization: Bearer ... Header。

Google Gen AI SDK 仍要求初始化 api_key / apiKey，因此 SDK 還會附帶 x-goog-api-key。該 Header 來自 SDK，不替代 AGTCloud 使用的 Bearer Header。

建立用戶端並傳送請求

Base URL 使用本頁顯示的 API Origin，不要追加 /v1、/v1beta 或完整業務路徑。SDK 會根據 api_version / apiVersion 與模型方法串接 /v1beta/models/{model}:generateContent。

import os

from google import genai
from google.genai import types

api_key = os.environ["AGTCLOUD_API_KEY"]

client = genai.Client(
    api_key=api_key,
    http_options=types.HttpOptions(
        base_url="https://api.agtcloud.cn",
        api_version="v1beta",
        headers={"Authorization": f"Bearer {api_key}"},
    ),
)

response = client.models.generate_content(
    model="MODEL_ID",
    contents="請用三句話介紹你自己。",
)

print(response.text)

這是 AGTCloud 的相容串接設定

Google Gemini API 的一般 API Key 流程與 AGTCloud Bearer 身分驗證不同。這裡透過官方 SDK 提供的自訂 HTTP 選項設定 AGTCloud API Origin、v1beta 版本和 Authorization Header，不應省略這些設定。

先驗證目前 SDK 與閘道的 Header 相容性

官方 SDK 會同時傳送 Authorization 和 x-goog-api-key。如果最小文字請求傳回身分驗證或 Header 驗證錯誤，請不要刪除 Bearer Header，也不要把真實 Key 寫入其他欄位；可先使用 Gemini Generate Content API Reference 中的 HTTP 呼叫方式，並在確認目前 SDK 與閘道相容後再切換。

串流輸出

import os

from google import genai
from google.genai import types

api_key = os.environ["AGTCLOUD_API_KEY"]

client = genai.Client(
    api_key=api_key,
    http_options=types.HttpOptions(
        base_url="https://api.agtcloud.cn",
        api_version="v1beta",
        headers={"Authorization": f"Bearer {api_key}"},
    ),
)

for chunk in client.models.generate_content_stream(
    model="MODEL_ID",
    contents="請簡要解釋什麼是向量檢索。",
):
    if chunk.text:
        print(chunk.text, end="", flush=True)

串流方法會持續傳回 Generate Content 回應片段。正式環境應處理連線中斷、逾時、空文字區塊和請求未正常結束等情況。

常見問題

現象	檢查項
`401` 或 `403`	確認 `AGTCLOUD_API_KEY` 已載入、自訂 Header 包含 `Authorization: Bearer ...`，並檢查目前閘道是否接受 SDK 附帶的 `x-goog-api-key`
`404` 或路徑包含重複版本	Base URL 只填寫 `https://api.agtcloud.cn`，並把 API 版本設定為 `v1beta`
建構函式不辨識 HTTP 設定	升級至目前穩定版 `google-genai` 或 `@google/genai`
模型不可用	將 `MODEL_ID` 替換為目前 API Key 可見且支援 Gemini Generate Content 的模型 ID
傳回結構與預期不同	核對 `candidates`、`content` 和 `parts`，不要只依賴彙整後的 `response.text`
一般文字成功但進階能力失敗	核對目標模型是否支援相應的 Parts、工具呼叫或多模態輸入

不要把自訂 Gateway 能力擴大到其他 SDK 資源

本頁僅覆蓋 Generate Content 與串流生成。不要據此假設 SDK 中的檔案上傳、快取、Live API、模型清單或其他 Google 平台方法都會透過相同地址工作；其他資源是否可用，請以 AGTCloud API Reference 為準。

下一步

檢視 Gemini Generate Content API Reference瞭解 contents、parts、生成設定和完整回應結構。
檢視 Gemini Stream Generate Content API Reference瞭解串流端點與回應事件。
已有原廠 SDK 專案可以參考原廠 SDK 移轉逐項替換設定並迴歸測試。
請求失敗時，參閱驗證與 API Key和錯誤與疑難排解。