Gemini 4 Argon API：用 Python 建立原生串流對話

Gemini 4 Argon API 對話使用 Gemini 原生內容格式：contents、角色與 parts。第一筆請求很簡單，較難的是在送出追問前正確保存回應。只從可見文字重建模型回合，可能遺失附簽章的內容；將空白載入訊息加入歷史紀錄，也可能讓下一筆請求無效。

本教學使用 Python 標準函式庫與 SeedRouter 原生端點，涵蓋文字聊天和串流。完整 API 參考文件說明所有參數規格；本文則從一筆請求出發，完成可用的對話流程。

第一筆請求之前

你需要 Python 3、SeedRouter API 金鑰與足夠的帳戶餘額。將金鑰放在名為 SEEDROUTER_API_KEY 的環境變數，不要寫入原始碼或傳送給瀏覽器的程式套件。每筆送出的訊息都可能產生費用。範例不會自動重試請求，也不會自動呼叫接續生成。

模型 ID 為 gemini-4-argon，應放在端點路徑中。Google 的原生生成指南說明此格式。SeedRouter 採用 Bearer 驗證，如下所示。

傳送一筆 Gemini 4 Argon API 請求

curl --no-buffer --fail-with-body \
  'https://api.seedrouter.ai/v1beta/models/gemini-4-argon:streamGenerateContent?alt=sse' \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain a mutex in one sentence."}]}],"generationConfig":{"maxOutputTokens":1024,"thinkingConfig":{"thinkingLevel":"low"}}}'

回應是一連串伺服器傳送事件，不是單一 JSON 文件。每個 data: 事件包含原生 Gemini JSON。可見文字位於 candidates[].content.parts[].text；部分內容則包含思考或簽章。usageMetadata 可能與文字分開傳回，因此讀到最後一個事件後，才能認定答案完整。

這裡刻意使用較小的輸出預算，作為基本連通檢查。思考也會使用預算，因此回應可能不完整。處理較難的工作時，請主動提高預算；不要把不完整答案變成看不見的重試迴圈。

執行兩輪 Python 對話

下載完整 Python 範例，儲存到本機後執行：

python3 gemini-4-argon-chat.py

先問「Explain a mutex in one sentence」，再問「Give a Python example of that idea」。腳本每次請求前都會等待你輸入；輸入空白行即可結束。核心歷史紀錄規則如下：

user = {"role": "user", "parts": [{"text": text}]}
body = {"contents": [*history, user]}
history = [*history, user, {"role": "model", "parts": parts}]

可下載的腳本也會提供生成設定、解析 SSE 訊框、只顯示非思考文字，並僅在結束原因為 STOP 且 parts 非空時寫入歷史紀錄。發生 API 錯誤、串流中斷或空白答案時，先前的歷史紀錄會保持不變，不會在未提示的情況下重新送出訊息。

上述短程式片段說明資料結構；完整請求處理請執行整個檔案。非串流回應的對應操作為 generateContent；參考範例提供 cURL、Python、Node.js 與 Go 的用法。

保存原生 parts，而不是載入提示

第二筆請求應包含三個真實回合：第一則使用者訊息、完成的模型回應，以及第二則使用者訊息。介面中的「思考中……」暫存提示不是另一個模型回合。

例如 contents.3.parts: Too small: expected array to have >=1 items 錯誤，表示第四筆內容的 parts 陣列是空的；索引從零開始。改提示詞或模型前，先檢查歷史紀錄如何建立。載入提示屬於畫面狀態，絕不能在請求中成為 { "role": "model", "parts": [] }。

依順序保留所有回傳的部分，包括 thoughtSignature 與標記為思考的部分，即使介面將它們隱藏。Google 的思考簽章指南解釋了為何後續回合必須保留這些不透明欄位。不要編輯、捏造或重建簽章。原生歷史紀錄應與介面顯示的文字分開儲存。

工具對話也適用相同的保存原則，但執行工具並回傳結果，需要更完整的應用程式迴圈。這個文字範例沒有實作該迴圈，不應被當作完整的程式開發代理。

讀取用量並處理停止

對於原始請求，保留串流最新回報的用量值。同一筆請求內重複出現的是累計快照，不要把它們相加。一般輸入為 promptTokenCount 減去 cachedContentTokenCount；計費輸出包含 candidatesTokenCount 與 thoughtsTokenCount。價格指南說明如何把這些數值換算成預算。

Ctrl+C 會停止範例，且不再送出請求。停止本機讀取，不代表遠端生成沒有耗用 token。若串流在用量抵達前結束，請查閱帳戶用量紀錄。範例採保守做法，不將未完成回合加入往後的歷史紀錄；是否保存部分答案，是另一項應用程式設計決策。

長輸出接續生成又是另一種情況。CONTINUATION 結束原因表示透過接續 token 恢復原始生成，而不是一則新的使用者訊息。Google 要求保留原始請求與最新 token，不把部分輸出加進 contents。詳見長輸出接續生成指南。本入門腳本會停止，不會自動實作接續生成。

哪些項目已完成驗證？

基本文字串流生成已透過 SeedRouter Playground 通過本機端對端檢查。範例的解析與歷史紀錄行為使用合成串流測試，涵蓋附簽章的部分、空白回應與中斷。這些測試資料是在檢查軟體，不是額外呼叫模型。工具、媒體與接續生成仍需各自完成功能檢查，才能稱為已驗證的串接。

API 常見問題

可以直接把 OpenAI 模型名稱換成 gemini-4-argon 嗎？

只換名稱不會轉換訊息格式。本指南採用 Gemini 原生 contents 與 parts。請確認用戶端支援該協定，以及你設定的驗證方式與端點。

為什麼已經使用 token，答案卻是空白？

思考可能用完輸出預算，安全機制或未完成的生成也可能讓可見文字為空。請檢查結束原因與用量，不要加入空白模型回合，也不要自動重複付費請求。

百萬 token 上下文代表一百萬輸出 token 嗎？

不是。輸入、思考與輸出共用上下文。長生成也有單次請求上限，可能需要接續生成。請針對共用總量編列預算，不要視為兩份獨立的輸入與輸出額度。

對話運作正常後再增加功能

先取得完整答案，再確認第二輪收到了原始的原生內容。新增附件、工具或持久化功能時，持續將 Gemini 4 Argon API 歷史紀錄與顯示狀態分開。接著可前往模型 Playground與使用權限指南，了解互動使用與帳戶要求。