Google Gen AI SDK for TypeScript and JavaScript は、開発者が Gemini モデルの最先端機能をアプリケーションにシームレスに統合することを可能にします。洗練されたチャットインターフェースの構築、クリエイティブなコンテンツの生成、またはマルチモーダル機能の活用を目指す場合でも、この SDK は堅牢で直感的なツールキットを提供します。Gemini API（Google AI Studio 経由）と Google Cloud の Vertex AI プラットフォームの両方を包括的にサポートしており、幅広いプロジェクトにとって汎用性の高い選択肢となります。このガイドでは、SDK の使用に関する基本事項を、初期設定から高度な機能の探求まで、公式ドキュメントとサンプルコードから直接引用した事実に基づいた実装詳細に焦点を当てて説明します。

利用開始：環境設定

SDK の機能に飛び込む前に、開発環境が前提条件を満たし、SDK がインストールされていることを確認してください。

前提条件

Google Gen AI SDK を使用するための主な前提条件は、Node.js バージョン 18 以降です。

インストール

SDK のインストールは npm を使用して簡単に行えます。ターミナルを開き、次のコマンドを実行します。

npm install @google/genai

このコマンドにより、必要なパッケージがプロジェクトにダウンロードおよびインストールされます。

クイックスタート：最初のインタラクション

Gemini モデルとの対話を開始する最も簡単な方法は、Google AI Studio から取得した API キーを使用することです。

コンテンツを生成する方法の簡単な例を次に示します。

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

// API キーが環境変数として設定されていることを確認してください
const GEMINI_API_KEY = process.env.GEMINI_API_KEY;

const ai = new GoogleGenAI({apiKey: GEMINI_API_KEY});

async function main() {
  try {
    const response = await ai.models.generateContent({
      model: 'gemini-2.0-flash-001', // または目的のモデル
      contents: '空が青いのはなぜですか？',
    });
    // response.text がテキストにアクセスする正しい方法であると仮定します（SDK構造に基づく）
    // 実際のレスポンス構造は response.candidates[0].content.parts[0].text である可能性があります
    // 簡単のため、README のクイックスタートに従い、概念的な 'response.text' を参照します。
    // より堅牢なアクセスは次のようになります：
    if (response.candidates && response.candidates.length > 0 &&
        response.candidates[0].content && response.candidates[0].content.parts &&
        response.candidates[0].content.parts.length > 0) {
      console.log(response.candidates[0].content.parts[0].text);
    } else {
      console.log("テキスト応答が受信されなかったか、予期しない構造です。");
    }
  } catch (error) {
    console.error("コンテンツ生成エラー:", error);
  }
}

main();

(注意：レスポンスオブジェクト内のテキストへの正確なパスは異なる場合があります。README.md はクイックスタートで簡潔にするために response.text を使用していますが、実際の API レスポンスはしばしば response.candidates[0].content.parts[0].text のようによりネストされています。使用しているメソッドの特定のレスポンス構造を常に参照してください。)

初期化：Gemini への接続

SDK は、Gemini Developer API または Vertex AI のいずれかで動作するように初期化できます。

Gemini Developer API

サーバーサイドアプリケーションの場合、API キーを使用して GoogleGenAI を初期化します。

import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({apiKey: 'YOUR_GEMINI_API_KEY'});

ブラウザでの使用：

ブラウザサイドアプリケーションでも初期化は同じです。ただし、重要なセキュリティ上の考慮事項があります。

注意：API キーのセキュリティ
API キーをクライアントサイドのコードに直接公開しないでください。本番環境では、API キーを保護するために常にサーバーサイドの実装を使用してください。開発目的または特定のユースケースでクライアントサイドの実装が避けられない場合は、厳格な API キー制限など、堅牢なセキュリティ対策を講じてください。

Vertex AI

SDK を Vertex AI で使用するには、Google Cloud プロジェクト ID とロケーションを指定する必要があります。

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

const ai = new GoogleGenAI({
    vertexai: true,
    project: 'your_google_cloud_project_id',
    location: 'your_google_cloud_location', // 例：'us-central1'
});

