# Gemini streaming — `models.streamGenerateContent`

Status: DOCUMENTED + LIVE_VERIFIED (SSE and JSON-array variants, structured-output stream, thinking stream; 2026-09-18, gemini-3.5-flash-lite / gemini-3.5-flash). Sources: https://ai.google.dev/api/generate-content#method:-models.streamgeneratecontent · https://ai.google.dev/gemini-api/docs/generate-content/text-generation · https://ai.google.dev/gemini-api/docs/generate-content/thought-signatures Machine-readable: generated/fragments/streaming-events/gemini-core.json, generated/fragments/endpoints/gemini-core.json Last verified: 2026-09-18

# 1. Two framings, one chunk type

POST /v1beta/models/{model}:streamGenerateContent takes the exact generateContent body. The response framing depends on the alt query parameter:

Variant	URL	Content-Type	Framing (observed)
SSE (recommended)	`…:streamGenerateContent?alt=sse`	`text/event-stream`	`data: <json>\r\n\r\n` per chunk. No `event:`/`id:` fields, no `[DONE]`. 4 chunks = 8 lines.
JSON array (default)	`…:streamGenerateContent`	`application/json; charset=UTF-8`	A pretty-printed JSON array streamed incrementally: line 1 `[{`, chunks separated by a line containing only `,`, closed by `]` (122 lines for the same 4 chunks). Needs an incremental array parser.

Both carried byte-identical chunk objects for the same prompt. Bonus (undocumented): …:generateContent?alt=sse returns a single data: event with the full response.

# 2. Chunk = partial `GenerateContentResponse`

Observed sequence for "Count from 1 to 12" (26 output tokens):

#	parts	finishReason	usageMetadata
1	`{text: "1 "}`	—	present (prompt 13, candidates 2)
2	`{text: "2 3 4 5 6 7 8 9 10"}`	—	present (running)
3	`{text: " 11 12"}`	—	present
4	`{text: "", thoughtSignature: "El4K…"}`	`STOP`	final (13 / 26 / 39, `serviceTier: standard`)

Rules:

usageMetadata is present in every chunk (running candidatesTokenCount); use the last one.
modelVersion and responseId are repeated on every chunk; responseId is constant within a stream.
The final chunk on Gemini 3 models carries an empty-text part with the turn's thoughtSignature — parsers must not drop empty text parts, and must keep reading until finishReason appears (docs FAQ: "the model may return the thought signature in a part with an empty text content part").
finishReason appears only once, on the last chunk (STOP, MAX_TOKENS observed).
Text deltas concatenate; with responseMimeType: application/json the deltas are partial JSON strings ({"colors": ["red", … then the rest) that concatenate into the final object.

# 3. Thinking in streams

With thinkingConfig.includeThoughts: true thought summaries stream first as parts {text, thought: true} (rolling summaries), then answer parts. Not guaranteed: on gemini-3.5-flash with thinkingBudget: 128 the stream billed thoughtsTokenCount: 103 yet emitted no thought part (2 chunks: 399 then the signature chunk). Non-streaming with budget 256 did return a thought part.

# 4. Errors

Pre-stream errors are plain JSON error bodies with the HTTP status (429 RESOURCE_EXHAUSTED observed).
Mid-stream errors are not documented for generateContent SSE (the Interactions API defines an error event; not applicable here). Treat a connection close without finishReason as an error.
Prompt blocked → single response with promptFeedback.blockReason and no candidates (not triggered).

# 5. Clients

curl: curl -N -H "x-goog-api-key: $GEMINI_API_KEY" -H "Content-Type: application/json" "…:streamGenerateContent?alt=sse" -d @body.json (examples/gemini/streaming/stream.sh).
Python: for chunk in client.models.generate_content_stream(...): chunk.text (SDK always uses alt=sse).
Node: for await (const chunk of await ai.models.generateContentStream({...})) chunk.text.

# Gemini streaming — models.streamGenerateContent