multi-router.aidocs

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:

EndpointFormatForwards to
POST /v1beta/models/{model}:generateContentGeminigenerativelanguage.googleapis.com
POST /v1beta/models/{model}:streamGenerateContent?alt=sseGemini, streamed as server-sent eventsgenerativelanguage.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:

  1. In Provider Keys, add or enable a Gemini key for the organization.
  2. On the Routers page, select New router, and under Proxies choose Gemini Proxy.
  3. 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:

Create a Gemini Proxybash
curl -X POST https://api.multi-router.ai/v1/routers \
  -H "Authorization: Bearer $MR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "gemini_proxy", "name": "Eng Gemini", "routing": { "provider_key_id": "llpk_2Hq8Vb4ZsM" } }'

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.

A request through the proxybash
curl "https://api.multi-router.ai/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $MR_API_KEY" \
  -H "X-MR-Router: rt_9Hk3Ws7PzQ" \
  -H "Content-Type: application/json" \
  -d '{ "contents": [{ "role": "user", "parts": [{ "text": "Hello" }] }] }'

Limits, settings and Traffic

LimitValue
Request body32 MB
Time to Google's response headers120 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:

Error formatjson
{ "error": { "code": 403, "message": "this Gemini Proxy is disabled", "status": "PERMISSION_DENIED" } }
StatusCause
404The 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.
403The Gemini Proxy is disabled.
400The model is not a catalog Gemini model, or the Multi-Router API key is in a forwarded header.
429The API key's rate limit or a budget refused the request.
503The proxy's Gemini key is missing or disabled.
502Google could not be reached or timed out.
Codex ProxyAlias
Was this helpful?