Gemini 2.5 Pro プレビュー版が本番環境で利用可能になりました。詳細

このページは Cloud Translation API によって翻訳されました。

Live API - WebSockets API reference

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

セッション

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

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

WebSocket 接続

セッションを開始するには、次の WebSocket エンドポイントに接続します。

wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent

セッションの構成

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

セッション中に、モデル以外の構成パラメータを変更できます。

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


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

API フィールドの詳細については、generationConfig をご覧ください。

メッセージを送信する

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)

サーバーメッセージには usageMetadata フィールドが含まれる場合がありますが、それ以外の場合は BidiGenerateContentServerMessage メッセージの他のフィールドが 1 つだけ含まれます。（messageType ユニオンは JSON で表現されていないため、フィールドはメッセージの最上位に表示されます）。

メッセージとイベント

ActivityEnd

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

ユーザーアクティビティの終了をマークします。

ActivityHandling

ユーザーアクティビティを処理するさまざまな方法。

列挙型
`ACTIVITY_HANDLING_UNSPECIFIED`	指定しない場合、デフォルトの動作は `START_OF_ACTIVITY_INTERRUPTS` です。
`START_OF_ACTIVITY_INTERRUPTS`	true の場合、アクティビティの開始時にモデルのレスポンスが中断されます（「割り込み」とも呼ばれます）。中断した時点で、モデルの現在のレスポンスはカットされます。これはデフォルトの動作です。
`NO_INTERRUPTION`	モデルのレスポンスが中断されることはありません。

ActivityStart

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

ユーザーアクティビティの開始をマークします。

AudioTranscriptionConfig

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

音声文字変換の設定。

AutomaticActivityDetection

アクティビティの自動検出を構成します。

フィールド
`disabled`	`bool` 省略可。有効になっている場合（デフォルト）、検出された音声入力とテキスト入力はアクティビティとしてカウントされます。無効になっている場合は、クライアントがアクティビティシグナルを送信する必要があります。
`startOfSpeechSensitivity`	`StartSensitivity` 省略可。音声が検出される確率を決定します。
`prefixPaddingMs`	`int32` 省略可。音声開始が commit される前に検出された音声に必要な時間。この値が低いほど、音声開始の検出の感度が高くなり、短い音声を認識できます。ただし、これにより誤検出の可能性も高くなります。
`endOfSpeechSensitivity`	`EndSensitivity` 省略可。検出された音声が終了する可能性を判断します。
`silenceDurationMs`	`int32` 省略可。音声の終了が確定する前に検出される非音声（無音など）に必要な時間。この値を大きくすると、ユーザーのアクティビティを中断することなく音声のギャップを長くできますが、モデルのレイテンシが増加します。

BidiGenerateContentClientContent

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

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

フィールド

フィールド
`turns[]`	`Content` 省略可。モデルとの現在の会話に追加されたコンテンツ。シングルターンクエリの場合、単一のインスタンスです。マルチターンクエリの場合、これは会話履歴と最新のリクエストを含む繰り返しフィールドです。
`turnComplete`	`bool` 省略可。true の場合、現在蓄積されているプロンプトからサーバーのコンテンツ生成が開始することを示します。true ではない場合、サーバーは、メッセージが追加されるのを待って生成を開始します。

turns[]

Content

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

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

turnComplete

bool

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

BidiGenerateContentRealtimeInput

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

さまざまなモダリティ（音声、動画、テキスト）は、同時実行ストリームとして処理されます。これらのストリーム間の順序は保証されません。

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

モデルの生成を中断せずに連続で送信できます。
BidiGenerateContentClientContent と BidiGenerateContentRealtimeInput にまたがってインターリーブされたデータを混在させる必要がある場合、サーバーは最良のレスポンスになるよう最適化を試みます（ただし、保証はありません）。
ターンの終了は明示的に指定されず、ユーザーアクティビティ（音声の終了など）から導き出されます。
ターンが終了する前でも、データは増分処理され、モデルからのレスポンスを迅速に開始できるように最適化されます。

