Gemini 對話

兩種 Gemini 套餐分組的可用參數不同，接入前請先看下方「兩個分組的差異」。

第一個請求

Gemini 對話模型可以用 OpenAI Chat Completions、OpenAI Responses 與 Anthropic Messages 三種協議調用，下面以 Chat Completions 為例。鑑權用 Authorization: Bearer sk-你的金鑰，也接受 x-api-key。

curl https://api.hop-base.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的金鑰" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "messages": [{"role": "user", "content": "你好"}]
  }'

不同套餐分組可用的 Gemini 型號可能不同。請先用當前金鑰調用 GET /v1/models，只使用實際返回的完整 ID。

不支援 x-goog-api-key 與 /v1beta/models/{model}:generateContent。兩個 Gemini 分組都可用 /v1/chat/completions、/v1/responses 與 /v1/messages；「Gemini 官方直連」另提供 /v1/messages/count_tokens（本地估算，不計費）。兩組在各協議下的細節不同，見下方「兩個分組的差異」。

可用模型

推薦順序：日常預設使用 gemini-3.8-flash；所有 ID 含 preview 的型號均按預覽版使用，不作穩定性承諾。

不同套餐分組的價格不同，以當前金鑰所屬分組及登入後「模型廣場」為準。

兩個分組的差異

「Gemini 全系（含生圖）」的結構化輸出支援 response_format 的 json_object 與 json_schema。

「Gemini 官方直連」：Chat Completions 參數

• messages：內容分片支援 text、image_url、input_audio、file、refusal，其他類型返回 400。image_url 只接受 base64 data URL；file 的 file_data 須為 data URL，不支援 file_id。role: "tool" 的結果作為函式結果送給模型。
• tools / tool_choice：tool_choice 支援 auto、none、required、指定函式與 allowed_tools；支援並行工具調用與多輪。parallel_tool_calls: false 時只保留第一個調用。舊版 functions / function_call 也相容。工具參數 schema 按完整 JSON Schema 接收，$ref、$defs、anyOf、additionalProperties 等無需改寫。
• response_format：支援 json_object 與 json_schema。
• stop：字串或陣列。n：1–8，返回同等數量的 choices。
• max_tokens / max_completion_tokens：同時傳時以 max_tokens 為準；思考 token 計入此上限，建議不低於 4096。
• temperature / top_p：按模型官方範圍原樣轉發；seed、top_k 也支援。
• presence_penalty / frequency_penalty：為 0 時忽略；非 0 時原樣下發，目前 Gemini 型號會返回 400 Penalty is not enabled for this model。
• reasoning_effort：換成思考預算，見下方「思考」。
• 返回 400 的欄位：logprobs、top_logprobs、logit_bias、modalities、audio、web_search_options（modalities 僅在含 text 以外的取值時報錯）。
• 忽略且不影響輸出的欄位：user、metadata、store、service_tier、safety_identifier、prompt_cache_key、stream_options、prediction、verbosity。

通用欄位說明見 API 參考 Chat Completions。

「Gemini 官方直連」：Responses 與 Anthropic Messages

• 工具：支援 function 工具與 custom 自由文字工具（如 Codex 的 apply_patch）；內建 / 託管工具（web_search、file_search、code_interpreter、computer 等）返回 400。tool_choice 取值同 Chat Completions；max_tool_calls 會截斷調用數。
• 無狀態：previous_response_id、conversation、background、prompt 範本與 item_reference 返回 400。每次請求都要在 input 裡帶完整歷史（Codex 預設即如此）。
• 結構化輸出用 text.format。
• 忽略且不影響輸出的欄位：store、include、user、metadata、safety_identifier、prompt_cache_key、service_tier、truncation、text.verbosity。

