googleapis/js-genai

Google Gen AI SDK for TypeScript & JavaScript

What it is – An official Google‑maintained npm package (@google/genai) that wraps the Gemini 2.0+ APIs (the public Gemini Developer API and the Gemini Enterprise Agent Platform). It gives JavaScript/TypeScript code a thin, idiomatic layer for:

• Text, image, audio, video generation
• Streaming responses
• Function (tool) calling / automatic function calling
• Stateful chat sessions
• File uploads, live‑session handling, and the newer Interactions unified API

Who it’s for – Front‑end or back‑end developers who want to call Gemini models from Node.js or browsers without writing raw HTTP requests.

Key concepts

Concept	What it does
GoogleGenAI class	Entry point; holds auth config (API key or enterprise credentials) and creates sub‑modules (models, chats, caches, files, live, interactions).
ai.models.generateContent	One‑shot request for text (or multimodal) generation.
generateContentStream	Async iterator that yields partial chunks as the model streams output.
ai.chats	Creates a local Chat object that keeps conversation history and simplifies multi‑turn interactions.
ai.caches	Manages server‑side prompt caches to reduce token‑cost for repeated large prefixes.
ai.files	Uploads large files (images, audio, PDFs…) and references them in prompts.
ai.live	Starts a real‑time session that can accept live audio/video and return live output.
ai.interactions	A higher‑level API that unifies model calls, chat state, tool orchestration, and long‑running tasks (e.g., deep‑research agents).
Function calling / tools	Declare JSON‑schema functions, let Gemini call them, then feed the result back.
Automatic Continuation	The SDK automatically follows continuation tokens unless you disable it.

Installation

npm install @google/genai

Quick‑start (API‑key)

import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: process.env.GEMINI_API_KEY});

const resp = await ai.models.generateContent({
  model: 'gemini-flash-latest',
  contents: 'Why is the sky blue?'
});
console.log(resp.text);

The same constructor works in the browser, but the README warns you should keep the key server‑side.

Enterprise‑Agent initialization

const ai = new GoogleGenAI({
  enterprise: true,
  project: 'my‑project',
  location: 'us-central1'
});

Environment variables (GOOGLE_GENAI_USE_ENTERPRISE, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION) can also be used.

Streaming example

for await (const chunk of ai.models.generateContentStream({
  model: 'gemini-flash-latest',
  contents: 'Write a 100‑word poem.'
})) {
  console.log(chunk.text);
}

Function‑calling (tool) example

const controlLight: FunctionDeclaration = {
  name: 'controlLight',
  parametersJsonSchema: {
    type: 'object',
    properties: {
      brightness: {type: 'number'},
      colorTemperature: {type: 'string'}
    },
    required: ['brightness', 'colorTemperature']
  }
};

const resp = await ai.models.generateContent({
  model: 'gemini-flash-latest',
  contents: 'Dim the lights so the room feels cozy.',
  config: {
    toolConfig: {functionCallingConfig: {mode: FunctionCallingConfigMode.ANY, allowedFunctionNames: ['controlLight']}},
    tools: [{functionDeclarations: [controlLight]}]
  }
});
console.log(resp.functionCalls);

The SDK returns a functionCalls array that you can execute and feed back via a subsequent request (or via ai.chats).

Interactions API (stateful, agent‑style)

// First turn
const i1 = await ai.interactions.create({model: 'gemini-flash-latest', input: 'Hi, I am Amir.'});
// Second turn – keep conversation context
const i2 = await ai.interactions.create({
  model: 'gemini-flash-latest',
  input: 'What is my name?',
  previous_interaction_id: i1.id
});

Supports deep‑research agents, multimodal inputs, built‑in tools (Google Search, code execution), and custom function tools.

Error handling – All API errors surface as ApiError with name, message, and HTTP status fields.

Version & compatibility notes

• Current SDK works on Node 20+. From version 3.0.0 it will require Node 22+. Pin to <3.0.0 if you need older runtimes.
• Upcoming major release will move Automatic Function Calling out of Models.generateContent into the Chats module.
• Some fields are being deprecated (LiveConnectConfig.generation_config, prompt/text/image in generate_videos, etc.).

Where to learn more

• Full docs: https://googleapis.github.io/js-genai/
• Sample projects: https://github.com/googleapis/js-genai/tree/main/sdk-samples
• Code‑generation guidance: codegen_instructions.md in the repo.

---

Bottom line – This repository is a genuine, production‑grade SDK that lets JavaScript/TypeScript developers integrate Google’s Gemini models (including enterprise agents) into apps, with support for streaming, chat state, tool calling, and multimodal data.