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
• 报错时看报错速查