Gemini Live API

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

Gemini Live API を使用すると、テキスト、音声、動画の入力に対して音声やテキストの出力を返す低レイテンシの双方向インタラクションを実現できます。これにより、人間とやり取りするような自然な音声会話が可能となります。また、いつでもモデルとのやりとりを中断できます。モデルが動画を理解できるようになることでコミュニケーション手段が多様化し、カメラ入力やスクリーンキャストを共有して質問することが可能になります。

機能

Live API の主な機能は次のとおりです。

• マルチモダリティ: モデルは、見て、聞いて、会話できます。
• 低レイテンシのリアルタイム インタラクション: モデルは、すばやくレスポンスを返すことができます。
• セッション メモリ: モデルは、1 つのセッションで行われたすべてのインタラクションを記憶し、以前に聞いたことや見たことがある情報を思い出すことができます。
• 関数呼び出し、コードの実行、Search as a Tool のサポート: モデルを外部サービスやデータソースと統合できます。

Live API は、サーバー間通信用に設計されています。

ウェブアプリとモバイルアプリについては、Daily のパートナーによるインテグレーションを使用することをおすすめします。

始める

Live API を試すには、Vertex AI Studio に移動し、[セッションを開始] をクリックします。

Live API は、WebSockets を使用するステートフル API です。

このセクションでは、Python 3.9 以降を使用して、Live API でテキストからテキストを生成する方法の例を示します。

pip install --upgrade google-genai

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=True

from google import genai
from google.genai.types import (
    Content,
    LiveConnectConfig,
    HttpOptions,
    Modality,
    Part,
)

client = genai.Client(http_options=HttpOptions(api_version="v1beta1"))
model_id = "gemini-2.0-flash-live-preview-04-09"

async with client.aio.live.connect(
    model=model_id,
    config=LiveConnectConfig(response_modalities=[Modality.TEXT]),
) as session:
    text_input = "Hello? Gemini, are you there?"
    print("> ", text_input, "\n")
    await session.send_client_content(
        turns=Content(role="user", parts=[Part(text=text_input)])
    )

    response = []

    async for message in session.receive():
        if message.text:
            response.append(message.text)

    print("".join(response))
# Example output:
# >  Hello? Gemini, are you there?
# Yes, I'm here. What would you like to talk about?

インテグレーション ガイド

このセクションでは、Live API とのインテグレーションの仕組みについて説明します。

セッション

WebSocket 接続で、クライアントと Gemini サーバー間のセッションが確立されます。

クライアントが新しい接続を開始すると、セッションがサーバーとメッセージを交換し、次のことを実行できます。

• テキスト、音声、動画を Gemini サーバーに送信する。
• Gemini サーバーから音声、テキスト、関数呼び出しリクエストを受信する。

セッション構成は、接続後の最初のメッセージで送信されます。セッション構成には、モデル、生成パラメータ、システム指示、ツールが含まれます。

次の構成例をご覧ください。

{
  "model": string,
  "generationConfig": {
    "candidateCount": integer,
    "maxOutputTokens": integer,
    "temperature": number,
    "topP": number,
    "topK": integer,
    "presencePenalty": number,
    "frequencyPenalty": number,
    "responseModalities": [string],
    "speechConfig": object
  },

  "systemInstruction": string,
  "tools": [object]
}

詳細については、BidiGenerateContentSetup をご覧ください。

メッセージを送信する

メッセージは、WebSocket 接続を介して交換される JSON 形式のオブジェクトです。

メッセージを送信するには、クライアントはオープンな WebSocket 接続を介して JSON オブジェクトを送信する必要があります。JSON オブジェクトには、次のオブジェクト セットのフィールドを 1 つだけ含める必要があります。

{
  "setup": BidiGenerateContentSetup,
  "clientContent": BidiGenerateContentClientContent,
  "realtimeInput": BidiGenerateContentRealtimeInput,
  "toolResponse": BidiGenerateContentToolResponse
}

サポートされているクライアント メッセージ