フィールド
`mediaChunks[]`	`Blob` 省略可。メディア入力用のインラインバイトデータ。複数の `mediaChunks` はサポートされていません。最初の `mediaChunks` 以外は無視されます。非推奨: 代わりに `audio`、`video`、`text` のいずれかを使用してください。
`audio`	`Blob` 省略可。これらがリアルタイム音声入力ストリームを形成します。
`video`	`Blob` 省略可。これらがリアルタイム動画入力ストリームを形成します。
`activityStart`	`ActivityStart` 省略可。ユーザーアクティビティの開始をマークします。このデータは、自動（サーバーサイド）アクティビティ検出が無効になっている場合にのみ送信されます。
`activityEnd`	`ActivityEnd` 省略可。ユーザーアクティビティの終了をマークします。このデータは、自動（サーバーサイド）アクティビティ検出が無効になっている場合にのみ送信されます。
`audioStreamEnd`	`bool` 省略可。マイクがオフになったなど、オーディオストリームが終了したことを示します。これは、自動アクティビティ検出が有効になっている場合にのみ送信する必要があります（デフォルト）。クライアントは音声メッセージを送信してストリームを再開できます。
`text`	`string` 省略可。これらがリアルタイムテキスト入力ストリームを形成します。

BidiGenerateContentServerContent

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

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

フィールド
`generationComplete`	`bool` 出力専用。true の場合、モデルの生成が完了していることを示します。生成中にモデルが中断された場合、中断されたターンには「generation_complete」メッセージは表示されず、「interrupted > turn_complete」に進みます。モデルがリアルタイム再生を想定している場合、再生が完了するのを待機しているため、generation_complete と turn_complete の間に遅延が発生します。
`turnComplete`	`bool` 出力専用。true の場合、モデルがターンを完了したことを示します。生成は、追加のクライアントメッセージに応答してのみ開始されます。
`interrupted`	`bool` 出力専用。true の場合、クライアントメッセージが現在のモデル生成を中断したことを示します。クライアントがリアルタイムでコンテンツを再生している場合、現在の再生キューを停止して空にする良いタイミングになります。
`groundingMetadata`	`GroundingMetadata` 出力専用。生成されたコンテンツのグラウンディングメタデータ。
`outputTranscription`	`BidiGenerateContentTranscription` 出力専用。音声文字変換を出力します。文字起こしは他のサーバーメッセージとは別に送信され、順序は保証されません（特に `serverContent` とこの `outputTranscription` の間では保証されません）。
`modelTurn`	`Content` 出力専用。ユーザーとの現在の会話の一部としてモデルが生成したコンテンツ。

BidiGenerateContentServerMessage

BidiGenerateContent 呼び出しのレスポンスメッセージ。

フィールド
`usageMetadata`	`UsageMetadata` 出力専用。レスポンスに関する使用メタデータ。
共用体フィールド `messageType`。メッセージのタイプ。`messageType` は次のいずれかになります。
`setupComplete`	`BidiGenerateContentSetupComplete` 出力専用。セットアップが完了したときに、クライアントからの `BidiGenerateContentSetup` メッセージに応答して送信されます。
`serverContent`	`BidiGenerateContentServerContent` 出力専用。クライアントメッセージに応答してモデルが生成したコンテンツ。
`toolCall`	`BidiGenerateContentToolCall` 出力専用。クライアントに `functionCalls` を実行して、一致する `id` を含むレスポンスを返すよう求めるリクエスト。
`toolCallCancellation`	`BidiGenerateContentToolCallCancellation` 出力専用。指定の `id` を含む、以前発行された `ToolCallMessage` をキャンセルする必要があることをクライアントに伝える通知。
`goAway`	`GoAway` 出力専用。サーバーがまもなく切断されることを知らせる通知。
`sessionResumptionUpdate`	`SessionResumptionUpdate` 出力専用。セッション再開ステータスの更新。

BidiGenerateContentSetup

最初の（および最初のみ）BidiGenerateContentClientMessage で送信されるメッセージ。ストリーミング RPC の期間に適用される構成が含まれています。

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

