Gemini Web-API Node.js Client

This is a TypeScript/Node.js reverse-engineered asynchronous Google Gemini client library. It replicates core web application features including authentication, multi-turn chat sessions, file uploads, and automatic session cookie rotation.

If you are looking for the OpenAI-compatible compatibility server, check out the apps/server application.

Features

• Browser TLS & HTTP2 Fingerprinting: Uses impit under the hood to bypass bot detection.
• Session/State Persistence: Persists multi-turn conversations ([cid, rid, rcid] metadata array) to continue conversations smoothly.
• Auto-Rotation of Cookies: Background interval refreshes session cookies using Google's rotation endpoints and updates cached cookies locally.
• File Upload Support: Allows uploading local files or buffers directly into the Gemini session for multimodal prompts.

Installation

Install the package via your preferred package manager:

npm install gemini-web-api
# or
pnpm add gemini-web-api
# or
yarn add gemini-web-api

Configure Environment

If using the default filesystem storage adapter, set up the required environment variables in your .env file:

# Default Gemini Web Client session cookies (from gemini.google.com)
GEMINI_SECURE_1PSID="your-secure-1psid-cookie"
GEMINI_SECURE_1PSIDTS="your-secure-1psidts-cookie"

# Optional configuration
GEMINI_COOKIE_PATH="./cookies.json"
GEMINI_ROTATION_INTERVAL_MS=180000

• GEMINI_SECURE_1PSID (Required): The default account's primary cookie value.
• GEMINI_SECURE_1PSIDTS (Recommended): The timestamp cookie, automatically updated by the rotator.
• GEMINI_COOKIE_PATH (Optional): Directory or file path where auto-rotated cookies and cached data will be saved. Defaults to ~/.gemini_webapi.
• GEMINI_ROTATION_INTERVAL_MS (Optional): Interval in milliseconds for background cookie rotation. Defaults to 3 minutes (180000 ms).

Available Scripts (Development)

If developing inside this package directory:

• pnpm build: Compiles the TypeScript code into ESM (dist/index.js), CJS (dist/index.cjs), and type definitions (dist/index.d.ts) using tsup.
• pnpm dev: Runs tsup in watch mode.
• pnpm lint: Runs tsc --noEmit to check for type errors.
• pnpm example: Runs the command-line chat demo (examples/chat.ts).

Library Usage Examples

Client Initialization

import { GeminiClient } from "gemini-web-api";

const client = new GeminiClient({
  cookies: {
    "__Secure-1PSID": process.env.GEMINI_SECURE_1PSID!,
    "__Secure-1PSIDTS": process.env.GEMINI_SECURE_1PSIDTS || "",
  },
  verbose: true,
});

// Initialize client (logs in, rotates cookies, sets up background refresh interval)
await client.init();

Active Chat Sessions (Multi-Turn Conversation)

// Start a new chat session with a specific model (default: "gemini-3-flash")
const chat = client.startChat({ model: "gemini-3-flash" });

// Send a simple message and wait for the response
const response = await chat.sendMessage("Hello! Introduce yourself.");
console.log(response.text);

// Or generate stream responses
const stream = chat.generateMessageStream("Tell me a long story.");
for await (const chunk of stream) {
  process.stdout.write(chunk.text);
}

💾 Custom Storage Adapters

By default, the library persists rotated cookie caches to the filesystem (via FileStorageAdapter). You can override this behavior by providing a custom StorageAdapter implementation (e.g., using Redis, databases, or Cloudflare Workers KV storage):

import { GeminiClient, StorageAdapter } from "gemini-web-api";

class MyCustomStorage implements StorageAdapter {
  async get(key: string): Promise<string | null> {
    // Retrieve value from database/cache
  }
  async set(key: string, value: string): Promise<void> {
    // Persist value to database/cache
  }
  async delete(key: string): Promise<void> {
    // Remove value from database/cache
  }
}

const client = new GeminiClient({
  cookies: {
    "__Secure-1PSID": "...",
    "__Secure-1PSIDTS": "...",
  },
  storage: new MyCustomStorage(),
});