サポートされているクライアント メッセージについては、次の表をご覧ください。

メッセージを受信する

Gemini からメッセージを受信するには、WebSocket の「message」イベントをリッスンし、サポートされているサーバー メッセージの定義に従って結果を解析します。

以下をご覧ください。

ws.addEventListener("message", async (evt) => {
  if (evt.data instanceof Blob) {
    // Process the received data (audio, video, etc.)
  } else {
    // Process JSON response
  }
});

サーバー メッセージには、次のオブジェクト セットのフィールドが 1 つだけ含まれます。

{
  "setupComplete": BidiGenerateContentSetupComplete,
  "serverContent": BidiGenerateContentServerContent,
  "toolCall": BidiGenerateContentToolCall,
  "toolCallCancellation": BidiGenerateContentToolCallCancellation
  "usageMetadata": UsageMetadata
  "goAway": GoAway
  "sessionResumptionUpdate": SessionResumptionUpdate
  "inputTranscription": BidiGenerateContentTranscription
  "outputTranscription": BidiGenerateContentTranscription
}

サポートされているサーバー メッセージ

サポートされているサーバー メッセージについては、次の表をご覧ください。

コンテンツの増分更新

増分更新を使用して、テキスト入力の送信、セッション コンテキストの確立、セッション コンテキストの復元を行います。コンテキストが短い場合は、ターンバイターンのインタラクションを送信して、イベントの正確なシーケンスを表すことができます。コンテキストが長い場合は、1 つのメッセージの概要を提供して、後続のインタラクション用にコンテキスト ウィンドウを空けておくことをおすすめします。

次のコンテキスト メッセージの例をご覧ください。

{
  "clientContent": {
    "turns": [
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
          "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turnComplete": true
  }
}

コンテンツ部分は functionResponse 型にできますが、モデルから発行された関数呼び出しにレスポンスを返す際に BidiGenerateContentClientContent を使用しないでください。代わりに BidiGenerateContentToolResponse を使用してください。BidiGenerateContentClientContent を使用するのは、以前のコンテキストを確立する場合や、会話中にテキスト入力を行う場合のみにしてください。

ストリーミング音声およびストリーミング動画

コードの実行

コードの実行の詳細については、コードの実行をご覧ください。

関数呼び出し

すべての関数は、BidiGenerateContentSetup メッセージの一部としてツール定義を送信することで、セッションの開始時に宣言する必要があります。

関数は JSON を使用して定義します。具体的には、OpenAPI スキーマ形式のサブセットを選択します。1 つの関数宣言に含めることができるパラメータは、次のとおりです。

• name（文字列）: API 呼び出し内の関数に対する固有識別子。

• description（文字列）: 関数の目的と機能についての包括的な説明。

• parameters（オブジェクト）: 関数に必要な入力データを定義します。

  • type（文字列）: 全体的なデータ型（オブジェクトなど）を指定します。

  • properties（オブジェクト）: 個々のパラメータを一覧表示します。各パラメータには次の情報が含まれます。

    • type（文字列）: パラメータのデータ型（文字列、整数、ブール値など）。
    • description（文字列）: パラメータの目的と適切な形式についての明確な説明。

  • required（配列）: 関数の動作に必須のパラメータ名を列挙した文字列の配列。

curl コマンドを使用した関数宣言のコード例については、Gemini API を使用した関数呼び出しをご覧ください。Gemini API SDK を使用して関数宣言を作成する方法の例については、関数呼び出しのチュートリアルをご覧ください。

モデルは、単一のプロンプトから複数の関数呼び出しと、出力の連結に必要なコードを生成できます。このコードはサンドボックス環境で実行され、後続の BidiGenerateContentToolCall メッセージを生成します。各関数呼び出しの結果が表示されるまで実行は停止するため、順番どおりに処理が行われます。

クライアントは BidiGenerateContentToolResponse を返します。

詳細については、関数呼び出しの概要をご覧ください。

音声形式

Live API は、次の音声形式をサポートしています。

• 入力音声形式: RAW 16 ビット PCM 音声、16kHz、リトル エンディアン
• 出力音声形式: RAW 16 ビット PCM 音声、24kHz、リトル エンディアン

システム指示

システム指示を指定することで、モデルの出力をより適切に制御し、音声レスポンスのトーンや感情を指定できます。

システム指示は、インタラクションの開始前にプロンプトに追加され、セッション全体で有効になります。

システム指示を設定できるのは、セッションの開始時、初回接続の直後のみです。セッション中にモデルにさらに多くの情報を入力するには、コンテンツの増分更新を使用します。

中断

モデルの出力はいつでも中断できます。音声アクティビティ検出（VAD）が中断を検出すると、進行中の生成はキャンセルされ、破棄されます。クライアントにすでに送信された情報だけが、セッション履歴に保持されます。その後、サーバーは中断を報告する BidiGenerateContentServerContent メッセージを送信します。

さらに、Gemini サーバーは保留中の関数呼び出しを破棄し、キャンセルされた呼び出しの ID を記載した BidiGenerateContentServerContent メッセージを送信します。

音声

Live API は、次の音声をサポートしています。

• Puck
• Charon
• Kore
• Fenrir
• Aoede

音声を指定するには、セッション構成の一部として、speechConfig オブジェクト内に voiceName を設定します。

次の speechConfig オブジェクトの JSON 表現をご覧ください。

{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "VOICE_NAME"
    }
  }
}

