googleapis/js-genai

Google Gen AI SDK for TypeScript & JavaScript

概要 – Googleが公式に管理するnpmパッケージ (@google/genai) で、Gemini 2.0+ API（パブリックなGemini Developer APIおよびGemini Enterprise Agent Platform）をラップしています。JavaScript/TypeScriptコードに対して、以下の機能のための軽量で慣用的なレイヤーを提供します：

テキスト、画像、音声、動画の生成
ストリーミングレスポンス
関数 (ツール) 呼び出し / 自動関数呼び出し
ステートフルなチャットセッション
ファイルアップロード、ライブセッション処理、および新しい Interactions 統合API

対象ユーザー – Node.jsやブラウザから、生のHTTPリクエストを書くことなくGeminiモデルを呼び出したいフロントエンドまたはバックエンド開発者。

主要な概念

概念	機能
`GoogleGenAI` クラス	エントリポイント。認証設定（APIキーまたはエンタープライズ認証情報）を保持し、サブモジュール (`models`, `chats`, `caches`, `files`, `live`, `interactions`) を作成します。
`ai.models.generateContent`	テキスト（またはマルチモーダル）生成のための単発リクエスト。
`generateContentStream`	モデルがストリーミング出力する際に部分的なチャンクを生成する非同期イテレータ。
`ai.chats`	会話履歴を保持し、複数ターンの対話を簡素化するローカルの `Chat` オブジェクトを作成します。
`ai.caches`	サーバー側のプロンプトキャッシュを管理し、繰り返される長いプレフィックスのトークンコストを削減します。
`ai.files`	大きなファイル（画像、音声、PDFなど）をアップロードし、プロンプト内で参照します。
`ai.live`	ライブ音声/動画を受け取り、ライブ出力を返すリアルタイムセッションを開始します。
`ai.interactions`	モデル呼び出し、チャット状態、ツールオーケストレーション、長時間実行タスク（例：ディープリサーチエージェント）を統合する高レベルAPI。
関数呼び出し / ツール	JSON-schema関数を宣言し、Geminiに呼び出させ、その結果をフィードバックします。
自動継続	SDKは、無効にしない限り自動的に継続トークンに従います。

インストール

npm install @google/genai

クイックスタート (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);

同じコンストラクタがブラウザでも動作しますが、キーはサーバー側に保持すべきであるとREADMEで警告されています。

Enterprise-Agentの初期化

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

環境変数 (GOOGLE_GENAI_USE_ENTERPRISE, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION) も使用可能です。

ストリーミングの例

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

関数呼び出し (ツール) の例

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);

SDKは functionCalls 配列を返し、それを実行して後続のリクエスト（または ai.chats）を通じてフィードバックできます。

Interactions API (ステートフル、エージェントスタイル)

// 1ターン目
const i1 = await ai.interactions.create({model: 'gemini-flash-latest', input: 'Hi, I am Amir.'});
// 2ターン目 – 会話コンテキストを保持
const i2 = await ai.interactions.create({
  model: 'gemini-flash-latest',
  input: 'What is my name?',
  previous_interaction_id: i1.id
});

ディープリサーチエージェント、マルチモーダル入力、組み込みツール（Google検索、コード実行）、カスタム関数ツールをサポートしています。

エラーハンドリング – すべてのAPIエラーは、name、message、HTTP status フィールドを持つ ApiError として表面化します。

バージョンと互換性に関する注意

現在のSDKはNode 20+で動作します。バージョン3.0.0からはNode 22+が必要です。古いランタイムが必要な場合は <3.0.0 に固定してください。
次のメジャーリリースでは、自動関数呼び出しが Models.generateContent から Chats モジュールに移動されます。
一部のフィールドは非推奨になっています (LiveConnectConfig.generation_config, generate_videos 内の prompt/text/image など)。

詳細情報

完全なドキュメント: https://googleapis.github.io/js-genai/
サンプルプロジェクト: https://github.com/googleapis/js-genai/tree/main/sdk-samples
コード生成ガイダンス: リポジトリ内の codegen_instructions.md。

結論 – このリポジトリは、JavaScript/TypeScript開発者がGoogleのGeminiモデル（エンタープライズエージェントを含む）をアプリに統合できるようにする、本格的なプロダクショングレードのSDKです。ストリーミング、チャット状態、ツール呼び出し、マルチモーダルデータをサポートしています。

googleapis/js-genai

Google Gen AI SDK for TypeScript & JavaScript

関連