フィールド
`model`	`string` 必須。モデルのリソース名。これは、モデルが使用する ID として機能します。形式: `models/{model}`
`generationConfig`	`GenerationConfig` 省略可。生成の構成。次のフィールドはサポートされていません。 `responseLogprobs` `responseMimeType` `logprobs` `responseSchema` `stopSequence` `routingConfig` `audioTimestamp`
`systemInstruction`	`Content` 省略可。ユーザーがモデルに提供するシステム指示。注: パートにはテキストのみを使用します。各パートのコンテンツは別の段落にします。
`tools[]`	`Tool` 省略可。モデルが次のレスポンスの生成に使用できる `Tools` のリスト。 `Tool` は、システムが外部システムと対話して、モデルの知識や範囲外のアクションまたは一連のアクションを実行できるようにするコードです。
`realtimeInputConfig`	`RealtimeInputConfig` 省略可。リアルタイム入力の処理を設定します。
`sessionResumption`	`SessionResumptionConfig` 省略可。セッション再開メカニズムを構成します。含まれている場合、サーバーは `SessionResumptionUpdate` メッセージを送信します。
`contextWindowCompression`	`ContextWindowCompressionConfig` 省略可。コンテキストウィンドウ圧縮メカニズムを構成します。指定されている長さを超えると、サーバーはコンテキストのサイズを自動的に縮小します。
`outputAudioTranscription`	`AudioTranscriptionConfig` 省略可。設定すると、モデルの音声出力の文字起こしが有効になります。音声文字変換は、出力音声に指定された言語コード（設定されている場合）と一致します。

BidiGenerateContentSetupComplete

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

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

BidiGenerateContentToolCall

クライアントに functionCalls を実行して、一致する id を含むレスポンスを返すよう求めるリクエスト。

フィールド

フィールド
`functionCalls[]`	`FunctionCall` 出力専用。実行される関数呼び出し。

functionCalls[]

FunctionCall

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

BidiGenerateContentToolCallCancellation

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

フィールド

フィールド
`ids[]`	`string` 出力専用。キャンセルするツール呼び出しの ID。

ids[]

string

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

BidiGenerateContentToolResponse

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

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

フィールド

フィールド
`functionResponses[]`	`FunctionResponse` 省略可。関数呼び出しに対するレスポンス。

functionResponses[]

FunctionResponse

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

BidiGenerateContentTranscription

音声の文字起こし（入力または出力）。

フィールド

フィールド
`text`	`string` 文字起こしテキスト。

text

string

文字起こしテキスト。

ContextWindowCompressionConfig

コンテキストウィンドウの圧縮を有効にします。これは、モデルのコンテキストウィンドウが指定された長さを超えないように管理するメカニズムです。

フィールド

フィールド
共用体フィールド `compressionMechanism`。使用されるコンテキストウィンドウ圧縮メカニズム。`compressionMechanism` は次のいずれかになります。
`slidingWindow`	`SlidingWindow` スライディングウィンドウメカニズム。
`triggerTokens`	`int64` コンテキストウィンドウの圧縮をトリガーするために必要なトークン数（ターンの実行前）。コンテキストウィンドウを短くするとモデルのレスポンスが速くなるため、品質とレイテンシのバランスを取るために使用できます。ただし、圧縮オペレーションを行うと一時的にレイテンシが増加するため、頻繁にトリガーしないでください。設定しない場合、デフォルトはモデルのコンテキストウィンドウの上限の 80% です。残りの 20% は、次のユーザーリクエストまたはモデルレスポンス用に使用されます。

共用体フィールド compressionMechanism。使用されるコンテキストウィンドウ圧縮メカニズム。compressionMechanism は次のいずれかになります。

slidingWindow

SlidingWindow

スライディングウィンドウメカニズム。

triggerTokens

int64

コンテキストウィンドウの圧縮をトリガーするために必要なトークン数（ターンの実行前）。

コンテキストウィンドウを短くするとモデルのレスポンスが速くなるため、品質とレイテンシのバランスを取るために使用できます。ただし、圧縮オペレーションを行うと一時的にレイテンシが増加するため、頻繁にトリガーしないでください。

設定しない場合、デフォルトはモデルのコンテキストウィンドウの上限の 80% です。残りの 20% は、次のユーザーリクエストまたはモデルレスポンス用に使用されます。

