Blog

Google Gen AI TypeScript/JavaScript SDK で強力な生成AIアプリケーションを構築する方法

Mark Ponomarev

Mark Ponomarev

27 5月 2025

Google Gen AI TypeScript/JavaScript SDK で強力な生成AIアプリケーションを構築する方法

人工知能の世界は急速に進化しており、Googleはその強力なGeminiモデルで最前線に立っています。この力を活用したいTypeScriptおよびJavaScript開発者にとって、Google Gen AI SDKは包括的で柔軟なソリューションを提供します。このSDKを使用すると、Gemini 2.5およびその他の最先端モデルを活用したアプリケーションを簡単に構築でき、Gemini Developer APIとVertex AIの両方に対して強固なサポートを提供します。この記事は、ライブのリアルタイムインタラクションやマルチモーダルコンテンツ処理から、テキスト読み上げ（TTS）、画像生成など、その主要な機能までを網羅し、このSDKを理解し活用するためのガイドとなるでしょう。

💡
美しいAPIドキュメントを生成する優れたAPIテストツールをお探しですか？

開発者チームが最大限の生産性で協力するための統合されたオールインワンプラットフォームをお探しですか？

Apidogはあなたのすべての要求を満たし、Postmanをはるかに手頃な価格で置き換えます！
ボタン

はじめに：JavaScriptとGeminiの力を繋ぐ

Google Gen AI JavaScript SDKは、開発者がGoogleの高度な生成AI機能をウェブおよびNode.jsアプリケーションに統合できるように綿密に設計されています。高度なチャットボット、知的なコンテンツ作成ツール、または多様なメディアタイプを理解し生成するアプリケーションを構築しているかどうかにかかわらず、このSDKは必要な構成要素を提供します。

SDKの核となる強みは、Gemini Developerプラットフォーム（Google AI StudioからのAPIキーを介して）またはGoogle CloudのVertex AIプラットフォームのどちらでホストされているかに関わらず、Geminiモデルにアクセスするための統一されたアプローチです。この柔軟性により、開発者はAPIキーを使用した迅速なプロトタイピングから、MLOps機能を備えたVertex AIでの本番環境レベルのデプロイまで、プロジェクトのニーズに最適な環境を選択できます。

このSDKは、待望のGemini 2.5モデルを含む最新のGemini機能とシームレスに連携するように設計されており、開発者は利用可能になり次第、最先端のAIにアクセスできます。

はじめに：インストールと初期化

高度な機能に入る前に、SDKのセットアップの基本を説明します。

前提条件：
開発環境にNode.jsバージョン18以降がインストールされていることを確認してください。

インストール：
SDKのインストールはnpmを使用して簡単に行えます：

npm install @google/genai

初期化 - Geminiへのゲートウェイ：
Google AI StudioまたはVertex AIを介したGemini APIとのすべてのインタラクションは、GoogleGenAIクラスのインスタンス化から始まります。

1. Gemini Developer APIを使用する（APIキーを使用）：
これは、特にサーバーサイドアプリケーションや個人プロジェクトの場合、開始する最も迅速な方法です。Google AI StudioからのAPIキーが必要です。

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

const GEMINI_API_KEY = process.env.GEMINI_API_KEY; // または実際のAPIキー
const ai = new GoogleGenAI({ apiKey: GEMINI_API_KEY });

async function run() {
  // 例：テキストコンテンツを生成する
  const model = ai.models.generateContent({
    model: "gemini-pro", // または特定のGemini 2.5モデル（例："gemini-2.5-flash-001"）
    contents: [{ role: "user", parts: [{ text: "Google Gen AI SDKの重要性について説明してください。" }] }]
  });
  const response = await model;
  console.log(response.text);
}

run();
APIキーのセキュリティに関する注意：

2. Vertex AIを使用する：
Google Cloudの堅牢性とスケーラビリティを必要とするアプリケーションの場合、Vertex AI用にSDKを初期化するのが適切な方法です。これには、Google CloudプロジェクトIDとロケーションを指定する必要があります。

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

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