提供されている SDK サンプルの多くは、環境変数（GOOGLE_GENAI_USE_VERTEXAI、GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATION）を使用して、Gemini API と Vertex AI の構成を切り替えるパターンを示しています。

API バージョン選択

デフォルトでは、SDK はベータ API エンドポイントを利用して、API の最新のプレビュー機能へのアクセスを提供します。安定した API エンドポイントが必要な場合は、初期化中に API バージョンを指定できます。

Vertex AI で v1 安定 API を使用する場合：

const ai = new GoogleGenAI({
    vertexai: true,
    project: 'your_project',
    location: 'your_location',
    apiVersion: 'v1'
});

Gemini Developer API で v1alpha を使用する場合（例として、特定のバージョンは異なる場合があります）：

const ai = new GoogleGenAI({
    apiKey: 'YOUR_GEMINI_API_KEY',
    apiVersion: 'v1alpha'
});

コアコンセプト：`GoogleGenAI` オブジェクト

SDK のすべての機能は、GoogleGenAI クラスのインスタンスを介してアクセスされます。このオブジェクトは中央ハブとして機能し、関連する API メソッドを論理的なサブモジュールに編成します。

ai.models: Gemini モデルと対話するための主要なインターフェースです。テキストベースの生成のための generateContent、画像作成のための generateImages、動画合成のための generateVideos などのメソッドを格納しています。また、利用可能なモデルに関するメタデータ（例：get、list）を取得するためにも使用できます。
ai.caches: このサブモジュールは、Cache オブジェクトを作成および管理するためのツールを提供します。キャッシュは、同じ大きなプロンプトプレフィックスを繰り返し使用する場合に、コストとレイテンシを削減するのに特に役立ちます。プロンプトの最初の部分をキャッシュすることにより、後続の呼び出しでは新しい一意の部分のみを処理する必要があります。caches.ts サンプルは、キャッシュの作成と使用を示しています。
ai.chats: 会話型アプリケーションを構築するために、ai.chats を使用すると、ローカルでステートフルな Chat オブジェクトを作成できます。これらのオブジェクトは、会話履歴を自動的に維持することにより、マルチターンの対話の管理を簡素化します。chats.ts や chat_afc_streaming.ts などのサンプルがその使用法を示しています。
ai.files: このサブモジュールは、ファイルを扱う上で不可欠です。ai.files.upload を使用してファイル（画像、テキストなど）を API にアップロードし、プロンプト内でこれらのファイルを URI を使用して参照できます。これは、ファイルが複数回使用される場合に帯域幅を削減するのに役立ち、プロンプトにインラインで含めるには大きすぎるファイルには必要です。generate_content_with_file_upload.ts サンプルは、ai.files.get によるファイル処理ステータスの確認を含め、これを示しています。
ai.live: ai.live サブモジュールは、Gemini モデルとのリアルタイムでインタラクティブなセッションを可能にします。テキスト、音声、動画の入力をサポートし、テキストまたは音声の出力をサポートします。これは、即時のフィードバックや継続的な対話を必要とする動的なアプリケーションに最適です。live_client_content.ts サンプルは、ここでの重要なリファレンスです。

主な機能とその利用方法

Google Gen AI SDK には、多様な AI 搭載アプリケーションを構築するための機能が満載です。

Gemini 2.5 モデルによるアプリの容易な構築

SDK は、さまざまな生成タスクのために Gemini 2.5 モデルの能力を活用するプロセスを簡素化します。

コンテンツ生成（テキスト）

最も一般的なユースケースは、テキストベースのコンテンツの生成です。ai.models.generateContent() メソッドがこれの中心となります。

// 'ai' が初期化された GoogleGenAI インスタンスであると仮定します
async function generateMyContent() {
  const response = await ai.models.generateContent({
    model: 'gemini-2.0-flash-001', // または他の互換性のあるテキストモデル
    contents: 'ローマ帝国に関する面白い事実を教えてください。',
  });
  // レスポンスへのアクセス例：
  console.log(response.candidates[0].content.parts[0].text);
}

