Google Gen AI SDK

@google/genai is Google’s official TypeScript and JavaScript SDK for building applications powered by Gemini models. It provides a single, unified client that works with both the Gemini Developer API (using an API key from Google AI Studio) and the Gemini Enterprise Agent Platform (formerly Vertex AI), so teams can prototype against the consumer API and later move to enterprise infrastructure without rewriting application code.

The SDK wraps content generation, streaming, function calling, file uploads, context caching, live bidirectional sessions, batch jobs, and fine-tuning behind a consistent, well-typed API surface, and ships isomorphic builds that run in both Node.js and the browser.

What You Get

• A single GoogleGenAI client that switches between the Gemini Developer API (API key) and Vertex AI / Gemini Enterprise (Cloud project credentials) without changing application code
• First-class support for text, image, audio, and video generation, plus streaming responses via generateContentStream
• Built-in function calling with JSON-schema tool declarations, automatic function calling, and native Model Context Protocol (MCP) tool support
• Context caching (ai.caches), file uploads (ai.files), batch jobs (ai.batches), fine-tuning (ai.tunings), and low-latency bidirectional Live sessions (ai.live) for audio/video
• Isomorphic builds for Node.js (CommonJS + ESM) and the browser, plus a bundled SentencePiece tokenizer for local token counting

Common Use Cases

• Building chatbots and multi-turn conversational agents with the ai.chats module
• Adding multimodal generation (text, image, audio) to web and Node.js applications
• Implementing tool-using/agentic workflows via function calling and MCP tool integration
• Building real-time voice/video assistants using the Live API’s bidirectional streaming sessions
• Migrating between prototyping with a Gemini API key and production deployment on Vertex AI without rewriting client code

Under The Hood

Architecture - Isomorphic design split across src/node, src/web, and src/cross directories behind a shared public API in client.ts/index.ts; a single GoogleGenAI entry point composes focused submodules (Models, Chats, Caches, Files, Live, Tokens, Tunings, Batches, Operations, FileSearchStores) each in its own file, with an internal ApiClient (_api_client.ts) abstracting HTTP/auth differences between the Gemini Developer API and the Gemini Enterprise Agent Platform (Vertex AI) so the same application code can target either backend.

Tech Stack - Pure TypeScript compiled with Rollup into dual ESM/CJS bundles for Node and web, using google-auth-library for Vertex/enterprise auth, ws for the Live streaming/WebSocket API, protobufjs for the bundled SentencePiece tokenizer, and Microsoft’s api-extractor to generate and diff public API reports on every build; tests run on Jasmine with recorded system/integration suites.

Code Quality - Consistently documented with TSDoc comments on nearly every public type and method (types.ts alone is roughly 8,600 lines of typed request/response models), enforced via ESLint/Prettier and strict TypeScript; the public surface is intentionally kept small behind underscore-prefixed internal modules (_api_client, _transformers, _afc), though the sheer size of the generated types file is a maintenance-heavy artifact.

API Design - A single new GoogleGenAI({...}) client exposes cleanly namespaced submodules (ai.models, ai.chats, ai.caches, ai.files, ai.live), supports both one-shot and streaming generateContent calls, declarative function calling with JSON-schema tool definitions (including automatic function calling and native MCP tool support), and works identically whether authenticated via a simple API key or full enterprise credentials — a deliberately low-friction entry point for a very large capability surface.