• Base URL 填 https://api.hop-base.com（不帶 /v1）。Claude Code 可經 CC Switch 直連，模型名須填 Gemini 型號 ID（如 gemini-3.8-flash），claude-* 名字不會自動對應。
• tool_choice 支援 auto、any、tool、none；disable_parallel_tool_use: true 時只保留第一個調用。
• image / document 只接受 base64 來源，url 來源返回 400；tool_result 可以帶圖片。
• 結構化輸出用 output_format 或 output_config.format（json_schema）。
• /v1/messages/count_tokens 為本地估算，不計費。
• 忽略且不影響輸出的欄位：metadata、service_tier、cache_control、context_management。

思考簽名（工具調用多輪）

Gemini 3 及以上型號的工具調用會帶「思考簽名」，在各協議裡的位置：

下一輪把助手訊息原樣帶回即可。用戶端丟了這些欄位也不會報錯：網關會盡量找回，找不回則按官方方式跳過校驗，推理連貫性可能略有下降。

串流輸出（SSE，加 "stream": true）

curl https://api.hop-base.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的金鑰" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-3.1-pro-preview", "stream": true,
    "messages": [{"role": "user", "content": "你好"}]}'

「Gemini 官方直連」分組的三個協議都支援 "stream": true，事件格式分別符合 OpenAI Chat Completions、OpenAI Responses 與 Anthropic Messages 規範，含工具調用的增量。串流可能在整段生成完畢後才集中分塊下發，首塊到達時間約等於完整生成時間，三個協議都是如此。Chat Completions 的最後一塊固定帶 usage。

「Gemini 全系（含生圖）」分組是逐字串流，需要用量時加 stream_options.include_usage。

非串流回應的 usage 裡帶本次扣費：cost_usd 為從餘額實際扣除的美元金額，cost 為同一筆的人民幣金額，currency 為 cost 的幣別（恆為 CNY）；回應標頭 X-HopBase-Cost / X-HopBase-Cost-USD / X-HopBase-Currency 同值；串流回應都不帶，扣費請到主控台「使用記錄」查看。見扣費說明。

思考（Thinking）

Gemini 模型預設開啟思考且無法完全關閉，思考 token 計入輸出上限。max_tokens 設得太小會出現 finish_reason=length 而正文只有幾個字，建議不低於 4096。

OpenAI 格式下思考 token 已包含在 completion_tokens 裡，另在 completion_tokens_details.reasoning_tokens 單列（「Gemini 官方直連」的 Responses 在 output_tokens_details.reasoning_tokens）。原生格式在 usageMetadata.thoughtsTokenCount 單列。

「Gemini 官方直連」分組把 reasoning_effort 換成思考預算：

gemini-4-argon 只接受思考檔位，不按上表換算：none / minimal → low，medium → medium，high → high；low 與不傳一樣按模型預設檔位。無法完全關閉思考。

Responses 開啟 reasoning.summary 時返回 reasoning 摘要；Anthropic Messages 的 thinking.type 為 enabled 或 adaptive 時返回 thinking 塊，budget_tokens 超過 24576 時按 24576 截斷。

「Gemini 官方直連」的計費口徑：思考 token 計入輸出；內建工具回灌給模型的 token（toolUsePromptTokenCount）計入輸入。usage 按各協議的標準形態返回，其中 Anthropic Messages 的 input_tokens 不含快取讀取，快取讀取在 cache_read_input_tokens。

「Gemini 全系（含生圖）」分組傳 none 可明顯減少思考量。

Gemini 原生格式透傳

從 Gemini SDK 遷移的存量請求體可以直接送：「Gemini 官方直連」分組的同一端點也接受 Gemini 原生 contents 欄位，回程按原生結構返回。

curl https://api.hop-base.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的金鑰" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "contents": [{"role": "user", "parts": [{"text": "你好"}]}]
  }'

原生格式只接受官方的頂層欄位：

contents, systemInstruction, generationConfig, safetySettings, tools,
toolConfig, cachedContent, labels, serviceTier, model

出現 store、max_tokens、messages 等其他欄位會返回 400 Unknown name …。原生格式不支援串流，請勿帶 "stream": true。

下一步

• Gemini 生圖（Banana）見圖片生成 API
• 報錯時看報錯速查