contents 引数の構造化：

generateContent（および関連メソッド）の contents パラメータは柔軟です。

Content: 単一の Content オブジェクトを提供すると、SDK はそれを自動的に配列でラップします。
Content[]: Content オブジェクトの配列を直接提供でき、これはマルチターンの会話または複数の情報を表します。
Part | string: 単一の Part オブジェクト（テキスト、インラインデータ、またはファイル URI）または単純な文字列は、ロール 'user' を持つ Content オブジェクトにラップされます。
Part[] | string[]: Part オブジェクトまたは文字列の配列は、ロール 'user' を持つ単一の Content オブジェクトに集約されます。

README.md からの重要な注意点：この自動ラッピングは FunctionCall および FunctionResponse パートには適用されません。これらについては、モデルによって話されたパートとユーザーによって話されたパートを明示的に定義するために、完全な Content[] 構造を提供する必要があります。

応答性のためのストリーミング

チャットボットなど、即時のフィードバックが必要なアプリケーションの場合、generateContentStream メソッドは非常に貴重です。モデルによって生成されると同時にレスポンスのチャンクを生成し、コンテンツを段階的に表示できます。

async function streamMyContent() {
  const responseStream = await ai.models.generateContentStream({
    model: 'gemini-2.0-flash-001',
    contents: 'フレンドリーなロボットについての短い物語を書いてください。',
  });

  let accumulatedText = "";
  for await (const chunk of responseStream) {
    if (chunk.text) { // チャンクにテキストが存在するか確認
      accumulatedText += chunk.text;
      console.log('受信チャンク：', chunk.text);
    }
  }
  console.log('完全なレスポンス：', accumulatedText);
}

generate_content_streaming.ts および chat_afc_streaming.ts サンプルは実用的な例を提供します。

関数呼び出し

関数呼び出しにより、Gemini モデルは外部システムや API と対話できます。モデルが呼び出すことができる関数（ツール）を定義すると、モデルは情報を取得したりアクションを実行したりするために、特定の引数でこれらの関数の実行を要求できます。このプロセスには、主に 4 つのステップが含まれます。

関数の宣言： FunctionDeclaration オブジェクトを使用して、関数の名前、説明、およびパラメータを定義します。パラメータタイプを指定するために Type enum（例：Type.OBJECT、Type.STRING、Type.NUMBER）が使用されます。
関数呼び出しを有効にして generateContent を呼び出す： tools 配列に関数宣言を提供し、toolConfig を構成します（例：functionCallingConfig: { mode: FunctionCallingConfigMode.ANY }）。
FunctionCall の処理： モデルのレスポンスには FunctionCall オブジェクトが含まれる場合があり、これはどの関数をどの引数で呼び出すかを示します。これらのパラメータを使用して実際の関数を実行します。
FunctionResponse の送信： 関数が実行された後、新しい generateContent 呼び出し（多くの場合チャット履歴の一部として）内の FunctionResponse パートとして結果をモデルに送信し、対話を続行します。

generate_content_with_function_calling.ts サンプルは FunctionDeclaration でこれを示しています。chat_afc_streaming.ts サンプルは、宣言と実行ロジックをバンドルする、より高度な CallableTool アプローチを紹介しています。

// chat_afc_streaming.ts からの簡略化された概念的なスニペット
import { GoogleGenAI, FunctionCallingConfigMode, FunctionDeclaration, Type, CallableTool, Part } from '@google/genai';

// ... (ai の初期化) ...

const controlLightFunctionDeclaration: FunctionDeclaration = { /* ... サンプル通り ... */ };

const controlLightCallableTool: CallableTool = {
  tool: async () => Promise.resolve({ functionDeclarations: [controlLightFunctionDeclaration] }),
  callTool: async (functionCalls: any[]) => { // `any` は簡潔さのため、特定の型を使用してください
    console.log('ツール呼び出し引数：', functionCalls[0].args);
    // 実際のツールロジックはここに記述します
    const responsePart: Part = {
      functionResponse: {
        name: 'controlLight',
        response: { brightness: 25, colorTemperature: 'warm' }, // レスポンス例
      },
    };
    return [responsePart];
  },
};