async function runVertex() {
  // 例：Vertex AIでテキストコンテンツを生成する
  const model = ai.models.generateContent({
    model: "gemini-1.5-pro-preview-0409", // Vertex AIモデルの例
    contents: [{ role: "user", parts: [{ text: "Gen AI SDKでVertex AIを使用する利点は何ですか？" }] }]
  });
  const response = await model;
  console.log(response.text);
}

runVertex();

APIバージョンの選択：
デフォルトでは、SDKはベータ版APIエンドポイントを利用して、プレビュー機能への早期アクセスを提供します。ただし、安定性を必要とするアプリケーションの場合、初期化時にv1（安定版）またはその他の特定のAPIバージョン（Gemini APIの特定のプレビュー機能の場合はv1alphaなど）を明示的に選択できます：

Vertex AIの場合（v1に設定）：

const ai = new GoogleGenAI({
    vertexai: true,
    project: 'your-gcp-project-id',
    location: 'your-gcp-location',
    apiVersion: 'v1'
});

Gemini Developer APIの場合（ai.liveなどの機能のためにv1alphaに設定）：

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

コアSDK構造：GoogleGenAIオブジェクト

初期化されると、aiオブジェクト（GoogleGenAIのインスタンス）はSDKの機能への主要なインターフェースとなります。これは、さまざまなサブモジュールへのアクセスを提供し、それぞれが特定の機能に対応しています：

Gemini 2.5モデルを使用したアプリの構築

SDKは、Gemini 2.5モデル（およびGemini 1.0 Pro、1.5 Pro、1.5 Flashなどの以前のバージョン）の力への直接的なアクセスを提供します。特定のモデルを使用するには、ai.models.generateContent()などのメソッドのmodelパラメータで、またはai.chats.create()でチャットセッションを作成する際に、その名前を参照するだけです。

たとえば、gemini-2.5-flash-001モデルを使用するには（仮称、リリースされた実際のモデル識別子に置き換えてください）：

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash-001', // 特定のモデル識別子を使用
  contents: [{ role: "user", parts: [{ text: "Gemini 2.5の主な進歩について教えてください。" }] }]
});
console.log(response.text);

SDKが基盤となるAPI呼び出しを処理するため、プロンプトの作成と生成されたコンテンツの処理に集中できます。Googleが新しいモデルをリリースし、既存のモデルを更新するにつれて、モデル識別子文字列を変更するだけで通常はそれらに切り替えることができ、アプリケーションを最先端の状態に保つことが容易になります。

詳細解説：マルチモーダルコンテンツ処理（MCP）

Geminiモデルの最も強力な側面の1つは、複数のモダリティ（テキスト、画像、音声、ビデオ）にわたるコンテンツを理解し生成する能力です。Google Gen AI SDKはこれを完全にサポートしており、リッチなマルチモーダルアプリケーションを構築できます。

MCPは、主にgenerateContentやsendMessage（チャット内）などのメソッドのcontentsパラメータを介して実現されます。contents配列は一連のContentオブジェクトを受け取り、それぞれが複数のPartオブジェクトを含むことができます。各Partは異なる種類のデータを表すことができます。

マルチモーダルコンテンツの構造：

例：マルチモーダルプロンプト（テキストと画像）：

import { GoogleGenAI } from '@google/genai';
// ... (初期化)

async function describeImage() {
  // 'base64ImageData'はJPEG画像のBase64エンコードされた文字列であると仮定します
  const base64ImageData = "..."; // あなたのBase64画像データ

  const contents = [
    {
      role: "user",
      parts: [
        { text: "この画像には何がありますか？" },
        {
          inlineData: {
            mimeType: "image/jpeg",
            data: base64ImageData,
          },
        },
      ],
    },
  ];

  const response = await ai.models.generateContent({
    model: "gemini-pro-vision", // またはGemini 2.5のビジョン対応モデル
    contents: contents,
  });
  console.log(response.text);
}

describeImage();

