Required dependencies

npm install google-auth-library p-retry protobufjs ws
npm install --save-dev @types/ws typescript

No native modules, pod installs, or Android linking steps are required for Node.js targets.

Project setup

1. Copy source. Place the source/ directory anywhere inside your project, e.g., src/genai/.

2. TypeScript config. Ensure your tsconfig.json includes the source and supports modern module resolution:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "esModuleInterop": true,
    "strict": true,
    "baseUrl": ".",
    "paths": {
      "@genai/*": ["src/genai/*"]
    }
  },
  "include": ["src/**/*"]
}

3. Environment variables. Set credentials before running:

# Gemini Developer API
export GEMINI_API_KEY="your-key-here"

# Or for Vertex AI / Enterprise Agent Platform
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"
# ADC: gcloud auth application-default login

4. Import entry point. Import from the barrel or node-specific entry:

// Universal (browser + Node)
import { GoogleGenAI } from './src/genai/index.js';
// Node-only (includes NodeGenAI with ADC support)
import { GoogleGenAI } from './src/genai/node/index.js';

5. Build. Compile with tsc or your existing bundler. No special build flags are required.

Public API

GoogleGenAI

import { GoogleGenAI, type GoogleGenAIOptions } from './src/genai/index.js';

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
// or Vertex: new GoogleGenAI({ project: '...', location: '...' })

The root client. Instantiate once and access all resource modules as properties (ai.models, ai.files, ai.live, ai.chats, ai.caches, ai.tokens, ai.batches, ai.operations, ai.tunings).

Models

import { Models } from './src/genai/index.js';
// Accessed as: ai.models  (type Models)

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: 'Explain quantum entanglement.',
});
console.log(response.text);

Handles all inference calls. Use generateContent for one-shot requests and streamGenerateContent for token-streaming responses.

Pager / PagedItem

import { Pager, PagedItem } from './src/genai/index.js';
// Returned by list operations, e.g. ai.models.list(), ai.files.list()

const page: Pager<PagedItem> = await ai.files.list({ config: { pageSize: 10 } });
for await (const file of page) {
  console.log(file.name);
}

An async-iterable cursor for paginated API responses. Iterate with for await or call .nextPage() manually.

setDefaultBaseUrls

import { setDefaultBaseUrls, type BaseUrlParameters } from './src/genai/index.js';

setDefaultBaseUrls({ googleAIStudio: 'https://custom-proxy.example.com' });

Override the default API base URLs globally before constructing any client. Useful for proxies, local emulators, or enterprise gateways.

mcpToTool

import { mcpToTool } from './src/genai/index.js';

const tool = mcpToTool(mcpServerDefinition);

Converts an MCP (Model Context Protocol) server tool definition into the Gemini Tool format accepted by generateContent.

Working examples

Scenario - Basic text generation

Simple one-shot prompt using the Gemini Developer API.

import { GoogleGenAI } from './src/genai/index.js';

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY! });

async function ask(prompt: string): Promise<string> {
  const response = await ai.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: prompt,
  });
  return response.text ?? '';
}

ask('What is 2 + 2?').then(console.log);

Scenario - Streaming response

Stream tokens to stdout as they arrive, reducing time-to-first-token in chat UIs.

import { GoogleGenAI } from './src/genai/index.js';

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY! });

async function stream(prompt: string) {
  const result = await ai.models.streamGenerateContent({
    model: 'gemini-2.5-flash',
    contents: prompt,
  });
  for await (const chunk of result) {
    process.stdout.write(chunk.text ?? '');
  }
  console.log();
}

stream('Tell me a short story about a robot.');

Scenario - Multi-turn chat

Maintain conversational context across multiple turns using the Chats helper.

import { GoogleGenAI } from './src/genai/index.js';

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY! });

async function chatSession() {
  const chat = ai.chats.create({ model: 'gemini-2.5-flash' });

  const r1 = await chat.sendMessage({ message: 'My name is Alex.' });
  console.log(r1.text);

  const r2 = await chat.sendMessage({ message: 'What is my name?' });
  console.log(r2.text); // should recall "Alex"
}

chatSession();

Scenario - File upload and multimodal inference

Upload a local file then pass it as content to the model.

import { GoogleGenAI } from './src/genai/node/index.js';
import { createReadStream } from 'fs';

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY! });

async function analyzeImage(path: string) {
  const uploaded = await ai.files.upload({
    file: { stream: createReadStream(path), mimeType: 'image/png', name: 'photo.png' },
  });

  const response = await ai.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: [
      { role: 'user', parts: [{ fileData: { fileUri: uploaded.uri, mimeType: 'image/png' } }, { text: 'Describe this image.' }] },
    ],
  });
  console.log(response.text);
}