const chat = ai.chats.create({
  model: 'gemini-2.0-flash', // 関数呼び出しをサポートするモデルを確認してください
  config: {
    tools: [controlLightCallableTool],
    toolConfig: { functionCallingConfig: { mode: FunctionCallingConfigMode.AUTO } },
    // ...
  },
});

// ... (sendMessageStream とレスポンス処理) ...

Live API サポート (`ai.live`)

ai.live モジュールは、高度にインタラクティブなリアルタイムアプリケーションを構築するために設計されています。コンテンツの双方向ストリーミングを可能にし、テキスト、音声、動画の入力をサポートし、テキストまたは音声の出力を生成します。これは、ライブ文字起こし、音声制御アシスタント、またはインタラクティブなマルチモーダルエクスペリエンスなどのアプリケーションに最適です。

Live API を使用するための主なステップ：

接続： ai.live.connect() を使用してセッションを確立します。モデル名とコールバックのセットを提供します。
コールバック：
- onopen: 接続が正常に確立されたときにトリガーされます。
- onmessage: サーバーからメッセージ（LiveServerMessage）を受信したときに呼び出されます。このメッセージには、テキスト、データ（音声など）、またはターンの完了を示すサーバーコンテンツが含まれる場合があります。
- onerror: セッション中に発生したエラーを処理します。
- onclose: 接続が閉じられたときに呼び出されます。
構成： connect の config パラメータで、期待する出力の種類を示すために responseModalities（例：[Modality.TEXT]、[Modality.AUDIO]）を指定できます。
コンテンツの送信： session.sendClientContent() を使用してモデルにデータを送信します。これは、単純なテキストでも、インラインデータ（例：base64 エンコードされた画像や音声）を含むより複雑な構造でもかまいません。
ターンの処理： 対話は多くの場合ターンベースです。サーバーからのメッセージを処理し、「ターン」がいつ完了したか（message.serverContent.turnComplete によって示される）を判断するためのロジックが必要になります。
セッションのクローズ： session.close() を使用して接続を終了します。

sdk-samples/live_client_content.ts ファイルは明確な例を提供しています。

// live_client_content.ts からのスニペット、簡略化
import { GoogleGenAI, LiveServerMessage, Modality } from '@google/genai';
// ... (ai の初期化と waitMessage, handleTurn などのヘルパー関数) ...

async function live(client: GoogleGenAI, model: string) {
  const responseQueue: LiveServerMessage[] = []; // 受信メッセージを保存するため

  const session = await client.live.connect({
    model: model, // 例：'gemini-2.0-flash-live-001'
    callbacks: {
      onopen: () => console.log('ライブセッションが開かれました。'),
      onmessage: (message: LiveServerMessage) => responseQueue.push(message),
      onerror: (e: any) => console.error('ライブエラー：', e.message || e), // ErrorEvent または類似のもの
      onclose: (e: any) => console.log('ライブセッションが閉じられました：', e.reason || e), // CloseEvent または類似のもの
    },
    config: { responseModalities: [Modality.TEXT] }, // テキストレスポンスを期待
  });

  // 簡単なテキストを送信
  session.sendClientContent({ turns: 'Hello world' });
  await handleTurn(); // サーバーレスポンスを待機して処理するカスタム関数

  // テキストとインライン画像データを送信
  const turnsWithImage = [
    'この画像はただの黒ですが、見えますか？',
    {
      inlineData: {
        data: 'iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAAC0lEQVR4nGNgQAYAAA4AAamRc7EAAAAASUVORK5CYII=', // 2x2 の黒い PNG
        mimeType: 'image/png',
      },
    },
  ];
  session.sendClientContent({ turns: turnsWithImage });
  await handleTurn();

  session.close();
}

