Google Generative AI JavaScript SDK

@google/generative-ai is the Node.js and browser SDK for calling Google’s Gemini API directly (not via Vertex AI). It provides a GoogleGenerativeAI client for minting GenerativeModel instances, then generateContent()/generateContentStream() for single-turn or streamed responses, a ChatSession helper for multi-turn conversations, plus support for function calling, system instructions, safety settings, token counting, and embeddings. A separate @google/generative-ai/server entry point exposes Node-only file upload and context-caching APIs for reference from prompts.

With the release of Gemini 2.0, Google unified this SDK with its Vertex AI SDK into a single @google/genai package and put this repository into limited maintenance: critical bug fixes only, with its stated end-of-life date (November 30, 2025) already passed. It remains widely installed — over 4 million weekly npm downloads — reflecting the large base of existing integrations that adopted it before the unification and have not yet migrated to the new SDK.

What You Get

• A typed GoogleGenerativeAI client with getGenerativeModel() for text, multimodal, and function-calling requests against Gemini models
• Streaming (generateContentStream) and non-streaming (generateContent) response handling, with streamed chunks consumable via async iteration
• A ChatSession helper that manages multi-turn conversation history automatically
• Content caching and file upload support via the isolated @google/generative-ai/server entry point (Node-only)
• Built-in support for system instructions, safety settings, generation config, tool/function-calling schemas, and token counting

Common Use Cases

• Adding a Gemini-powered chat feature - a team wires up ChatSession in a Node backend or browser app to get multi-turn conversational responses without hand-rolling history management
• Multimodal prompting - passing images and text together as Part[] for an app that needs to reason over screenshots or documents
• Function calling - defining Tool/ToolConfig schemas so the model can request structured function calls that the app then executes and returns results for
• Server-side file and cache management - using the /server subpath to upload large files or set up cached content for repeated prompts, cutting token costs on Node-hosted services

Under The Hood

Architecture

The package is layered: src/gen-ai.ts exposes the top-level GoogleGenerativeAI client, which mints GenerativeModel instances (src/models/generative-model.ts) that in turn delegate each operation to a methods/ layer (generate-content.ts, chat-session.ts, count-tokens.ts, embed-content.ts). Those methods funnel through a shared requests/ layer (request.ts builds the target URL and headers and issues the fetch call, request-helpers.ts formats request bodies, response-helpers.ts parses responses, stream-reader.ts aggregates server-sent-event chunks for streaming). A separate server/ subpackage, exposed via the @google/generative-ai/server export condition, provides GoogleAIFileManager and GoogleAICacheManager against a distinct Node-only REST surface. errors.ts centralizes a small typed error hierarchy that every layer throws through consistently. There is no dependency-injection container; the design relies on straightforward object construction, with request.ts’s URL/header-building functions acting as the single choke point every method ultimately depends on.

Tech Stack

Written in strict TypeScript (5.2.2) with zero runtime dependencies, calling Gemini’s REST API directly via the native fetch/Headers APIs. Built with Rollup into dual CJS/ESM bundles for both the main and server entry points, with Microsoft’s API Extractor generating curated .d.ts files and API reports for each surface separately (api-extractor.json / api-extractor.server.json) — a level of public-API surface discipline beyond a typical small SDK. Documentation is generated straight from TSDoc comments via API Documenter into docs/reference/{main,server}. Release management uses Changesets with dedicated GitHub Actions workflows for release-PR creation and npm publishing. The package targets Node >=18 and browsers as a dual build, gating Node-only file/cache APIs behind the separate /server export.

Code Quality

Twenty-three *.test.ts files sit alongside their source files, using Mocha, Chai, chai-as-promised, and Sinon for unit coverage of request formatting and response parsing, plus a separate test-integration/node suite and @web/test-runner-based browser integration tests. Error handling is explicit and typed rather than swallowed: request.ts checks response.ok and throws a structured GoogleGenerativeAIFetchError carrying status, statusText, and parsed error details, and a small class hierarchy (GoogleGenerativeAIError and subclasses for fetch/response/request-input/abort errors) is used consistently across the codebase. Naming is consistent and mirrors the underlying Gemini API task names. Linting (ESLint + typescript-eslint + import/unused-imports plugins) and Prettier formatting run as part of npm test and CI (.github/workflows/test.yml).

API Design The public API is intentionally small: new GoogleGenerativeAI(apiKey).getGenerativeModel({model}) followed by .generateContent() or .generateContentStream(), which accept either a bare string, an array of string/Part, or a fully-typed request object — minimizing boilerplate for the common case while still exposing systemInstruction, tools, safetySettings, and generationConfig for advanced use. ChatSession wraps multi-turn history management, and streaming responses are exposed as an async-iterable so consumers can for await chunks without manually parsing SSE. The dedicated /server entry point cleanly isolates Node-only file and cache APIs from the isomorphic client, and TSDoc {@link} cross-references throughout support IDE tooltips and the generated reference docs. The tradeoff is that, being deprecated in favor of @google/genai, its ergonomics deliberately preserve the old API’s shape rather than adopt the newer SDK’s conventions.