プロンプトで異なるデータタイプをシームレスにブレンドできるこの能力は、ビジュアルQ&Aシステムからビデオコンテンツを分析および説明するツールまで、アプリケーションの可能性の膨大な配列を開きます。SDKは画像*生成*のための直接的なメソッドを提供しますが、ビデオ*生成*はSDKの直接的なメソッドとしては明示的に提供されていません。代わりに、ビデオは主に入力モダリティとして扱われます。ただし、generateContentを介してアクセスされる高度なマルチモーダルモデルは、要約やビデオコンテンツに関する質問への回答など、洗練された方法でビデオ入力の処理と応答が可能かもしれません。

Live API（ai.live）を使用したリアルタイムインタラクション

低レイテンシで対話的な体験を要求するアプリケーションにとって、ai.liveサブモジュールはゲームチェンジャーです。現在プレビュー中であり、Gemini APIの場合はv1alpha APIバージョンを必要とするai.liveは、Geminiモデルとの双方向ストリーミングのためのWebSocket接続を確立します。これにより、入力としてテキスト、オーディオチャンク、さらにはビデオフレームをリアルタイムで送信し、出力としてテキストまたはオーディオを受信できます。

ai.liveの主要な概念：

  1. ai.live.connect(params)：これがエントリポイントです。モデル名（model）、接続構成（config）、およびさまざまなWebSocketイベント（例：onopen、onmessage、onerror、onclose）のコールバック関数（callbacks）などのパラメータを提供します。これは、Sessionオブジェクトに解決されるPromiseを返します。
  2. Sessionオブジェクト：アクティブなWebSocket接続を表します。次のメソッドがあります：

構成（LiveConnectParametersおよびLiveConnectConfig）：

コールバック（LiveCallbacks）：

例：基本的なai.liveセットアップ（概念）：

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

// Gemini APIの場合はapiVersion: 'v1alpha'で初期化されていることを確認してください
const ai = new GoogleGenAI({ apiKey: 'YOUR_GEMINI_API_KEY', apiVersion: 'v1alpha' });

async function startLiveSession() {
  try {
    const session = await ai.live.connect({
      model: 'gemini-pro', // またはライブをサポートする特定のモデル、ドキュメントを確認してください
      config: {
        responseModalities: [Modality.TEXT, Modality.AUDIO], // テキストとオーディオを期待する
        // speechConfig: { ... } // TTSの場合、以下で説明
      },
      callbacks: {
        onopen: () => console.log('ライブセッションに接続しました！'),
        onmessage: (serverMessage) => {
          // サーバーからのメッセージを処理する
          // これはテキスト、オーディオデータ、ツール呼び出しなどである可能性があります
          console.log('サーバーから受信：', serverMessage);
          if (serverMessage.speechUpdate?.audio) {
            // 受信したオーディオデータを処理する（例：再生）
            const audioBytes = serverMessage.speechUpdate.audio;
            // ... あなたのオーディオ再生ロジック ...
          }
          if (serverMessage.textUpdate?.text) {
             console.log("テキスト：", serverMessage.textUpdate.text);
          }
        },
        onerror: (error) => console.error('ライブセッションエラー：', error),
        onclose: () => console.log('ライブセッションが閉じられました。'),
      },
    });

    // これでメッセージを送信できます
    session.sendClientContent({ turns: [{ role: 'user', parts: [{text: 'こんにちは、ライブGemini！'}] }] });

    // 連続的なオーディオ入力の場合：
    // navigator.mediaDevices.getUserMedia({ audio: true }).then(stream => {
    //   const mediaRecorder = new MediaRecorder(stream);
    //   mediaRecorder.ondataavailable = event => {
    //     if (event.data.size > 0) {
    //       session.sendRealtimeInput({ media: { mediaChunks: [event.data] } });
    //     }
    //   };
    //   mediaRecorder.start(1000); // 毎秒オーディオチャンクを送信
    // });

    // 終了したらセッションを閉じることを忘れないでください
    // session.close();

  } catch (error) {
    console.error('ライブセッションへの接続に失敗しました：', error);
  }
}

startLiveSession();

ai.liveモジュールは、異なるモダリティにわたるユーザー入力にリアルタイムで反応し、真に対話的で応答性が高いと感じられるアプリケーションを構築するのに非常に強力です。

テキスト読み上げ（TTS）モデルと機能

