Gemini Relay

Gemini Relay is a Gemini API proxy on Vercel (Next.js App Router) for regions where direct Gemini access is slow or blocked, plus a browser streaming playground for debugging.

Try it: gemini-relay-proxy.vercel.app/chat (demo only)

Important notes

• Custom domain required for production. Prefer DNS in a region that can reach Google Gemini. Do not rely on *.vercel.app in production. If needed, front the service with a jump host or another edge proxy (e.g. CF).
• Use your own Gemini API key. Do not share or reuse others’ keys.
• Multiturn messages must end with role: user (or a function response). If the first message is not user, the proxy drops it; if the last is not user, the request is rejected.
• Auth paths: /api/v1, /api/v1beta, /api/v1beta2 only.
  • Passthrough: ?key= or x-goog-api-key with your Gemini key.
  • Proxy mode: headers from PROXY_AUTH_HEADERS; server injects a key from GEMINI_API_KEYS.
  • Missing credential/path → 401. Proxy mode without GEMINI_API_KEYS → 503. Empty JSON body on POST/PUT/PATCH → 403 (GET needs no body).
• Runs on Next.js App Router Route Handlers (nodejs + Fluid Compute): app/api/v1|v1beta|v1beta2/[...path] → services/gemini/. Successful calls return 200 then stream. maxDuration and business timeout are 120s.
• Model IDs live in the URL (transparent forward), e.g. /api/v1beta/models/{model}:generateContent. Prefer current Stable: gemini-3.5-flash (general) or gemini-3.5-flash-lite (lighter). Playground can Refresh the official model list.
• Debug via Vercel → Logs (or local pnpm dev terminal). Playground / MCP are for debugging; generation still goes through the REST proxy.

Deploy

1. Clone / import the repo and deploy.
2. Attach a custom domain.
3. Set env vars (see below). Redeploy after changes.
4. If Deployment Protection is on, callers need x-vercel-protection-bypass (Vercel → Deployment Protection → Protection Bypass for Automation).

Local: copy .env.example → .env, then pnpm install && pnpm dev.

App routes

Usage

Replace $HOST with your origin (custom domain in production).

Passthrough (?key=):

curl "$HOST/api/v1beta/models/gemini-3.5-flash:streamGenerateContent?key=$GEMINI_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-vercel-protection-bypass: $VERCEL_SECRET" \
  -H "cache-control: no-cache" \
  --data-raw '{"contents":[{"role":"user","parts":[{"text":"Hello Gemini"}]}]}' \
  --compressed

Passthrough (header — recommended by Google):

curl "$HOST/api/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_TOKEN" \
  -H "x-vercel-protection-bypass: $VERCEL_SECRET" \
  --data-raw '{"contents":[{"role":"user","parts":[{"text":"Hello Gemini"}]}]}'

Proxy mode (server holds Gemini keys; callers send PROXY_AUTH_HEADERS):

# PROXY_AUTH_HEADERS='{"X-API-KEY":""}'
# GEMINI_API_KEYS='["..."]'
curl "$HOST/api/v1beta/models" \
  -H "X-API-KEY: " \
  -H "x-vercel-protection-bypass: $VERCEL_SECRET"

Environment variables

MCP (for agents)

Two MCP endpoints share the same Skill docs. Generation stays on REST / Playground.

1. Install MCP (public, no secret): read Skill / deploy guide before you have proxy keys.
2. After deploy, switch to Auth MCP (proxy headers required): Skill + gemini_list_models.
3. Optionally set MCP_INSTALL_ENABLED=false to take the install MCP offline.

One-click — Install MCP (no secret):

{
  "mcpServers": {
    "gemini-relay-install": {
      "url": "https://gemini-relay-proxy.vercel.app/api/mcp/install"
    }
  }
}

Auth MCP (after deploy — replace the secret):

{
  "mcpServers": {
    "gemini-relay": {
      "url": "https://gemini-relay-proxy.vercel.app/api/mcp",
      "headers": {
        "X-API-KEY": ""
      }
    }
  }
}

Site UI: header MCP → install + auth one-click / Copy mcp.json. On your host, swap origin to $HOST.