その他の関連サンプルには、live_client_content_with_url_context.ts（URL コンテキストのデモンストレーション）、live_music.ts（音楽関連の対話、音声機能を示唆）、および live_server.ts があり、これらは sdk-samples/index.html とともに、音声入力および出力ストリームの処理を含むライブ対話のためのバックエンドの設定を示しています。sdk-samples/index.html ファイルには、特にマイク音声をキャプチャし、Socket.IO を介してサーバーに送信し、サーバーから受信した音声を再生するためのクライアントサイド JavaScript が含まれており、リアルタイムの音声入出力を効果的に示しています。

MCP (Multi-modal Coherent Prompting) サポート

Multi-modal Coherent Prompting (MCP) は、Gemini モデルが複数の外部ツールやサービスと連携して対話することを可能にします。これは、多様な機能を活用できる複雑なエージェントを構築するための強力な機能です。SDK は、MCP クライアントを Gemini モデルのツールとして統合するための mcpToTool ユーティリティを提供します。

sdk-samples/mcp_client.ts サンプルは、2 つのモック MCP サーバー（1 つは色付きメッセージを「印刷」するためのもの、もう 1 つは「ビープ音」を鳴らすためのもの）を設定することでこれを示しています。これらはその後、generateContent にツールとして提供されます。

コアコンセプト：

MCP サーバー： McpServer インスタンスを作成します（@modelcontextprotocol/sdk/server/mcp.js から）。
サーバー上のツールの定義： server.tool() を使用して、MCP サーバーが公開する関数（例：print_message、beep）を定義します。これには、期待される入力パラメータの指定（サンプルではスキーマ検証に Zod を使用）と実行するロジックが含まれます。
サーバーの接続： サーバーはトランスポートメカニズム（例：ローカルテスト用の InMemoryTransport）を介して接続します。
MCP クライアント： McpClient（@modelcontextprotocol/sdk/client/index.js から）が作成され、サーバーのトランスポートに接続されます。
mcpToTool： @google/genai の mcpToTool 関数は、MCP クライアントを ai.models.generateContent() の tools 配列に渡すことができる形式に変換します。
モデルとの対話： Gemini モデルは、レスポンス生成の一部としてこれらの MCP ツールを呼び出すことを選択できます。これは標準の関数呼び出しと同様です。

// mcp_client.ts からの概念的なフロー
import { GoogleGenAI, mcpToTool, FunctionCallingConfigMode } from '@google/genai';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
// ... (ai の初期化、spinUpPrintingServer、spinUpBeepingServer はサンプル通り) ...

async function mcpSample(ai: GoogleGenAI) {
  const printingClient: Client = await spinUpPrintingServer();
  const beepingClient: Client = await spinUpBeepingServer();

  const response = await ai.models.generateContent({
    model: 'gemini-2.5-flash-preview-04-17', // MCP/高度なツール使用をサポートするモデル
    contents: 'プリンターを使用して緑色で "Hello MCP" と印刷し、その後ビープ音を鳴らしてください。',
    config: {
      tools: [mcpToTool(printingClient, beepingClient)], // MCP クライアントをツールとして提供
      toolConfig: {
        functionCallingConfig: {
          mode: FunctionCallingConfigMode.AUTO, // または .ANY
        },
      },
    },
  });
  // モデルはその後、MCP ツールをターゲットとする FunctionCall パートを発行します。
  // SDK と MCP クライアント/サーバーのセットアップが通信を処理します。
  // MCP における 'callTool' に相当するものは、サーバーの登録済みツールハンドラによって処理されます。
}

mcp_client_stream.ts サンプルは、ストリーミングを MCP 対話で使用する方法を示すことでこれを拡張しています。

TTS (Text-to-Speech) モデル

提供されているサンプルには、generateImages のような ai.models サブモジュールにスタンドアロンの「Text-to-Speech」または generateSpeech メソッドは明示的に含まれていませんが、SDK の機能は主に ai.live モジュールを介して TTS 機能を強力にサポートしています。

live_client_content.ts および sdk-samples/index.html（live_server.ts を使用）のセットアップで見られるように、Live API は音声出力を生成するように構成できます（responseModalities: [Modality.AUDIO]）。このようなセッションでモデルによってテキストが処理されると、結果として得られる音声出力は実質的に TTS になります。