SDKはテキスト読み上げ（TTS）生成を容易にし、主にオーディオ出力が要求された場合のai.liveインターフェースを介して行われます。これにより、Geminiモデルがテキストだけでなく、音声で応答できるようになります。

TTS構成（SpeechConfigおよびVoiceConfig）：

ai.live.connect()を使用してライブ接続を確立する際、configパラメータ内でspeechConfigを指定できます。

例：ライブセッションでのオーディオ出力の要求：

// ai.live.connectパラメータ内：
// ...
config: {
  responseModalities: [Modality.AUDIO], // TTSに不可欠
  speechConfig: {
    voiceConfig: {
      // 実際に利用可能なプリビルド音声名に置き換えてください
      prebuiltVoice: 'aura-asteria-en',
    }
  }
},
callbacks: {
  onmessage: (serverMessage) => {
    if (serverMessage.speechUpdate?.audio) {
      const audioData = serverMessage.speechUpdate.audio; // これはArrayBufferです
      // このオーディオデータをブラウザで再生するか、Node.jsで保存するロジック
      // 例：ブラウザの場合：
      // const audioBlob = new Blob([audioData], { type: 'audio/mpeg' }); // または適切なMIMEタイプ
      // const audioUrl = URL.createObjectURL(audioBlob);
      // new Audio(audioUrl).play();
      console.log('TTS用のオーディオデータを受信しました。');
    }
    if (serverMessage.textUpdate?.text) {
        console.log("付随するテキスト（もしあれば）：", serverMessage.textUpdate.text)
    }
  },
  // ... その他のコールバック
},
// ...

オーディオ出力用に構成されている場合、ライブセッションのonmessageコールバックはServerMessageオブジェクトを受信します。メッセージに音声が含まれている場合、speechUpdate.audioフィールドにオーディオデータ（通常ArrayBufferとして）が保持されます。その後、このデータを処理してユーザーに再生するか、オーディオファイルとして保存できます。textUpdate.textフィールドも音声のテキストバージョンで入力される場合があります。

TTSをライブの会話フローに直接統合することで、SDKはボイスファーストアプリケーション、対話型アシスタント、アクセシビリティ機能に最適になります。

画像生成モデル

SDKは、Imagenのようなモデルを使用して画像を生成するための専用メソッドai.models.generateImages()を提供します。このメソッドを使用すると、テキストプロンプトを提供し、生成された画像データを受信できます。

ai.models.generateImages()の使用：

このメソッドはGenerateImagesParametersを受け取ります。これには以下が含まれます：

例：画像を生成する：

import { GoogleGenAI } from '@google/genai';
// ... (Vertex AIの初期化、ImagenはしばしばVertex AIサービスであるため)
const ai = new GoogleGenAI({ vertexai: true, project: 'your-gcp-project-id', location: 'your-gcp-location' });


async function createImage() {
  try {
    const response = await ai.models.generateImages({
      model: 'imagen-3.0-generate-002', // 最新のモデルについてはドキュメントを確認してください
      prompt: '夕暮れ時の未来都市、飛行する乗り物とネオンライト。',
      config: {
        numberOfImages: 1,
        aspectRatio: '16:9',
        includeRaiReason: true,
      },
    });

    if (response?.generatedImages && response.generatedImages.length > 0) {
      const imageBytesBase64 = response.generatedImages[0]?.image?.imageBytes;
      if (imageBytesBase64) {
        // imageBytesBase64は画像のBase64エンコードされた文字列です
        console.log('画像が生成されました（Base64エンコード）！');
        // その後、この画像をブラウザに表示（例：<img src="data:image/png;base64,..." />）
        // またはNode.jsでファイルに保存したりできます
      }
    } else {
      console.log('画像が生成されなかったか、RAIでフィルタリングされました：', response?.raiFilteredReason);
    }
  } catch (error) {
    console.error('画像生成エラー：', error);
  }
}

createImage();

応答（GenerateImagesResponse）には、GeneratedImageオブジェクトの配列が含まれます。各オブジェクトには、画像データ（多くの場合Base64形式のimageBytesとして）、フィルタリングされた場合はraiFilteredReason、およびその他のメタデータが含まれる場合があります。

ビデオ処理（入力として）

