Routing
Gemini Proxy
The router that serves Gemini CLI: Gemini generateContent requests forwarded to Google with the organization's Gemini key.
A Gemini Proxy is a router that serves Google's Gemini CLI and other clients of the Gemini API. It receives Gemini generateContent and streamGenerateContent requests, forwards the request body to Google unchanged with the organization's Gemini key, and returns Google's response unchanged. It serves Gemini models only, and records usage and cost for each person in Traffic. How Gemini CLI is configured to use a Gemini Proxy is described in Gemini CLI.
Endpoints
A request selects the proxy with the X-MR-Router header, which names the proxy's id or an alias that points to it. The model is the path segment before the colon:
| Endpoint | Format | Forwards to |
|---|---|---|
POST /v1beta/models/{model}:generateContent | Gemini | generativelanguage.googleapis.com |
POST /v1beta/models/{model}:streamGenerateContent?alt=sse | Gemini, streamed as server-sent events | generativelanguage.googleapis.com |
Only these two operations are served: other Gemini API operations, such as countTokens, return 404, and paths without /v1beta and the ?key= query parameter are not supported. Without a Gemini Proxy in the header, these paths return 404 Gemini generateContent is only available through a Gemini Proxy (X-MR-Router).
Credentials
A Gemini Proxy uses an organization Gemini key only, set in routing.provider_key_id. Multi-Router removes the client's credential and sends the organization's key, so usage is billed to the organization's Google account and developers never hold the Gemini key.
The client sends its Multi-Router API key in x-goog-api-key, the header Gemini clients use for their key, which Multi-Router accepts on these paths. The key can also be sent as Authorization: Bearer <key> or X-MR-Api-Token: Bearer <key>. A Google account sign-in does not go through a Gemini Proxy.
Models
A Gemini Proxy forwards requests for Gemini models in the catalog, named as Google names them, such as gemini-2.5-flash. A model the catalog does not list for Gemini returns 400 only catalog-known Gemini models are served by this proxy.
Creating a Gemini Proxy
To create a Gemini Proxy in the dashboard:
- In Provider Keys, add or enable a Gemini key for the organization.
- On the Routers page, select New router, and under Proxies choose Gemini Proxy.
- Enter a Name, choose the organization's Gemini key, and create the proxy. Its Forwarding panel shows the key, which can be changed, and the Gemini CLI settings.
With the API, send POST /v1/routers with kind gemini_proxy and the key:
routing.provider_key_id is required and is the only routing field a Gemini Proxy accepts. PATCH /v1/routers/{id} with routing.provider_key_id changes the key.
Limits, settings and Traffic
| Limit | Value |
|---|---|
| Request body | 32 MB |
| Time to Google's response headers | 120 seconds |
A Gemini Proxy's settings are its key, its request logging, and its name, description and tags. The API key's rate limit and budgets apply. Requests are sent to Google once, without retries, and Google's status and error body are returned to the client. Traffic records one row for each request, with the API type gemini.generate_content or gemini.stream_generate_content, the model, the person and the cost.
Errors
Creating or changing a Gemini Proxy returns 400 invalid_provider_key_id when the key is missing or is not an enabled Gemini key in the organization. Errors from Multi-Router use Google's format, so Gemini clients read them as they read Google's own:
| Status | Cause |
|---|---|
| 404 | The X-MR-Router header names no Gemini Proxy, the API key cannot use it, or the path is not one of the two served operations. |
| 403 | The Gemini Proxy is disabled. |
| 400 | The model is not a catalog Gemini model, or the Multi-Router API key is in a forwarded header. |
| 429 | The API key's rate limit or a budget refused the request. |
| 503 | The proxy's Gemini key is missing or disabled. |
| 502 | Google could not be reached or timed out. |