制限事項

プロジェクトを計画する際は、Live API と Gemini 2.0 の次の制限事項を考慮してください。

クライアント認証

Live API が提供するのはサーバー間認証のみであるため、クライアントが直接使用することはおすすめしません。クライアントの入力を Live API で安全に認証するには、中間アプリケーション サーバーを経由する必要があります。

会話の履歴

モデルはセッション内のインタラクションを追跡しますが、会話履歴は保存されません。セッションが終了すると、対応するコンテキストは消去されます。

以前のセッションを復元したり、ユーザー インタラクションの過去のコンテキストをモデルに提供したりするには、アプリケーションが独自の会話ログを維持し、BidiGenerateContentClientContent メッセージを使用して新しいセッションの開始時にこの情報を送信する必要があります。

セッションの最大継続時間

セッション継続時間は、音声では最大 15 分、音声と動画では最大 2 分に制限されます。セッション継続時間が上限を超えると、接続が終了します。

モデルはコンテキストのサイズによっても制限されます。動画ストリームや音声ストリームとともに大量のコンテンツを送信すると、セッションが早期に終了する可能性があります。

音声アクティビティ検出（VAD）

デフォルトでは、モデルは連続した音声入力ストリームに対して音声アクティビティ検出（VAD）を自動的に実行します。VAD は、設定メッセージの RealtimeInputConfig.AutomaticActivityDetection フィールドで設定できます。

オーディオ ストリームが一秒以上一時停止すると（ユーザーがマイクをオフにしたときなど）、キャッシュに保存されているオーディオをフラッシュするために AudioStreamEnd イベントが送信されます。クライアントはいつでも音声データの送信を再開できます。

また、設定メッセージで RealtimeInputConfig.AutomaticActivityDetection.disabled を true に設定することで、自動 VAD をオフにすることもできます。この構成では、クライアントがユーザーの音声を検出し、適切なタイミングで ActivityStart メッセージと ActivityEnd メッセージを送信します。この構成では AudioStreamEnd は送信されません。代わりに、ストリームの中断は ActivityEnd メッセージでマークされます。

その他の制限

手動エンドポイントはサポートされていません。

音声入力と音声出力は、モデルが関数呼び出しを使用する機能に悪影響を及ぼします。

トークン数

トークン数はサポートされていません。

レート上限

次のレート制限が適用されます。

• API キーあたり 3 つの同時実行セッション
• 1 分あたり 400 万個のトークン

メッセージとイベント

次のステップ

• 関数呼び出しの詳細を確認する。
• 例については、関数呼び出しのリファレンスをご覧ください。