analyzeImage('./screenshot.png');

File walkthrough

• index.ts — Public export barrel; start here for all imports.
• client.ts — Constructs GoogleGenAI, wires auth and HTTP client, exposes module properties.
• models.ts — Models class implementing generateContent, streamGenerateContent, embedContent, listModels, etc.
• types.ts — All request/response TypeScript interfaces and enumerations; generated from the API spec.
• errors.ts — GoogleGenAIError hierarchy thrown on API and network failures.
• files.ts — Files class for upload, get, list, delete operations on media files.
• live.ts — Live class for real-time bidirectional streaming via WebSocket.
• chats.ts — Chats factory that maintains turn history and wraps Models.
• caches.ts — Caches class for creating and managing context caches.
• batches.ts — Batches class for async batch prediction jobs.
• tokens.ts — Tokens class for countTokens operations.
• tunings.ts — Tunings class for supervised fine-tuning job management.
• operations.ts — Operations class for polling long-running operations.
• pagers.ts — Pager<T> async-iterable cursor and PagedItem type.
• mcp/ — mcpToTool adapter converting MCP server definitions to Gemini tool format.
• converters/ — Per-resource converter modules that map SDK params to REST request shapes.
• interactions/ — Gemini Enterprise Agent Platform agent interaction client (Stainless-generated).
• cross/ — Runtime-agnostic helpers: SentencePiece tokenizer, cross-env uploader/downloader/WebSocket.
• node/ — Node.js-specific: NodeGenAI client, Node auth (google-auth-library), Node file I/O.
• vertex_internal/ — Internal surface for @google/vertexai only; not a public API.
• _api_client.ts — Low-level HTTP dispatch, retry logic, header management.
• _auth.ts — Auth interface implemented by API-key and ADC providers.
• _base_url.ts — setDefaultBaseUrls and BaseUrlParameters.
• _common.ts — BaseModule base class shared by all resource modules.
• _transformers.ts / _base_transformers.ts — Response shape normalisation pipeline.
• _uploader.ts / _downloader.ts — Abstract interfaces for file transfer.
• _websocket.ts — WebSocket abstraction used by the Live API.
• _internal_types.ts — Internal-only type helpers not exported publicly.

Common pitfalls and fixes

• GEMINI_API_KEY not set at runtime — The client throws immediately; always verify process.env.GEMINI_API_KEY is populated before constructing GoogleGenAI.
• moduleResolution must be NodeNext or Bundler — The source uses .js extension imports; classic node resolution will fail to resolve them. Set "moduleResolution": "NodeNext" in tsconfig.json.
• ESM vs CJS interop with ws — ws is a CommonJS package; if your project is pure ESM ("type": "module"), import it as import WebSocket from 'ws' and ensure esModuleInterop: true.
• protobufjs missing at runtime — The SentencePiece tokenizer in cross/sentencepiece/ requires protobufjs. Install it even if you don't call the tokenizer directly, because the cross-module is bundled.
• Browser usage exposes API keys — Never instantiate GoogleGenAI with an apiKey in client-side browser bundles. Proxy through a backend route instead.
• Vertex AI ADC not configured — When using project/location auth, run gcloud auth application-default login and ensure GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION env vars are set, or pass them explicitly to the constructor.

Vibe-coding prompt template

I have copied the source of the @google/genai SDK (version 1.50.1) into
`src/genai/` inside my project. The integration guide is in `USAGE.md`.

Please help me integrate this SDK into my existing project step by step:

1. Read `USAGE.md` and `src/genai/index.ts` to understand the public API.
2. Identify where in my project I should initialise `GoogleGenAI` (singleton
   pattern recommended).
3. Add the required dependencies from the "Required dependencies" section of
   USAGE.md to my `package.json` and run `npm install`.
4. Update my `tsconfig.json` as described in "Project setup".
5. Create a service module that wraps `ai.models.generateContent` and
   `ai.models.streamGenerateContent` for my use case.
6. If I need multi-turn chat, use `ai.chats.create` from `src/genai/chats.ts`.
7. If I need file uploads, use `ai.files.upload` from `src/genai/files.ts`.
8. Make sure no API keys appear in client-side code.
9. Show me the final imports, service file, and any environment variable
   configuration needed.

My project is: [DESCRIBE YOUR PROJECT HERE]
My runtime is: Node.js [VERSION], TypeScript [VERSION]

License and credit

The source is copyright 2025 Google LLC, licensed under the Apache-2.0 license (see source/ file headers). Upstream package: @google/genai version 1.50.1. Full documentation: https://googleapis.github.io/js-genai/

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

전체 설치 가이드와 연동 프롬프트는 구매 후 열람할 수 있습니다.