sdk-samples/index.html のクライアントサイドコードには、サーバーから（その例では Socket.IO を介して）base64 エンコードされた音声データを受信し、それをデコードしてブラウザの AudioContext を使用して再生するロジックが含まれています。これは、ライブでインタラクティブなコンテキストでテキスト入力から音声を生成するためのエンドツーエンドのパイプラインを示しています。

// sdk-samples/index.html からの概念的なクライアントサイド音声再生
// socket.on('audioStream', async function (base64AudioMsg) {
//   const float32AudioData = base64ToFloat32AudioData(base64AudioMsg); // デコード関数
//   const audioCtx = new AudioContext();
//   const audioBuffer = audioCtx.createBuffer(1, float32AudioData.length, 24000); // サンプルレート
//   audioBuffer.copyToChannel(float32AudioData, 0);
//   const source = audioCtx.createBufferSource();
//   source.buffer = audioBuffer;
//   source.connect(audioCtx.destination);
//   source.start(0);
//   // ... キューイングロジック ...
// });

したがって、直接的な ai.models.textToSpeech() メソッドを呼び出すわけではありませんが、次の方法で TTS を実現します。

responseModalities に Modality.AUDIO を含めて ai.live.connect() を使用します。
session.sendClientContent() を介してテキストコンテンツを送信します。
音声が生成された場合、音声データ（おそらく message.data または類似のフィールドに、base64 エンコードされている可能性あり）を含む LiveServerMessage を処理します。
この音声データをクライアントサイドでデコードして再生します。

画像・動画生成モデル

SDK は、ビジュアルコンテンツを生成および操作するための専用メソッドを提供します。

画像生成 (`ai.models.generateImages`)

ai.models.generateImages() メソッドを使用すると、テキストプロンプトから画像を生成できます。

モデル： 画像生成モデルを指定します（例：generate_image.ts で使用されている imagen-3.0-generate-002）。
プロンプト： 生成したい画像のテキスト説明を提供します。
設定 (config)：
- numberOfImages: 特定の数の画像バリエーションを要求します。
- includeRaiReason: コンテンツ生成が影響を受ける場合に、Responsible AI に関連する理由をオプションで含めます。
- aspectRatio、mode、negativePrompt、seed などの他のパラメータを使用して、より詳細な制御を行うことができます（基本的な generate_image.ts ではすべてが明示的に示されているわけではありませんが、これらの存在は画像生成 API では一般的です）。

レスポンスには生成された画像が含まれ、通常はバイトデータ（response.generatedImages[0].image.imageBytes）として返され、これを保存または表示できます。

// generate_image.ts からのスニペット
import { GoogleGenAI } from '@google/genai';
// ... (ai の初期化) ...

async function generateMyImage() {
  const response = await ai.models.generateImages({
    model: 'imagen-3.0-generate-002',
    prompt: '夕焼け空に飛行車が飛び交う未来都市の風景。',
    config: {
      numberOfImages: 1,
      includeRaiReason: true,
    },
  });

  if (response?.generatedImages?.[0]?.image?.imageBytes) {
    const imageBytes = response.generatedImages[0].image.imageBytes;
    // imageBytes を処理します（例：ファイルに保存、ブラウザに表示）
    console.log('画像生成完了（バイト長）：', imageBytes.length);
  }
}

sdk-samples ディレクトリには、より高度な画像編集タスクのためのスクリプトも含まれています。

edit_image_control_reference.ts: 編集をガイドするために参照画像を使用する可能性があります。
edit_image_mask_reference.ts: マスクと参照に基づいてインペインティングまたはアウトペインティングを示唆します。
edit_image_style_transfer.ts: ある画像のスタイルを別の画像に転送します。
edit_image_subject_reference.ts: 参照によって定義された被写体に焦点を当てて画像を編集します。
upscale_image.ts: 生成された画像または既存の画像の解像度を上げるため。

