Gemini 參數與協定差異

使用 Gemini 模型時，根據本頁調整思考、工具和快取設定。完整結構參閱 Generate Content、Stream Generate Content 和 Chat Completions；普通與流式原生請求共用下方規則。

適用模型

模型	使用要點
gemini-4-argon	原生思考檔位為 `LOW/MEDIUM/HIGH`，預設 `MEDIUM`；僅支援隱式快取，長輸出通過續寫完成
gemini-3.8-flash	同樣使用三檔思考，預設 `MEDIUM`，不支援原生 `MINIMAL`；支援隱式與顯式快取
gemini-3.7-flash	同樣使用三檔思考，預設 `MEDIUM`，不支援原生 `MINIMAL`。Google Developer API 已將此型號標記為棄用並轉向 3.8；這是原廠對應服務的安排，不表示平台已下線或自動替換該型號

Generate Content 差異

欄位	差異說明
`thinkingConfig.thinkingLevel`	三款均不能用 `MINIMAL` 或舊式零預算關閉思考；降低深度使用 `LOW`，不要套用 Gemini 2.5 的關閉方式
`thinkingConfig.thinkingBudget`	新接入使用 `thinkingLevel`，兩者不能同時傳入。Argon 的 Gemini Developer API 將單獨傳入的舊預算映射到最近檔位並給出警告
`temperature/topP/topK`	這些型號忽略舊採樣設定；無需傳入，無法通過這些欄位調整採樣
`candidateCount`	Gemini 3 及後續型號不支援該設定，應從請求中移除
`frequencyPenalty/presencePenalty`	Google Cloud 的 3.7 Flash 指南明確說明傳入會報錯；與上方採樣參數的靜默忽略行為不同
`thinkingConfig.includeThoughts`	開啟後可通過 `parts[].thought` 區分思考摘要與回答；摘要不是原始思考，也不能代替簽名回傳
`parts[].thoughtSignature`	完整、原樣保留回傳的 Parts；工具呼叫歷史必須回傳簽名，不要合併有簽名和無簽名的內容區塊
`functionCall/functionResponse`	函數結果的 `id`、`name` 與實際呼叫逐一匹配，不能遺漏或錯配並行工具結果
model 預填充	不以未完成的 model 消息結尾；3.8 還要求最終用戶輪次包含非空文字
`maxOutputTokens`	包含思考與回答。Argon 直接 REST 非流式單次上限為 `32768`，流式單次上限為 `65536`；超過單次上限需續寫，不能只增大數字就視為一次回傳
`continuationToken`	本頁僅 Argon 使用長輸出續寫：`CONTINUATION` 時保留原輸入、工具和總預算，傳入最新令牌；`MAX_TOKENS` 後繼續時，提高預算至已用 Token 數以上。不要把中間輸出追加到 `contents`

Chat Completions 差異

以下規則來自 Google 官方 Chat 兼容層，不代表所有平台渠道採用相同轉換方式。

欄位	差異說明
`reasoning_effort`	本頁型號使用 `low/medium/high`，預設 `medium`；Argon 還兼容 `minimal`，並將其映射為 `low`
`extra_body.google.thinking_config`	用於傳入 Gemini 思考設定，如 `thinking_level` 與 `include_thoughts`；不能與 `reasoning_effort` 同時設定
`tool_calls[].extra_content`	保留其中的 `google.thought_signature`，並連同完整工具呼叫歷史回傳；只保留函數名稱和參數會丟失簽名
`response_format`	可使用官方支援的 JSON 結構化輸出；Schema 按 Gemini 支援的子集編寫，不等同於支援 OpenAI 的全部 Schema 行為。原生格式設定使用 Generate Content Reference 中的欄位
長輸出續寫	Google 官方 Chat 兼容入口不支援長輸出續寫；需要續寫時使用原生 Generate Content 或 Stream Generate Content

快取差異

欄位	差異說明
隱式快取	預設啟用，無需額外開關；Argon、3.8 Flash 的最小輸入前綴為 `4096` 個 Token，仍需前綴一致，不保證命中
`cachedContent`	Argon 不支援顯式快取，創建或引用會報錯；3.8 Flash 支援。3.7 Flash 在 Google Cloud 服務中也支援顯式快取
Chat 快取引用	Google 兼容層通過 `extra_body.google.cached_content` 引用原生快取；不使用 OpenAI 的 `prompt_cache_options`，Argon 也不會因改用 Chat 獲得顯式快取能力
快取用量	原生查看 `usageMetadata.cachedContentTokenCount`；實際回傳的快取用量用於判斷命中，不能僅憑開啟設定判斷

媒體輸入差異

輸入	協定內容區塊	差異說明
圖片	原生 `inlineData`	使用 Base64 數據並填寫正確的 `mimeType`
檔案	原生 `fileData`	可用於圖片、音訊、影片和 PDF；填寫伺服器端可讀取的資源 URI，不將本地檔案路徑當作 URI；原廠 Files 引用須來自對應檔案服務
圖片	Chat `image_url`	使用官方支援的圖片 URL 或 Base64 Data URL，不套用原生 Parts 結構
音訊	Chat `input_audio`	官方範例使用 Base64 音訊和 `format`；不要把它當作音訊生成設定

欄位	差異說明
`mediaResolution`	控制輸入媒體的處理精度；請求級與單個 Part 的設定按各自結構填寫，單個媒體設定可覆蓋請求級設定，不代表輸出圖片分辨率
`responseModalities`	三款型號僅輸出文字，使用 `TEXT`；通用 Schema 中的 `IMAGE/AUDIO`、`imageConfig` 和 `speechConfig` 不用於這些型號的圖像、語音生成

呼叫範例

將 MODEL_ID 替換為平台提供的完整模型 ID。兩個範例均使用中檔思考和明確的輸出預算，不自動執行續寫。

curl 'https://api.agtcloud.cn/v1beta/models/MODEL_ID:generateContent' \
  -H 'Authorization: Bearer your-api-key' \
  -H 'Content-Type: application/json' \
  --data '{
    "contents": [{"role": "user", "parts": [{"text": "用三點說明如何排查 API 逾時"}]}],
    "generationConfig": {
      "thinkingConfig": {"thinkingLevel": "MEDIUM"},
      "maxOutputTokens": 32768
    }
  }'