EndSensitivity

音声の終了を検出する方法。

列挙型
`END_SENSITIVITY_UNSPECIFIED`	デフォルトは END_SENSITIVITY_HIGH です。
`END_SENSITIVITY_HIGH`	自動検出で音声が終了する頻度が増える。
`END_SENSITIVITY_LOW`	自動検出による音声の終了が減ります。

GoAway

サーバーがまもなく切断されることを知らせる通知。

フィールド

フィールド
`timeLeft`	`Duration` 接続が ABORTED として終了するまでの残り時間。この期間は、モデル固有の最小値より短くなることはありません。この最小値は、モデルのレート制限とともに指定されます。

timeLeft

Duration

接続が ABORTED として終了するまでの残り時間。

この期間は、モデル固有の最小値より短くなることはありません。この最小値は、モデルのレート制限とともに指定されます。

RealtimeInputConfig

BidiGenerateContent でリアルタイム入力の動作を構成します。

フィールド

フィールド
`automaticActivityDetection`	`AutomaticActivityDetection` 省略可。設定しない場合、アクティビティの自動検出はデフォルトで有効になります。自動音声検出が無効になっている場合は、クライアントがアクティビティシグナルを送信する必要があります。
`activityHandling`	`ActivityHandling` 省略可。アクティビティの効果を定義します。
`turnCoverage`	`TurnCoverage` 省略可。ユーザーのターンに含まれる入力を定義します。

automaticActivityDetection

AutomaticActivityDetection

省略可。設定しない場合、アクティビティの自動検出はデフォルトで有効になります。自動音声検出が無効になっている場合は、クライアントがアクティビティシグナルを送信する必要があります。

activityHandling

ActivityHandling

省略可。アクティビティの効果を定義します。

turnCoverage

TurnCoverage

省略可。ユーザーのターンに含まれる入力を定義します。

SessionResumptionConfig

セッションの再開の構成。

このメッセージは、セッション構成に BidiGenerateContentSetup.sessionResumption として含まれます。構成されている場合、サーバーは SessionResumptionUpdate メッセージを送信します。

フィールド

フィールド
`handle`	`string` 前のセッションのハンドル。存在しない場合、新しいセッションが作成されます。セッションハンドルは、以前の接続の `SessionResumptionUpdate.token` 値から取得されます。

handle

string

前のセッションのハンドル。存在しない場合、新しいセッションが作成されます。

セッションハンドルは、以前の接続の SessionResumptionUpdate.token 値から取得されます。

SessionResumptionUpdate

セッション再開ステータスの更新。

BidiGenerateContentSetup.sessionResumption が設定されている場合にのみ送信されます。

フィールド

フィールド
`newHandle`	`string` 再開可能な状態を表す新しいハンドル。`resumable`=false の場合は空になります。
`resumable`	`bool` 現在のセッションをこの時点で再開できる場合は true です。セッションの特定の時点では再開できません。たとえば、モデルが関数呼び出しを実行しているときや生成しているときなどです。このような状態でセッションを再開すると（以前のセッショントークンを使用して）、データが一部失われます。この場合、`newHandle` は空で、`resumable` は false になります。

newHandle

string

再開可能な状態を表す新しいハンドル。resumable=false の場合は空になります。

resumable

bool

現在のセッションをこの時点で再開できる場合は true です。

セッションの特定の時点では再開できません。たとえば、モデルが関数呼び出しを実行しているときや生成しているときなどです。このような状態でセッションを再開すると（以前のセッショントークンを使用して）、データが一部失われます。この場合、newHandle は空で、resumable は false になります。

SlidingWindow

SlidingWindow メソッドは、コンテキストウィンドウの先頭にあるコンテンツを破棄して動作します。生成されたコンテキストは、常にユーザー役割のターンの開始から始まります。システム指示と BidiGenerateContentSetup.prefixTurns は常に結果の先頭に残ります。

フィールド

フィールド
`targetTokens`	`int64` 保持するトークンの目標数。デフォルト値は trigger_tokens/2 です。コンテキストウィンドウの一部を破棄すると、一時的にレイテンシが増加するため、この値は、頻繁な圧縮オペレーションを回避するように調整する必要があります。

