generateContent, batchEmbedContents, Imagen predict). Switch to the
OpenAI-compatible endpoint when you need compatibility behavior the native
adapter does not implement yet (notably remote image_url values).
Configure
config.yaml:
USE_GOOGLE_GEMINI_NATIVE_API is still honored as a legacy global toggle
when per-provider GEMINI_API_MODE is unset. Prefer GEMINI_API_MODE.store: false is forwarded as Gemini’s
per-request opt-out; the OpenAI-compatible endpoint has no such member.
In native AI Studio mode /v1/messages/count_tokens is answered by Gemini’s
own countTokens, so the count includes the per-request overhead Gemini 4
bills. openai_compatible mode, Vertex, and any request whose countTokens
call fails get GoModel’s estimate.
Base URLs
GoModel keeps separate internal bases for native Gemini and the OpenAI-compatible API:- native chat/models:
https://generativelanguage.googleapis.com/v1beta - OpenAI-compatible:
https://generativelanguage.googleapis.com/v1beta/openai
GEMINI_BASE_URL overrides them. When the value ends in /openai, GoModel
uses it for the OpenAI-compatible client and derives the native base by
stripping /openai. Files and batches always use the OpenAI-compatible
surface; chat, embeddings, and images follow the API mode.
Embeddings
In native mode, embeddings are served throughmodels/{model}:batchEmbedContents.
dimensions maps to outputDimensionality and encoding_format: "base64" is
honored. Native mode records the token usage Gemini reports for newer models
such as gemini-embedding-2. Older models such as gemini-embedding-001, and
the OpenAI-compatible surface, report none, so those responses carry zero token
counts. When the model is priced per token, these zero-count usage rows are
flagged with a cost-calculation caveat.
Image generation and edits
In native mode the OpenAI-compatible image endpoints work with Gemini image models (gemini-2.5-flash-image, gemini-3.1-flash-image,
gemini-nano-banana-2.1, …, via generateContent). When the model returns no
image, the error carries Gemini’s finish reason and message (for example
IMAGE_RECITATION). Google retired Imagen from the AI Studio API in August
2026; Imagen is still served on Vertex AI. Image edits
require native mode and a Gemini image model; masks are not supported. See the
Images API provider notes for parameter
mapping and pricing details.
Images in chat responses
In native mode, image-capable models (gemini-2.5-flash-image,
gemini-3-pro-image-preview, …) can return images from Chat Completions and
Responses. message.content stays the text string. On Chat Completions the
images go in a separate images array, the same field OpenRouter uses.
Clients that don’t read the field just ignore it:
image_generation_call output
item. The base64 image is in result and the format in output_format, as in
OpenAI’s output. To edit the image in a later turn, send the assistant message
(with images) or the image_generation_call item back unchanged, so Gemini
gets each image’s thought signature. /v1/messages (Anthropic Messages API)
clients get only the text. When streaming, each image arrives whole: in a
chunk’s delta.images on Chat Completions, and as a finished
image_generation_call item on Responses. One upstream stream event, which
carries a whole image as base64, can be up to 32 MiB; stream plugins hold at
most 4 MiB by default, so a larger image ends a stream that runs through them.
Request 2K and 4K images without streaming when such plugins are on.
Each image is several megabytes of base64. Request logs capture at most 1 MB of
a response body, so a logged body is truncated and marked as such. The response
cache stores the whole response.
Reasoning effort
In native mode,reasoning_effort (or reasoning.effort) is translated to
Gemini’s thinkingConfig:
Thinking cannot be turned off on Gemini 3 or 4, and Pro models, 3.7 and 3.8
Flash, Gemini 4 (
gemini-4-argon, …) and the -latest aliases reject minimal, so GoModel sends
the lowest level those models accept instead of surfacing Google’s 400.
Likewise only Gemini 4 Hydrogen accepts xhigh, so every other Gemini model gets
high (the high budget on Gemini 2.5). An
explicit extra_body.google.thinking_config is forwarded unchanged when it
sets thinking_budget or thinking_level; otherwise reasoning_effort adds
its level or budget to it. The same clamps apply to Gemini 3 and 4 in openai_compatible mode, where Google’s endpoint
forwards reasoning_effort as a thinking level and rejects the same values.
On Gemini 4, thinking tokens count against max_tokens, and a long answer that
hits the per-request output cap finishes with length (Gemini’s
CONTINUATION); GoModel does not resume it.
Google bills thinking tokens as output. Its OpenAI-compatible endpoint counts
them in total_tokens but leaves them out of completion_tokens, so in
openai_compatible mode GoModel adds them back before it records usage and
answers the client. As in native mode, the output count then includes thinking:
Chat Completions report it in completion_tokens and
completion_tokens_details.reasoning_tokens, the Responses API in
output_tokens and output_tokens_details.reasoning_tokens. Recorded output
tokens and cost rise accordingly. How much is added depends on the response:
- Reasoning tokens itemised: at most that count is added, and an explicit
0adds nothing.reasoning_tokensreports the itemised count, or the output count when the itemised count is larger, whether or not anything was added, so it never exceeds the output count. - Not itemised (the shape recorded from Gemini 2.5 Flash and 3 Flash): the
whole part of
total_tokensbeyond prompt and completion tokens is added and reported as reasoning tokens. It can include prompt tokens of Google’s built-in tools, which are then priced as thinking: at the output rate, or atreasoning_output_per_mtokwhen the model has one.
Sampling parameters on Gemini 3 and 4
Google’s Gemini 3 and 4 migration guides say to removetemperature, top_p
and top_k from every request because the models are tuned for their defaults
(Gemini 4 ignores them), and list candidate_count as unsupported. In native
mode GoModel therefore drops those four fields for Gemini 3 and later
(gemini-3-*, gemini-3.8-*, gemini-4-*, …) and still forwards them for
Gemini 2.5, Gemma and other models. presence_penalty and frequency_penalty
are never forwarded: every current Gemini API model, 2.5 included, answers
HTTP 400 “Penalty is not enabled for this model”. max_tokens, stop,
response_format and thinking settings are unaffected.
In openai_compatible mode GoModel also drops the members Google’s endpoint
rejects as unknown (seed, logprobs, top_logprobs, store, metadata,
logit_bias, top_k, prediction, prompt_cache_key, safety_identifier,
verbosity, web_search_options) along with the penalties, and repairs the
streamed tool calls that endpoint emits without an index and finishes with
stop instead of tool_calls.
Thought signatures
Gemini 3 and 4 attach an encryptedthoughtSignature to the function calls
they emit and reject a follow-up request (HTTP 400, “Function call is missing a
thought_signature”) when that call comes back in the history without it. In
native mode GoModel exposes the signature the same way Google’s own
OpenAI-compatible endpoint does, so a client that echoes assistant messages
back unchanged keeps working:
extra_content member appears on streamed tool_calls deltas, on
Responses API function_call output items, on Anthropic Messages API
tool_use blocks, and (for text-only turns) on the assistant message itself.
Send it back verbatim; only the first call of a parallel batch carries a
signature. Other providers never see it; see
Extra content, thinking blocks, and thought signatures for the shared convention. A flat thought_signature (or
thoughtSignature) on the tool call or its function object is accepted too,
so clients built against other gateways keep working.
When a Gemini 3 or 4 history contains a function call without any signature
(the conversation started on another model, or the client dropped the field),
GoModel sends Google’s documented skip_thought_signature_validator
placeholder instead of surfacing the 400, in native and openai_compatible
mode alike. Reasoning continuity is reduced for that turn, so prefer echoing
the real signature.
Image input
For URL-hosted images in native mode, Google’s own examples fetch the URL
first and send the bytes to
generateContent.
Video input
data: URL becomes an inline video part (defaulting to
video/mp4 when the data URL declares no media type), while YouTube, Files API,
and Cloud Storage URIs are sent as a file reference Gemini resolves itself. Any
other remote https://... URL is rejected rather than dropped — upload it
through the Gemini Files API first.
Messages and tools
In native mode, OpenAI chat fields map ontogenerateContent like this:
Gemini accepts
allowedFunctionNames only with ANY or VALIDATED, which is
why an auto subset becomes VALIDATED: the model can still answer in text,
but any call it makes is limited to the listed tools. VALIDATED applies to
the whole request, so one strict tool makes every declared tool
schema-validated.
Gemini has no way to limit a turn to one function call, and naming a single
tool does not help: Gemini can call the same function more than once in a turn.
When parallel_tool_calls: false (or Anthropic’s disable_parallel_tool_use)
matters, handle or reject the extra calls in your client.
An allowed_tools choice with an empty tools list is rejected with a 400, as
OpenAI does.
Not yet integrated
- Automatic fetching of remote
image_urlvalues in native mode. - Uploading remote images or videos through the Gemini Files API before a chat request.