これらは通常、入力画像、目的の変更を説明するプロンプト、および場合によってはマスクまたは参照画像の提供を伴います。

動画生成 (`ai.models.generateVideos`)

動画コンテンツの生成は非同期操作です。

生成の開始： ai.models.generateVideos() を呼び出し、以下を提供します。
- model: 動画生成モデル（例：generate_video.ts の veo-2.0-generate-001）。
- prompt: 動画のテキスト説明。
- config (オプション): numberOfVideos などのパラメータ。
  この呼び出しは Operation オブジェクトを返します。
完了のポーリング： 動画生成には時間がかかります。ai.operations.getVideosOperation({operation: operation}) を使用して、操作のステータスを定期的に確認する必要があります。operation.done が true になるまでループは続行されます。
動画の取得： done になると、operation.response.generatedVideos 配列に生成された動画ファイルへの参照が含まれます。
動画のダウンロード： ai.files.download({ file: videoReference, downloadPath: 'myvideo.mp4' }) を使用して動画ファイルを保存します。

// generate_video.ts からのスニペット、簡略化
import { GoogleGenAI } from '@google/genai';
// ... (ai の初期化と遅延関数) ...

async function generateMyVideo() {
  let operation = await ai.models.generateVideos({
    model: 'veo-2.0-generate-001',
    prompt: '花が咲くタイムラプス。',
    config: { numberOfVideos: 1 },
  });

  console.log('動画生成開始。オペレーション ID：', operation.name);

  while (!operation.done) {
    console.log('動画生成完了を待機中...');
    await delay(5000); // 再度確認する前に 5 秒待機
    operation = await ai.operations.getVideosOperation({ operation: operation });
  }

  console.log('動画生成完了。');
  const videos = operation.response?.generatedVideos;
  if (videos && videos.length > 0) {
    videos.forEach((video, i) => {
      console.log(`動画 ${i} をダウンロード中...`);
      // ここでの 'video' オブジェクトは、名前、URI などを持つ File オブジェクトです。
      ai.files.download({
        file: video, // File オブジェクトを直接渡す
        downloadPath: `generated_video_${i}.mp4`,
      }).then(() => {
        console.log(`動画 video${i}.mp4 がダウンロードされました。`);
      }).catch(e => console.error('ダウンロードエラー', e));
    });
  } else {
    console.log('動画は生成されませんでした。');
  }
}

Gemini API と Vertex AI のサポート：統一されたエクスペリエンス

Google Gen AI SDK の大きな強みは、Gemini API（通常は Google AI Studio の API キー経由でアクセス）と Vertex AI（Google Cloud の統合 MLOps プラットフォーム）の両方を一貫してサポートしている点です。

デュアル初期化： 「初期化」セクションで示したように、GoogleGenAI オブジェクトをいずれかのサービスをターゲットにするように構成できます。
一貫した API サーフェス： ほとんどの場合、メソッドとそのシグネチャ（generateContent、generateImages など）は、使用しているバックエンドサービスに関係なく同じままです。これにより、コードの移行が容易になり、それらを切り替える必要がある場合に抽象化レイヤーを提供できます。
サンプルコードの構造： sdk-samples ディレクトリのほとんどのファイル（例：generate_image.ts、chats.ts、live_client_content.ts）には、通常 GOOGLE_GENAI_USE_VERTEXAI のような環境変数に基づいて、Gemini API（コメント/変数ではしばしば "MLDev" または "GoogleAI" と呼ばれる）または Vertex AI のいずれかのために SDK を条件付きで初期化するロジックが含まれています。

README.md はその違いを明確にしています。

Vertex AI プラットフォームまたは Gemini Developer プラットフォームのいずれかでホストされているモデルは、この SDK を介してアクセスできます。

この統一されたアプローチにより開発が簡素化され、SDK が選択したバックエンドとの通信のニュアンスを処理する間、アプリケーションロジックに集中できます。

高度なトピックとその他の機能

コア機能以外にも、SDK はサンプル全体で示されているいくつかのその他の機能を提供します。

