Skip to main content
This guide calls Gemini’s native generateContent protocol. Confirm native Gemini support for your channel and model. The example sends a gateway token issued by your deployment in the x-goog-api-key header.

Address and request structure

The project selects a channel from the model path. The header authenticates the gateway token; the channel adapter supplies upstream authentication. The project also accepts the key query parameter, but this example keeps credentials out of URLs by using a header.

Setup

Use Node.js 22.18+ or 24 with built-in fetch; no Google SDK is required. Set API_KEY in your environment, then configure the root URL and actual model:
Save as native-gemini.mts and run node native-gemini.mts; from the documentation directory, run node examples/native-gemini.mts. This example accepts only letters, digits, dots, underscores, and hyphens in a model ID. It rejects models/ prefixes, paths, and action suffixes. This is a local URL validation constraint, not the gateway’s full model naming contract.

TypeScript

Complete example:

Read the result

The example requires exactly one candidate, finishReason: STOP, role: model, and nonempty visible text. A promptFeedback.blockReason, MAX_TOKENS, SAFETY, an error object, or tool/media parts fails the example. Text marked thought: true is omitted from display; thoughts without a visible answer also fail. Success prints the joined answer. Failure prints no partial answer, follows no redirects, and triggers no automatic retry. Native tools use tools[].functionDeclarations, functionCall, and functionResponse, which differ from Chat tool messages. For multiple turns, preserve the whole model content, including returned thoughtSignature values and tool identifiers, before adding new user content. Hiding thoughts for display does not justify dropping signatures during replay. This example is a single-turn text client, not a native tool loop.

Streaming path and support boundaries

Native SSE uses POST /v1beta/models/{model}:streamGenerateContent?alt=sse. Adding stream: true to a generateContent body does not switch actions. Each SSE data contains a Gemini response object, not a Chat delta or a named Responses event. Handle parts by candidate index and check the final finishReason; neither HTTP success nor EOF proves normal completion. A network chunk can split a UTF-8 character or an SSE event. This runnable example covers generateContent text responses. Native SSE and tool loops provides a complete Python streaming implementation. Image/audio extensions and actual channels still need separate implementation and integration testing. Do not reuse the event parsers from Chat / Responses streaming tools for Gemini. The project does not implement /v1beta/...:countTokens and currently returns 404; do not rely on provider SDK counting methods. Verify model routing, optional fields, and conversion behavior against your deployment. Gemini generateContent reference · Error handling Protocol reference: Google generateContent / streamGenerateContent. Gateway endpoints and authentication follow this repository’s routing and adapters. 阅读中文