Multimodal Live API

Multimodal Live API を使用すると、Gemini との低レイテンシの双方向音声と動画のやり取りが可能になります。Multimodal Live API を使用すると、エンドユーザーに自然で人間のような音声会話のエクスペリエンスを提供できます。また、音声コマンドを使用してモデルのレスポンスを中断することもできます。このモデルは、テキスト、音声、動画の入力を処理し、テキストと音声の出力を生成できます。

Multimodal Live API は Google AI Studio で試すことができます。

Multimodal Live API を使用する

このセクションでは、Google の SDK のいずれかで Multimodal Live API を使用する方法について説明します。基盤となる WebSockets API の詳細については、以下の WebSockets API リファレンスをご覧ください。

テキストの送受信

import asyncio
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model = "gemini-2.0-flash-exp"

config = {"response_modalities": ["TEXT"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        while True:
            message = input("User> ")
            if message.lower() == "exit":
                break
            await session.send(input=message, end_of_turn=True)

            async for response in session.receive():
                if response.text is not None:
                    print(response.text, end="")

if __name__ == "__main__":
    asyncio.run(main())

音声を受信する

次の例は、音声データを受信して .wav ファイルに書き込む方法を示しています。

import asyncio
import wave
from google import genai

client = genai.Client(api_key="GEMINI_API_KEY", http_options={'api_version': 'v1alpha'})
model = "gemini-2.0-flash-exp"

config = {"response_modalities": ["AUDIO"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        wf = wave.open("audio.wav", "wb")
        wf.setnchannels(1)
        wf.setsampwidth(2)
        wf.setframerate(24000)

        message = "Hello? Gemini are you there?"
        await session.send(input=message, end_of_turn=True)

        async for idx,response in async_enumerate(session.receive()):
            if response.data is not None:
                wf.writeframes(response.data)

            # Comment this out to print audio data info
            # if response.server_content.model_turn is not None:
            #      print(response.server_content.model_turn.parts[0].inline_data.mime_type)

        wf.close()

if __name__ == "__main__":
    asyncio.run(main())

オーディオ形式

Multimodal Live API は、次のオーディオ形式をサポートしています。

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

音声と動画をストリーミングする

システム指示

システム指示を使用すると、特定のニーズやユースケースに基づいてモデルの動作を制御できます。システム指示は設定構成で設定でき、セッション全体で有効になります。

from google.genai import types

config = {
    "system_instruction": types.Content(
        parts=[
            types.Part(
                text="You are a helpful assistant and answer in a friendly tone."
            )
        ]
    ),
    "response_modalities": ["TEXT"],
}

コンテンツの増分更新

増分更新を使用して、テキスト入力の送信、セッション コンテキストの確立、セッション コンテキストの復元を行います。短いコンテキストの場合は、ターンバイターン インタラクションを使用して、イベントの正確なシーケンスを表すことができます。

PythonJSON
from google.genai import types

turns = [
    types.Content(parts=[types.Part(text="What is the capital of France?")], role="user"),
    types.Content(parts=[types.Part(text="Paris")], role="model")
]
await session.send(input=types.LiveClientContent(turns=turns))

turns = [types.Content(parts=[types.Part(text="What is the capital of Germany?")], role="user")]
await session.send(input=types.LiveClientContent(turns=turns, turn_complete=True))
{
  "clientContent": {
    "turns": [
      {
        "parts":[
          {
            "text": ""
          }
        ],
        "role":"user"
      },
      {
        "parts":[
          {
            "text": ""
          }
        ],
        "role":"model"
      }
    ],
    "turnComplete": true
  }
}

コンテキストが長い場合は、1 つのメッセージの概要を提供して、後続のインタラクション用にコンテキスト ウィンドウを空けておくことをおすすめします。

音声を変更する

Multimodal Live API は、Aoede、Charon、Fenrir、Kore、Puck の音声をサポートしています。

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

PythonJSON
from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    speech_config=types.SpeechConfig(
        voice_config=types.VoiceConfig(
            prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Kore")
        )
    )
)
{
  "voiceConfig": {
    "prebuiltVoiceConfig": {
      "voiceName": "Kore"
    }
  }
}

関数呼び出しを使用する

ツールは Multimodal Live API で定義できます。関数呼び出しの詳細については、関数呼び出しチュートリアルをご覧ください。

ツールは、セッション構成の一部として定義する必要があります。

config = types.LiveConnectConfig(
    response_modalities=["TEXT"],
    tools=[set_light_values]
)

async with client.aio.live.connect(model=model, config=config) as session:
    await session.send(input="Turn the lights down to a romantic level", end_of_turn=True)

    async for response in session.receive():
        print(response.tool_call)

モデルは、単一のプロンプトから複数の関数呼び出しと、出力の連結に必要なコードを生成できます。このコードはサンドボックス環境で実行され、その後の BidiGenerateContentToolCall メッセージを生成します。各関数呼び出しの結果が利用可能になるまで実行が停止し、順序処理が保証されます。

クライアントは BidiGenerateContentToolResponse を返す必要があります。

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

中断を処理する

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

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

async for response in session.receive():
    if response.server_content.interrupted is not None:
        # The generation was interrupted

制限事項

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

クライアント認証

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

会話の履歴

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

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

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

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

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

音声アクティビティ検出(VAD)

モデルは、連続した音声入力ストリームに対して、音声アクティビティ検出(VAD)を自動的に実行します。VAD は常に有効になっており、パラメータを構成することはできません。

トークン数

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

レート上限

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

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

WebSockets API リファレンス

Multimodal Live API は、WebSockets を使用するステートフル API です。このセクションでは、WebSockets API に関する詳細について説明します。

セッション

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

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

接続後の最初のメッセージで、モデル、生成パラメータ、システム インストラクション、ツールを含むセッション構成が設定されます。

次の構成例をご覧ください。SDK の名前のケースは異なる場合があります。Python SDK の構成オプションを確認できます。


{
 
"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]
}

メッセージを送信する

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


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

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

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

メッセージ 説明
BidiGenerateContentSetup 最初のメッセージで送信されるセッション構成
BidiGenerateContentClientContent クライアントから送信された現在の会話コンテンツの増分更新
BidiGenerateContentRealtimeInput リアルタイムの音声または動画入力
BidiGenerateContentToolResponse サーバーから受信した ToolCallMessage へのレスポンス

メッセージを受信する

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

以下をご覧ください。

async with client.aio.live.connect(model='...', config=config) as session:
    await session.send(input='Hello world!', end_of_turn=True)
    async for message in session.receive():
        print(message)

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


{
 
"setupComplete": BidiGenerateContentSetupComplete,
 
"serverContent": BidiGenerateContentServerContent,
 
"toolCall": BidiGenerateContentToolCall,
 
"toolCallCancellation": BidiGenerateContentToolCallCancellation
}

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

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

メッセージ 説明
BidiGenerateContentSetupComplete セットアップが完了したときに、クライアントから送信される BidiGenerateContentSetup メッセージ
BidiGenerateContentServerContent クライアント メッセージに応答してモデルが生成したコンテンツ
BidiGenerateContentToolCall クライアントに関数呼び出しを実行して、一致する ID を含むレスポンスを返すよう求めるリクエスト
BidiGenerateContentToolCallCancellation ユーザーがモデル出力を中断したために関数呼び出しがキャンセルされたときに送信されます

メッセージとイベント

BidiGenerateContentClientContent

クライアントから送信された現在の会話の増分更新。ここでのコンテンツはすべて無条件で会話履歴に追加され、コンテンツを生成するモデルへのプロンプトの一部として使用されます。

次のメッセージが表示されると、現在のモデルの生成が中断されます。

フィールド
turns[]

Content

省略可。モデルとの現在の会話に追加されたコンテンツ。

シングルターン クエリの場合、単一のインスタンスです。マルチターン クエリの場合、これは会話履歴と最新のリクエストを含む繰り返しフィールドです。

turn_complete

bool

省略可。true の場合、現在蓄積されているプロンプトからサーバーのコンテンツ生成が開始することを示します。true ではない場合、サーバーは、メッセージが追加されるのを待って生成を開始します。

BidiGenerateContentRealtimeInput

リアルタイムで送信されるユーザー入力。

BidiGenerateContentClientContent とはいくつかの点で異なります。

  • モデルの生成を中断せずに連続で送信できます。
  • BidiGenerateContentClientContentBidiGenerateContentRealtimeInput にまたがってインターリーブされたデータを混在させる必要がある場合、サーバーは最適なレスポンスを得るために最適化を試みますが、保証はされません。
  • ターンの終了は明示的に指定されず、ユーザー アクティビティ(音声の終了など)から導き出されます。
  • ターンが終了する前でも、データは増分処理され、モデルからのレスポンスを迅速に開始できるように最適化されます。
  • 常にユーザーの入力と見なされます(会話履歴の入力には使用できません)。中断することなく継続的に送信できます。このモデルは、ユーザーの音声の開始と終了を自動的に検出し、それに応じてレスポンスをストリーミングする開始または終了を行います。データは受信時に増分処理されるため、レイテンシが最小限に抑えられます。
フィールド
media_chunks[]

Blob

省略可。メディア入力用のインライン バイトデータ。

BidiGenerateContentServerContent

クライアント メッセージに応答してモデルが生成するサーバーの増分更新。

コンテンツはリアルタイムではなく、できるだけ早く生成されます。クライアントは、バッファリングしてリアルタイムで再生することもできます。

フィールド
turn_complete

bool

出力専用。true の場合、モデルの生成が完了していることを示します。生成は、追加のクライアント メッセージに応答してのみ開始されます。content を指定して設定すると、その content がターンの最後であることを示すことができます。

interrupted

bool

出力専用。true の場合、クライアント メッセージが現在のモデル生成を中断したことを示します。クライアントがコンテンツをリアルタイムで再生している場合は、現在の再生キューを停止して空にするのが適切なタイミングです。

grounding_metadata

GroundingMetadata

出力専用。生成されたコンテンツのグラウンディング メタデータ。

model_turn

Content

出力専用。ユーザーとの現在の会話の一部としてモデルが生成したコンテンツ。

BidiGenerateContentSetup

最初のクライアント メッセージでのみ送信されるメッセージ。ストリーミング セッションの期間に適用される構成が含まれています。

クライアントは、BidiGenerateContentSetupComplete メッセージを待って、追加メッセージを送信する必要があります。

フィールド
model

string

必須。モデルのリソース名。これは、モデルが使用する ID として機能します。

形式: models/{model}

generation_config

GenerationConfig

省略可。生成の構成。

次のフィールドはサポートされていません。

  • responseLogprobs
  • responseMimeType
  • logprobs
  • responseSchema
  • stopSequence
  • routingConfig
  • audioTimestamp
system_instruction

Content

省略可。ユーザーがモデルに提供するシステム指示。

注: パートにはテキストのみ使用してください。各パートのコンテンツは別の段落にします。

tools[]

Tool

省略可。モデルが次のレスポンスの生成に使用できる Tools のリスト。

Tool は、システムが外部システムと対話して、モデルの知識や範囲外のアクションまたは一連のアクションを実行できるようにするコードです。

BidiGenerateContentSetupComplete

この型にはフィールドがありません。

クライアントからの BidiGenerateContentSetup メッセージに応答して送信されます。

BidiGenerateContentToolCall

クライアントに、関数呼び出しを実行して、一致する id を含むレスポンスを返すようリクエストします。

フィールド
function_calls[]

FunctionCall

出力専用。実行される関数呼び出し。

BidiGenerateContentToolCallCancellation

指定された id を使用して以前に発行された ToolCallMessage は実行されず、キャンセルされる必要があることをクライアントに通知します。これらのツール呼び出しに副作用があった場合、クライアントはツール呼び出しを取り消すことができます。このメッセージは、クライアントがサーバーのターンを中断した場合にのみ表示されます。

フィールド
ids[]

string

出力専用。キャンセルするツール呼び出しの ID。

BidiGenerateContentToolResponse

サーバーから受信した ToolCall に対してクライアントが生成するレスポンス。個々の FunctionResponse オブジェクトは、id フィールドでそれぞれの FunctionCall オブジェクトと照合されます。

単項およびとサーバー ストリーミングの GenerateContent API では、Content パートを交換することで関数呼び出しが実行されますが、双方向の GenerateContent API では、専用のメッセージセットを介して関数呼び出しが実行されます。

フィールド
function_responses[]

FunctionResponse

省略可。関数呼び出しに対するレスポンス。

一般的なタイプの詳細

よく使用される API リソース タイプ BlobContentFunctionCallFunctionResponseGenerationConfigGroundingMetadataTool について詳しくは、コンテンツの生成をご覧ください。

サードパーティとの連携

ウェブアプリとモバイルアプリのデプロイでは、次のオプションを検討できます。