tessl/npm-google--genai

Google Gen AI JavaScript SDK for building applications powered by Gemini with content generation, image/video generation, function calling, caching, and real-time live sessions

Overview

Eval results

Files

Authentication Tokens

Name: tessl/npm-google--genai
Author: tessl

The Tokens class (accessed via client.authTokens) provides methods for creating ephemeral authentication tokens for use with constrained API access, particularly for Live API sessions. These tokens allow you to control access to Live API connections with specific constraints and expiration times.

Note: This feature is experimental and only supported in the Gemini Developer API (not Vertex AI), using API version v1alpha.

Capabilities

Create Authentication Token

Creates an ephemeral authentication token that can be used for secure, constrained access to Live API sessions. Tokens can be configured to lock specific fields in LiveConnectConfig, limiting what session configurations can be modified when the token is used.

/**
 * Creates an ephemeral auth token resource
 * @experimental
 * @param params - Parameters for creating the auth token
 * @returns Promise resolving to the created AuthToken
 * @throws Error if called on a Vertex AI client
 * @remarks Only supported in v1alpha API version of the Gemini Developer API
 */
function create(params: CreateAuthTokenParameters): Promise<AuthToken>;

interface CreateAuthTokenParameters {
  config?: CreateAuthTokenConfig;
}

interface CreateAuthTokenConfig {
  uses?: number;
  expireTime?: string;
  bidiGenerateContentSetup?: LiveConnectConstraints;
  lockAdditionalFields?: string[];
  httpOptions?: HttpOptions;
  abortSignal?: AbortSignal;
}

interface AuthToken {
  name?: string;
  uses?: number;
  expireTime?: string;
  usesRemaining?: number;
  createTime?: string;
}

Token Configuration Modes

Authentication tokens support multiple configuration modes that control which Live API connection parameters can be modified when using the token.

Mode 1: Unlocked Configuration

If bidiGenerateContentSetup is unset, the token allows full flexibility in LiveConnectConfig for each session connection.

import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({
  apiKey: 'YOUR_API_KEY',
  httpOptions: { apiVersion: 'v1alpha' }  // Required for auth tokens
});

// Create token with unlocked configuration
const token = await client.authTokens.create({
  config: {
    uses: 3,
    expireTime: '2025-05-01T00:00:00Z'
  }
});

console.log('Token created:', token.name);
console.log('Uses remaining:', token.usesRemaining);

// Use the token to connect to Live API with any configuration
const sessionClient = new GoogleGenAI({
  apiKey: token.name,
  httpOptions: { apiVersion: 'v1alpha' }
});

const session = await sessionClient.live.connect({
  model: 'gemini-2.0-flash',
  config: {
    responseModalities: ['AUDIO'],
    systemInstruction: 'Be helpful and concise'
    // Any configuration can be used
  }
});

Mode 2: Fully Locked Configuration

If bidiGenerateContentSetup is set, all fields in LiveConnectConfig are locked to the values specified in the setup. Attempts to change these fields when connecting will be ignored by the API.

// Create token with locked configuration
const token = await client.authTokens.create({
  config: {
    uses: 3,
    expireTime: '2025-05-01T00:00:00Z',
    bidiGenerateContentSetup: {
      setup: {
        model: 'gemini-2.0-flash',
        generationConfig: {
          responseModalities: ['AUDIO'],
          temperature: 0.7
        },
        systemInstruction: {
          parts: [{ text: 'Always answer in English.' }]
        }
      }
    }
  }
});

// When using this token, all config fields are locked
const sessionClient = new GoogleGenAI({
  apiKey: token.name,
  httpOptions: { apiVersion: 'v1alpha' }
});

const session = await sessionClient.live.connect({
  model: 'gemini-2.0-flash',  // Locked - cannot be changed
  config: {
    responseModalities: ['TEXT'],  // Ignored - locked to ['AUDIO']
    temperature: 1.0,              // Ignored - locked to 0.7
    systemInstruction: 'Speak Spanish'  // Ignored - locked to English
  }
});

Mode 3: Partially Locked with Additional Fields

If bidiGenerateContentSetup is set along with lockAdditionalFields, the specified fields from setup are locked, plus any additional fields listed in lockAdditionalFields.

// Create token with setup fields + additional locked fields
const token = await client.authTokens.create({
  config: {
    uses: 3,
    expireTime: '2025-05-01T00:00:00Z',
    bidiGenerateContentSetup: {
      setup: {
        model: 'gemini-2.0-flash',
        generationConfig: {
          responseModalities: ['AUDIO'],
          systemInstruction: {
            parts: [{ text: 'Always answer in English.' }]
          }
        }
      }
    },
    lockAdditionalFields: ['temperature', 'topK']
  }
});

// When connecting:
// - model: locked to 'gemini-2.0-flash'
// - responseModalities: locked to ['AUDIO']
// - systemInstruction: locked to 'Always answer in English.'
// - temperature: locked (cannot be modified)
// - topK: locked (cannot be modified)
// - Other fields like topP, maxOutputTokens can still be modified

Mode 4: Only Setup Fields Locked

