cloudflare / cloudflare/cloudflare-docs

AI Gateway Realtime WebSockets: Gemini Live (BidiGenerateContent) docs example doesn't reflect actual behaviour

Open
#30,949 1 comment 0 reactions 9 assignees Claimed by @zeke View on GitHub
content:edit documentation product:ai-gateway stale
Dominant language
MDX
Stars
5.2k
Forks
16.7k
Avg merge
2d 6h
Merged PRs (30d)
337

Description

### Existing documentation URL(s)

## Page

https://developers.cloudflare.com/ai-gateway/usage/websockets-api/realtime-api/

### What changes are you suggesting?

## Issue

The Google AI Studio code sample on this page suggests Gemini Live (`BidiGenerateContent`) is supported through AI Gateway. In practice, the gateway returns `101 Switching Protocols` for the WS upgrade but immediately drops with `1006` (abnormal closure) when any frame is sent.

We tested four auth permutations from a Cloudflare Worker outbound `fetch()` with `Upgrade: websocket`:

| # | URL | Auth | Result |
|---|-----|------|--------|
| 1 | `wss://gateway.ai.cloudflare.com/v1///google?api_key=` | `cf-aig-authorization: Bearer ` header | 101 → 1006 |
| 2 | Same URL | `cf-aig-authorization: ` header (no Bearer) | 101 → 1006 |
| 3 | Same URL | `Sec-WebSocket-Protocol: cf-aig-authorization.` subprotocol (per docs sample) | 101 → 1006 |
| 4 | No `api_key` in URL | `cf-aig-authorization: Bearer ` header (BYOK assumed) | HTTP 500 |

The direct path (`wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent?key=...`) works perfectly with the same setup payload, so the issue isn't on our side.

## Smoking gun in the docs sample itself

The code example specifies:

```js
setup: {
model: "models/gemini-2.5-flash",
generationConfig: { responseModalities: ["TEXT"] },
}
```

But `gemini-2.5-flash` is not a Live-capable model, and `BidiGenerateContent` is the realtime bidirectional endpoint — pairing them with `responseModalities: ["TEXT"]` doesn't match any of Google's documented Live model use cases. This suggests the sample was written ahead of actual implementation.

## Request

Either:

1. **Document the actual current support** — list which Google models/endpoints work through gateway WS (e.g. note that REST is supported but `BidiGenerateContent` isn't yet), and remove or update the Google sample on the realtime-api page to a configuration that actually works, OR
2. **Ship the implementation** — track the gap as a known issue with a target window.

Even option (1) would have saved us several hours of debugging. The sample as it stands actively suggests this works.

## Environment

- Cloudflare Worker (`compatibility_date = "2026-03-27"`), `nodejs_compat` flag, `smart` placement (Oceania).
- Workers `fetch()` outbound WS pattern (same pattern works fine for the `workers-ai` provider — Deepgram Nova-3).
- AI Gateway with `AI_GATEWAY_SLUG` set; REST Google routing works correctly through the same gateway.
- Tested 2026-05-20.

### Additional information

_No response_

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.