Skip to main content
This page covers Gemini through Google AI Studio API keys. For Gemini on Google Cloud’s Vertex AI, see the Google Vertex AI guide. By default, GoModel routes Gemini chat, Responses, embeddings, and image requests through Gemini’s native APIs (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

Or in 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.
Native AI Studio mode can also materialize GoModel’s post-routing prompt-cache plans as five-minute Gemini cached-content objects. Reuse is scoped to the API key selected for the session; sessionless traffic with rotating keys skips object creation so a resource is never reused under the wrong credential. Gemini 4 models have no explicit caching (Google caches shared prefixes implicitly), so no objects are created for them. Vertex currently receives the original request without cached-content objects. Google stores Gemini API requests by default on new paid-tier projects. In native mode a Chat Completions 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 through models/{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:
On the Responses API each image is a separate 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 0 adds nothing. reasoning_tokens reports 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_tokens beyond 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 at reasoning_output_per_mtok when the model has one.

Sampling parameters on Gemini 3 and 4

Google’s Gemini 3 and 4 migration guides say to remove temperature, 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 encrypted thoughtSignature 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:
The same 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

In native mode a 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 onto generateContent 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_url values in native mode.
  • Uploading remote images or videos through the Gemini Files API before a chat request.

References

Last modified on November 18, 2026