ファイルのアップロードと管理 (ai.files):
- ai.files.upload(): プロンプトで使用するファイル（テキスト、画像など）をアップロードします。generate_content_with_file_upload.ts サンプルは Blob のアップロードを示しています。
- config: アップロードされたファイルの displayName を指定します。
- アップロードは、name、uri、mimeType、および state を持つ File オブジェクトを返します。
- ai.files.get(): ファイルのメタデータを取得し、処理ステータス（例：PROCESSING、ACTIVE、FAILED）を確認します。ポーリングが必要な場合があります。
- createPartFromUri(): ファイル URI と MIME タイプから Part オブジェクトを簡単に作成し、contents に含めるためのユーティリティ。
セマンティックキャッシング (ai.caches):
- caches.ts サンプルは、ai.caches.create() を使用したキャッシュの作成を示しています。
- その後、リクエストにキャッシュ名/オブジェクトを提供することで、generateContent でこのキャッシュを使用できます。これは、共通のプロンプトプレフィックスの埋め込みを再利用するのに役立ち、コストを節約し、潜在的にレイテンシを改善します。
モデル情報：
- ai.models.get({ model: 'model-name' }): 特定のモデルに関する詳細情報を取得します。（get_model_info.ts で見られるように）
- ai.models.list(): 利用可能なモデルをリストします。（list_models.ts で見られるように）
コンテンツ生成のための構成オプション：
さまざまな generate_content_with_...ts サンプルは、多数の構成オプションを紹介しています。
- generate_content_with_safety_settings.ts: 有害な可能性のあるコンテンツをモデルがどのように処理するかを制御するための安全設定の構成を示しています。
- generate_content_with_system_instructions.ts: 会話全体でモデルの動作をガイドするためのシステムレベルの指示を提供する方法を示しています。
- generate_content_with_response_schema.ts: モデルの出力のための JSON スキーマを指定でき、構造化されたレスポンスを保証します。..._accept_json_schema.ts バリアントはこれを強調しています。
- generate_content_with_latlong.ts: 位置データを取り込む機能を示しています。
- generate_content_with_log_prob.ts: トークンの対数確率にアクセスするため。
- generate_content_with_model_configuration.ts: 一般的なモデル構成パラメータ。
- generate_content_with_search_grounding.ts: モデルのレスポンスを検索結果でグラウンディングします。
- generate_content_with_url_context.ts: 生成タスクのための URL コンテキストの提供。
アボートシグナル： abort_signal.ts サンプルは、進行中の API リクエストをキャンセルするために AbortController を使用する方法を示しており、これは長時間実行される操作やユーザーが開始したキャンセルを管理するために不可欠です。
API バージョニング詳細： api_version.ts は、API バージョン選択に関連するより詳細な例またはテストを提供する可能性があります。
チューニング： tunings.ts は、モデルのファインチューニングまたはチューニング済みモデルの管理に関連する機能を示唆していますが、詳細はサンプルのコードにあります。

まとめ

Google Gen AI SDK for TypeScript and JavaScript は、Gemini ファミリーのモデルの高度な機能への強力で柔軟な橋渡しを提供します。Gemini API と Vertex AI の両方をサポートし、ストリーミング、関数呼び出し、ライブマルチモーダルインタラクション、画像/動画生成、包括的なコンテンツ生成制御などの豊富な機能セットと組み合わせることで、次世代の AI アプリケーションを構築しようとしている開発者にとって優れた選択肢となります。

詳細な README.md、docs フォルダ内の構造化されたドキュメント、特に sdk-samples ディレクトリ内の豊富な実用的な例を探求することで、開発者は迅速に習熟し、イノベーションを開始できます。特にブラウザベースのアプリケーションでは、本番環境へのデプロイメントのためにサーバーサイドの実装を優先するか、堅牢なクライアントサイドのセキュリティ対策を講じることにより、常に API キーのセキュリティを優先することを忘れないでください。SDK は Gemini の機能とともに進化するように設計されているため、更新や新しいサンプルに注目することで、生成 AI の最新の進歩を活用していることを保証できます。