generateContent、batchEmbedContents、Imagen predict)路由 Gemini 的聊天、Responses、嵌入(Embeddings)和图片请求。如果您需要原生适配器尚未实现的兼容行为(尤其是远程 image_url 值),请切换到兼容 OpenAI 的端点。
配置
config.yaml 中配置:
当未设置按提供商的
GEMINI_API_MODE 时,USE_GOOGLE_GEMINI_NATIVE_API 仍作为旧版全局开关生效。建议使用 GEMINI_API_MODE。store: false 会作为 Gemini 的按请求退出选项转发;兼容 OpenAI 的端点没有这样的成员。
Base URL
GoModel 为原生 Gemini 和兼容 OpenAI 的 API 分别维护内部的 Base URL:- 原生聊天/模型:
https://generativelanguage.googleapis.com/v1beta - 兼容 OpenAI:
https://generativelanguage.googleapis.com/v1beta/openai
GEMINI_BASE_URL 会覆盖它们。当该值以 /openai 结尾时,GoModel 将其用于兼容 OpenAI 的客户端,并通过去掉 /openai 推导出原生 Base URL。文件和批处理始终使用兼容 OpenAI 的接口;聊天、嵌入和图片则遵循 API 模式。
嵌入
在原生模式下,嵌入通过models/{model}:batchEmbedContents 提供。dimensions 映射为 outputDimensionality,并支持 encoding_format: "base64"。原生模式会记录 Gemini 为较新模型(如 gemini-embedding-2)报告的 Token 用量。较旧的模型(如 gemini-embedding-001)以及兼容 OpenAI 的接口不报告用量,因此这些嵌入响应中的 Token 数为零。当模型按 Token 计价时,这些 Token 数为零的用量记录会被标记一条成本计算说明。
图片生成与编辑
在原生模式下,兼容 OpenAI 的图片端点可用于 Gemini 图片模型(gemini-2.5-flash-image、gemini-3.1-flash-image、gemini-nano-banana-2.1 等,通过 generateContent)。当模型未返回图片时,错误会携带 Gemini 的结束原因和消息(例如 IMAGE_RECITATION)。Google 已于 2026 年 8 月从 AI Studio API 中下线 Imagen;Imagen 仍可在 Vertex AI 上使用。图片编辑需要原生模式和 Gemini 图片模型;不支持蒙版。关于参数映射和定价详情,请参阅 Images API 的提供商说明。
聊天响应中的图片
在原生模式下,支持图片的模型(gemini-2.5-flash-image、gemini-3-pro-image-preview 等)可以在 Chat Completions 和 Responses 中返回图片。message.content 仍为文本字符串。在 Chat Completions 上,图片放在单独的 images 数组中,与 OpenRouter 使用的字段相同。不读取该字段的客户端会直接忽略它:
image_generation_call 输出项。Base64 图片位于 result 中,格式位于 output_format 中,与 OpenAI 的输出一致。如需在后续轮次中编辑该图片,请原样回传助手消息(包含 images)或 image_generation_call 输出项,以便 Gemini 获得每张图片的思考签名。/v1/messages(Anthropic Messages API)客户端只会收到文本。流式响应中,每张图片都会完整送达:Chat Completions 中位于数据块的 delta.images,Responses API 中则是一个已完成的 image_generation_call 输出项。携带完整 Base64 图片的单个上游流事件最大可达 32 MiB;流式插件默认最多容纳 4 MiB,因此更大的图片会终止经过这些插件的流。启用此类插件时,请以非流式方式请求 2K 和 4K 图片。
每张图片都是数 MB 的 Base64 数据。审计日志最多捕获 1 MB 的响应体,因此记录的响应体会被截断并标记为已截断。响应缓存会存储完整的响应。
推理强度
在原生模式下,reasoning_effort(或 reasoning.effort)会被转换为 Gemini 的 thinkingConfig:
Gemini 3 和 4 无法关闭思考,并且 Pro 系列、3.7 和 3.8 Flash 以及 Gemini 4(
gemini-4-argon 等)会拒绝 minimal,因此 GoModel 会发送这些模型所接受的最低级别,而不是将 Google 的 400 错误返回给您。显式设置的 extra_body.google.thinking_config 在设置了 thinking_budget 或 thinking_level 时会原样转发;否则 reasoning_effort 会把其级别或预算添加进去。同样的钳制也适用于 openai_compatible 模式,Google 的端点在该模式下会将 reasoning_effort 作为思考级别转发,并拒绝相同的取值。
在 Gemini 4 上,思考 Token 会计入 max_tokens,达到按请求输出上限的长回答会以 length(Gemini 的 CONTINUATION)结束;GoModel 不会续写它。
Gemini 3 和 4 上的采样参数
Google 的 Gemini 3 和 4 迁移指南建议从每个请求中移除temperature、top_p 和 top_k,因为这些模型已针对其默认值调优(Gemini 4 会忽略它们),并将 candidate_count 列为不支持的参数。因此在原生模式下,GoModel 会为 Gemini 3 及更高版本(gemini-3-*、gemini-3.8-*、gemini-4-* 等)丢弃这四个字段,而对 Gemini 2.5、Gemma 和其他模型仍会转发。presence_penalty 和 frequency_penalty 从不转发:包括 2.5 在内的所有当前 Gemini API 模型都会返回 HTTP 400 “Penalty is not enabled for this model”。max_tokens、stop、response_format 和思考设置不受影响。
在 openai_compatible 模式下,GoModel 还会丢弃 Google 端点视为未知而拒绝的成员(seed、logprobs、top_logprobs、store、metadata、logit_bias、top_k、prediction、prompt_cache_key、safety_identifier、verbosity、web_search_options)以及惩罚参数,并修复该端点发出的流式工具调用——它们缺少 index,且以 stop 而不是 tool_calls 结束。
思考签名(Thought signatures)
Gemini 3 和 4 会为其发出的函数调用附加一个加密的thoughtSignature;当该调用在历史记录中回传时如果缺少这个签名,后续请求会被拒绝(HTTP 400,“Function call is missing a thought_signature”)。在原生模式下,GoModel 以与 Google 自己的兼容 OpenAI 端点相同的方式暴露该签名,因此原样回传助手消息的客户端可以继续正常工作:
extra_content 成员也会出现在流式的 tool_calls 增量、Responses API 的 function_call 输出项、Anthropic Messages API 的 tool_use 块上,以及(对于纯文本轮次)助手消息本身上。请原样回传;在并行调用批次中,只有第一个调用携带签名。其他提供商永远不会看到它;共享约定请参阅额外内容、思考块与思考签名。工具调用或其 function 对象上的扁平 thought_signature(或 thoughtSignature)也会被接受,因此为其他网关构建的客户端可以继续正常工作。
当 Gemini 3 或 4 的历史记录中包含没有任何签名的函数调用时(对话最初在其他模型上开始,或客户端丢弃了该字段),GoModel 会发送 Google 文档中说明的 skip_thought_signature_validator 占位符,而不是返回 400 错误,原生模式和 openai_compatible 模式皆是如此。这会降低该轮次的推理连续性,因此建议回传真实的签名。
图片输入
在原生模式下使用 URL 托管的图片时,Google 自己的示例会先获取该 URL,再将字节发送到
generateContent。
视频输入
data: URL 会变为内联视频部分(当 data URL 未声明媒体类型时默认为 video/mp4),而 YouTube、Files API 和 Cloud Storage URI 会作为文件引用发送,由 Gemini 自行解析。其他任何远程 https://... URL 都会被拒绝而不是被丢弃,请先通过 Gemini Files API 上传。
消息与工具
在原生模式下,OpenAI 聊天字段按如下方式映射到generateContent:
Gemini 只在
ANY 或 VALIDATED 模式下接受 allowedFunctionNames,这就是 auto 子集会变为 VALIDATED 的原因:模型仍可以用文本回答,但它发起的任何调用都仅限于列出的工具。VALIDATED 作用于整个请求,因此只要有一个 strict 工具,所有已声明的工具都会进行 Schema 校验。
Gemini 无法将某一轮限制为只进行一次函数调用,指定单个工具也无济于事:Gemini 可以在一轮中多次调用同一个函数。如果 parallel_tool_calls: false(或 Anthropic 的 disable_parallel_tool_use)对您很重要,请在客户端中处理或拒绝多余的调用。
与 OpenAI 一样,tools 列表为空的 allowed_tools 选择会以 400 被拒绝。
尚未集成
- 在原生模式下自动获取远程
image_url值。 - 在聊天请求之前,通过 Gemini Files API 上传远程图片或视频。