Streaming

Stream authenticated Gemini responses, inspect per-chunk model metadata, and consume structured partial outputs.

GeminiWeb.stream() returns a promise that resolves to an async iterable of GeminiStreamChunk. Text deltas are yielded as they arrive, allowing you to process generated output incrementally.

Basic streaming

Initialize GeminiWeb with your authentication credentials and call stream() with a prompt. Iterate over the returned chunks to display text as it arrives.

src/stream.ts

import 'dotenv/config'import { GeminiWeb } from '@orcushq/gemini' const cookies = process.env.GEMINI_COOKIESconst xsrfToken = process.env.GEMINI_XSRF_TOKEN if (!cookies?.trim() || !xsrfToken?.trim()) {  throw new Error(    'GEMINI_COOKIES and GEMINI_XSRF_TOKEN are required',  )} const model = new GeminiWeb({  model: 'gemini-3.6-flash',  cookies,  xsrfToken,}) const stream = await model.stream(  'Write a short haiku about servers.',) for await (const chunk of stream) {  if (chunk.content) {    process.stdout.write(chunk.content)  }   if (chunk.done) {    console.log('\nFinished:', chunk.accumulated)  }}

Chunk fields

content contains the newly emitted text delta.
accumulated contains the full text emitted so far.
done is true on the final chunk of a successful stream.
model identifies the model reported as serving the response.
requestedModel identifies the requested model ID without the @think= suffix, when available.
modelFellBack indicates whether the response evidence shows a model substitution.
fallbackReason explains the detected fallback, or is undefined.

Inspect model metadata

Inspect the final chunk to access model information and fallback metadata. The reported model can differ from the requested model, so use the response metadata when checking which model served the request.

src/stream-metadata.ts

const stream = await model.stream(  'Write a short story about programming.',) for await (const chunk of stream) {  if (chunk.content) {    process.stdout.write(chunk.content)  }   if (chunk.done) {    console.log('\nRequested model:', chunk.requestedModel)    console.log('Served model:', chunk.model)    console.log('Model fallback:', chunk.modelFellBack)    console.log('Fallback reason:', chunk.fallbackReason)  }}

Served model evidence

The requested model does not guarantee which model answered. Fallback metadata is derived from the response evidence. See [Served model evidence](/docs/served-model-evidence).

Structured partials

withStructuredOutput() creates a structured-output runnable that can stream text and best-effort partial values. The partial field contains a parsed and validated value when the accumulated output matches the supplied schema.

src/structured-stream.ts

import { z } from 'zod' // Reuse the authenticated model initialized above.const personSchema = z.object({  name: z.string(),  age: z.number(),}) const structured = model.withStructuredOutput(personSchema) for await (const chunk of structured.stream(  'Return JSON with name "Vikas" and age 21.',)) {  if (chunk.content) {    process.stdout.write(chunk.content)  }   if (chunk.partial !== undefined) {    console.log('\nStructured partial:', chunk.partial)  }   if (chunk.done) {    console.log('\nFinal result:', chunk.partial)  }}

Partials are best effort

`chunk.partial` may be undefined while the output is incomplete or invalid. A partial value is available when the accumulated output can be extracted, parsed, and validated against the schema.