targetTokens

int64

保持するトークンの目標数。デフォルト値は trigger_tokens/2 です。

コンテキストウィンドウの一部を破棄すると、一時的にレイテンシが増加するため、この値は、頻繁な圧縮オペレーションを回避するように調整する必要があります。

StartSensitivity

音声の開始を検出する方法を決定します。

列挙型
`START_SENSITIVITY_UNSPECIFIED`	デフォルトは START_SENSITIVITY_HIGH です。
`START_SENSITIVITY_HIGH`	自動検出により、音声の開始がより頻繁に検出されます。
`START_SENSITIVITY_LOW`	自動検出で音声の開始が検出される頻度が低下します。

TurnCoverage

ユーザーのターンに含まれる入力に関するオプション。

列挙型
`TURN_COVERAGE_UNSPECIFIED`	指定しない場合、デフォルトの動作は `TURN_INCLUDES_ONLY_ACTIVITY` です。
`TURN_INCLUDES_ONLY_ACTIVITY`	ユーザーのターンには、前回のターン以降のアクティビティのみが含まれ、無操作（音声ストリームの無音など）は含まれません。これはデフォルトの動作です。
`TURN_INCLUDES_ALL_INPUT`	ユーザーのターンには、前回のターンからのすべてのリアルタイム入力が含まれます（音声ストリームの無音など）。

UsageMetadata

レスポンスに関する使用メタデータ。

フィールド
`promptTokenCount`	`int32` 出力専用。プロンプト内のトークン数。`cachedContent` が設定されている場合でも、これは引き続き有効なプロンプトの合計サイズです。つまり、キャッシュに保存されているコンテンツのトークン数も含まれます。
`cachedContentTokenCount`	`int32` プロンプトのキャッシュに保存されている部分（キャッシュに保存されているコンテンツ）のトークン数
`responseTokenCount`	`int32` 出力専用。生成されたすべてのレスポンス候補のトークンの合計数。
`toolUsePromptTokenCount`	`int32` 出力専用。ツール使用プロンプト内にあるトークンの数。
`thoughtsTokenCount`	`int32` 出力専用。思考モデルの思考トークンの数。
`totalTokenCount`	`int32` 出力専用。生成リクエストのトークンの合計数（プロンプト + レスポンス候補）。
`promptTokensDetails[]`	`ModalityTokenCount` 出力専用。リクエスト入力で処理されたモダリティのリスト。
`cacheTokensDetails[]`	`ModalityTokenCount` 出力専用。リクエスト入力でキャッシュに保存されたコンテンツのモダリティのリスト。
`responseTokensDetails[]`	`ModalityTokenCount` 出力専用。レスポンスで返されたモダリティのリスト。
`toolUsePromptTokensDetails[]`	`ModalityTokenCount` 出力専用。ツール使用リクエスト入力で処理されたモダリティのリスト。

一般的なタイプの詳細

よく使用される API リソースタイプ（Blob、Content、FunctionCall、FunctionResponse、GenerationConfig、GroundingMetadata、ModalityTokenCount、Tool）について詳しくは、コンテンツの生成をご覧ください。

Live API - WebSockets API reference

セッション

WebSocket 接続

セッションの構成

メッセージを送信する

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

メッセージを受信する

メッセージとイベント

ActivityEnd

ActivityHandling

ActivityStart

AudioTranscriptionConfig

AutomaticActivityDetection

BidiGenerateContentClientContent

BidiGenerateContentRealtimeInput

BidiGenerateContentServerContent

BidiGenerateContentServerMessage

BidiGenerateContentSetup

BidiGenerateContentSetupComplete

BidiGenerateContentToolCall

BidiGenerateContentToolCallCancellation

BidiGenerateContentToolResponse

BidiGenerateContentTranscription

ContextWindowCompressionConfig

EndSensitivity

GoAway

RealtimeInputConfig

SessionResumptionConfig

SessionResumptionUpdate

SlidingWindow

StartSensitivity

TurnCoverage

UsageMetadata

一般的なタイプの詳細

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