If bidiGenerateContentSetup is set and lockAdditionalFields is an empty array, only the fields explicitly set in the setup are locked.

// Create token locking only specified setup fields
const token = await client.authTokens.create({
  config: {
    uses: 3,
    expireTime: '2025-05-01T00:00:00Z',
    bidiGenerateContentSetup: {
      setup: {
        model: 'gemini-2.0-flash',
        generationConfig: {
          responseModalities: ['AUDIO'],
          systemInstruction: {
            parts: [{ text: 'Always answer in English.' }]
          }
        }
      }
    },
    lockAdditionalFields: []  // Empty array means lock only setup fields
  }
});

// When connecting:
// - model: locked to 'gemini-2.0-flash'
// - responseModalities: locked to ['AUDIO']
// - systemInstruction: locked to 'Always answer in English.'
// - temperature, topK, topP, maxOutputTokens, etc. can be freely modified

Token Management

Token Expiration

Tokens expire based on the expireTime parameter. After expiration, the token can no longer be used to create sessions.

const token = await client.authTokens.create({
  config: {
    uses: 10,
    expireTime: '2025-12-31T23:59:59Z'  // Token expires at end of 2025
  }
});

// Check token details
console.log('Token expires:', token.expireTime);
console.log('Uses remaining:', token.usesRemaining);

Usage Limits

Tokens have a maximum number of uses specified by the uses parameter. Once the token has been used that many times, it cannot create new sessions.

const token = await client.authTokens.create({
  config: {
    uses: 5,  // Token can be used for 5 session connections
    expireTime: '2025-12-31T23:59:59Z'
  }
});

// Each session connection decrements usesRemaining
for (let i = 0; i < 3; i++) {
  const sessionClient = new GoogleGenAI({
    apiKey: token.name,
    httpOptions: { apiVersion: 'v1alpha' }
  });

  const session = await sessionClient.live.connect({
    model: 'gemini-2.0-flash',
    config: { responseModalities: ['AUDIO'] }
  });

  console.log(`Session ${i + 1} created`);
  session.close();
}

// Token now has 2 uses remaining

Type Definitions

interface LiveConnectConstraints {
  setup?: LiveConnectConstraintsSetup;
}

interface LiveConnectConstraintsSetup {
  model?: string;
  generationConfig?: LiveConnectConstraintsGenerationConfig;
  systemInstruction?: Content;
  tools?: Tool[];
}

interface LiveConnectConstraintsGenerationConfig {
  temperature?: number;
  topK?: number;
  topP?: number;
  maxOutputTokens?: number;
  responseModalities?: Modality[];
  seed?: number;
  speechConfig?: SpeechConfig;
}

Use Cases

Temporary Access for External Services

Create tokens for external services to access your Live API without sharing your main API key.

// Create a token for a third-party service
const token = await client.authTokens.create({
  config: {
    uses: 100,
    expireTime: '2025-06-01T00:00:00Z',
    bidiGenerateContentSetup: {
      setup: {
        model: 'gemini-2.0-flash',
        generationConfig: {
          responseModalities: ['AUDIO'],
          temperature: 0.8
        }
      }
    }
  }
});

// Share token.name with the external service
// They can use it without knowing your main API key
console.log('Token for external service:', token.name);

Rate-Limited Client Access

Provide rate-limited access to different client applications.

// Create tokens for different clients with different limits
const clientAToken = await client.authTokens.create({
  config: {
    uses: 1000,  // Premium client
    expireTime: '2025-12-31T23:59:59Z'
  }
});

const clientBToken = await client.authTokens.create({
  config: {
    uses: 100,  // Free tier client
    expireTime: '2025-12-31T23:59:59Z'
  }
});

console.log('Premium client token:', clientAToken.name);
console.log('Free tier token:', clientBToken.name);

Constrained Demo Applications

Create tokens with locked configurations for demo or testing purposes.

// Token for demo app with fixed, safe configuration
const demoToken = await client.authTokens.create({
  config: {
    uses: 50,
    expireTime: '2025-03-01T00:00:00Z',
    bidiGenerateContentSetup: {
      setup: {
        model: 'gemini-2.0-flash',
        generationConfig: {
          responseModalities: ['AUDIO'],
          temperature: 0.5,  // Conservative temperature
          maxOutputTokens: 1000  // Limit output length
        },
        systemInstruction: {
          parts: [{
            text: 'You are a demo assistant. Keep responses brief and appropriate.'
          }]
        }
      }
    }
  }
});

console.log('Demo token:', demoToken.name);

API Version Requirement

Important: Authentication tokens are only supported in the v1alpha API version. You must specify this version in your client configuration:

const client = new GoogleGenAI({
  apiKey: 'YOUR_API_KEY',
  httpOptions: {
    apiVersion: 'v1alpha'  // Required for auth tokens
  }
});

Platform Availability

Gemini Developer API: Supported (v1alpha only)
Vertex AI: Not supported - will throw an error if attempted

Install with Tessl CLI

npx tessl i tessl/npm-google--genai

docs

content-generation.md

embeddings.md

file-search-stores.md