前述のように、SDKは生成された出力としてではなく、主に入力モダリティとしてビデオを扱います。マルチモーダルGeminiモデルへのプロンプトにビデオデータを含める方法はいくつかあります：

ビデオファイルのアップロード（ai.files.upload() - Gemini API）：
ai.filesサブモジュールを使用してビデオファイル（例：MP4）をアップロードできます。アップロード後、ContentオブジェクトのfileData部分で参照できるファイルURIを受け取ります。

// ファイルアップロードの概念例（Gemini API）
// const uploadedFile = await ai.files.upload({
//   file: pathToYourVideoFile, // またはブラウザでのBlob
//   mimeType: 'video/mp4',
//   displayName: 'my-cool-video.mp4'
// });
// const videoFileUri = uploadedFile.uri;

const contents = [{
  role: "user",
  parts: [
    { text: "このビデオを要約してください。" },
    { fileData: { mimeType: "video/mp4", fileUri: "YOUR_UPLOADED_VIDEO_URI_HERE" } },
    // オプションでVideoMetadataを追加
    // { videoMetadata: { startOffset: "0s", endOffset: "30s" } } // 最初の30秒を処理
  ]
}];

Google Cloud Storage URIの使用（Vertex AI）：
Vertex AIを使用する場合、Google Cloud Storageバケットに保存されているビデオファイルを、fileData部分でそのgs:// URIを使用して直接参照できます。

ライブビデオフレーム（ai.live）：
ai.liveセクションで説明したように、session.sendRealtimeInput()を使用して個々のビデオフレーム（Blobオブジェクトとして、おそらくimage/jpegやimage/pngのような画像mimetypes）を送信できます。これにより、ライブビデオフィードに基づくリアルタイム分析またはインタラクションが可能になります。

startOffsetとendOffsetを持つVideoMetadataインターフェースを使用すると、モデルが焦点を当てるべきビデオファイルのセグメントを指定でき、これは長いビデオの処理に役立ちます。

Gemini API vs. Vertex AIサポート：デュアルアプローチ

Google Gen AI SDKの大きな利点は、Gemini Developer API（Google AI Studio経由）とVertex AIの両方をシームレスにサポートしていることです。このデュアルサポートは、開発者に柔軟性と明確なアップグレードパスを提供します。

SDKは多くの違いを抽象化します。ai.models.generateContent()のようなコアメソッドは両方で同様に機能し、主な違いは初期化（apiKey vs. vertexai: true, project, location）です。これにより、Gemini APIから開始し、アプリケーションが成熟し、スケーリングするにつれてVertex AIに移行できます。AIロジックを完全に書き直す必要はありません。メソッドのドキュメントは、機能またはパラメータが1つのプラットフォームに固有であるかどうかをしばしば指定します。

結論：次世代AIアプリのためのツールキット

Google Gen AI TypeScript/JavaScript SDKは、Gemini 2.5およびその他の高度なモデルの機能をJavaScript開発者に直接もたらす、強力で多用途なツールキットです。マルチモーダルコンテンツのサポート、Live APIを介したリアルタイムインタラクション、統合されたTTS、画像生成、およびGemini Developer APIとVertex AIの間で選択できる柔軟性により、不可欠なリソースとなっています。

SDKの構造、そのコアモジュール（ai.models、ai.live、ai.chats、ai.files、ai.caches）、およびマルチモーダルプロンプトのニュアンスを理解することで、これまで以上に豊かな方法で世界を見て、聞いて、話し、理解できる革新的なアプリケーションを構築する準備が整っています。GoogleがAIの境界を押し広げ続けるにつれて、このSDKは、あなたのJavaScriptおよびTypeScriptプロジェクト内でその可能性を解き放つための鍵となるでしょう。今すぐ飛び込み、実験し、AIを活用したアプリケーションの未来を構築しましょう！

この記事は、README.mdおよびdocsディレクトリから収集した情報に基づいて生成されました。指定されたすべてのトピックをカバーし、要求された文字数を目指しています。

ApidogでAPIデザイン中心のアプローチを取る

APIの開発と利用をよりシンプルなことにする方法を発見できる

無料会員登録ダウンロード