gemini-live-api-dev

Gemini Live API 開発スキル

概要

Live API を使用すると、WebSocket 経由で Gemini と低遅延のリアルタイム音声・動画インタラクションを実現できます。音声、動画、テキストの連続ストリームを処理し、人間のような自然な音声応答とバックグラウンドでの推論を即座に提供します。

主な機能：

• 双方向音声ストリーミング — マイクからスピーカーへのリアルタイム会話
• バックグラウンドでの推論（拡張思考） — 会話中のつなぎ言葉を音声で返しながら、複数ステップの推論をバックグラウンドで実行
• ライブストリーミング文字起こし — 中間結果と確定結果をリアルタイムで取得する音声テキスト変換
• 動画ストリーミング — 音声とともにカメラや画面のフレームを送信
• テキストの入力／出力 — ライブセッション内でテキストを送受信
• 音声の文字起こし — 入力音声と出力音声の両方のテキスト文字起こしを取得
• 音声アクティビティ検出（VAD） — 自動サーバー VAD、クライアント側のハイブリッド VAD、手動のプッシュ・トゥ・トーク
• 非同期関数呼び出し — 音声のストリーミングを続けながら、ブロックせずにツールを実行
• セッション全体へのクライアントコンテンツの適用 — ストリーミング中に会話ターンを挿入・更新
• セッション管理 — コンテキスト圧縮、セッション再開、GoAway シグナル
• エフェメラルトークン — セキュアなクライアント側認証

メモ

Live API はWebSocket経由で直接接続します。WebRTC のサポートや、より簡単な統合には、パートナー統合を使用してください。

モデル

現行モデル（こちらを使用）

• gemini-3.8-live — 低遅延の音声エージェント体験や、推論による遅延のないリアルタイム対話に最適なデフォルトモデルです。インターリーブされた推論、デフォルトでの非同期関数呼び出し（behavior: NON_BLOCKING）、セッション全体へのクライアントコンテンツの更新をサポートします。
• gemini-3.8-live-extended-thinking — ライブインタラクション中に、より高度なバックグラウンド推論が必要な場合に推奨される、高推論能力の音声間モデルです。会話中のつなぎ言葉を音声で継続的に返しながら、バックグラウンドでの推論と非同期ツール呼び出し（behavior: NON_BLOCKING が必要）を処理します。ライフサイクルは interaction_status（IN_PROGRESS と IDLE）で管理されます。
• gemini-3.5-transcribe-live — 中間仮説、確定した文字起こし、スマートな書式設定、ハイブリッド VAD に対応した、リアルタイムのストリーミング音声テキスト変換です。
• gemini-3.5-live-translate-preview — 70 以上の言語に対応した、リアルタイムの音声間ストリーミング翻訳です。

警告

レガシーモデル（gemini-3.1-flash-live-preview、gemini-2.5-flash-native-audio-*、gemini-live-2.5-flash-preview、gemini-2.0-flash-live-001）：破壊的なプロトコル変更（behavior: "NON_BLOCKING"、thinking_level、interaction_status、send_client_content）については、references/migration.mdをお読みください。

SDK

• Python：google-genai >= 2.3.0 — pip install -U google-genai
• JavaScript/TypeScript：@google/genai >= 2.3.0 — npm install @google/genai

警告

レガシー SDK の google-generativeai（Python）と @google/generative-ai（JS）は非推奨です。使用しないでください。

パートナー連携

リアルタイムの音声・動画アプリの開発を効率化するには、WebRTC または WebSockets を介した Gemini Live API に対応するサードパーティ連携を使用してください。

• LiveKit — LiveKit Agents で Gemini Live API を使用します。
• Pipecat by Daily — Gemini Live と Pipecat を使用して、リアルタイム AI チャットボットを作成します。
• Fishjam by Software Mansion — Fishjam を使用して、ライブ動画・音声ストリーミングアプリケーションを作成します。
• Vision Agents by Stream — Vision Agents を使用して、リアルタイムの音声・動画 AI アプリケーションを構築します。
• Voximplant — Voximplant を使用して、着信と発信を Live API に接続します。
• Firebase AI SDK — Firebase AI Logic を使用して Gemini Live API を始めましょう。

音声フォーマット

• 入力：RAW PCM、リトルエンディアン、16 ビット、モノラル。ネイティブは 16kHz（ほかのサンプリングレートはリサンプリングされます）。MIME タイプ：audio/pcm;rate=16000
• 出力：RAW PCM、リトルエンディアン、16 ビット、モノラル。サンプリングレートは 24kHz です。

重要

リアルタイムストリーミングのユーザー入力（音声、動画、テキスト）には、すべて send_realtime_input / sendRealtimeInput を使用してください。Gemini 3.8 モデルでは、明示的なロール（user または model）を指定して会話のコンテキストを挿入するために、セッションのライフサイクル全体で send_client_content / sendClientContent がサポートされています（turn_complete=true は常に実行中の生成を中断します）。

警告

sendRealtimeInput では media を使用しないでください。専用のキーを使用してください。音声データには audio、画像や動画のフレームには video、テキスト入力には text を指定します。

---

クイックスタート

認証

Python

from google import genai

client = genai.Client(api_key="YOUR_API_KEY")

JavaScript

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

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

Live API への接続

Python

from google.genai import types

config = types.LiveConnectConfig(
    response_modalities=[types.Modality.AUDIO],
    system_instruction=types.Content(
        parts=[types.Part(text="You are a helpful assistant.")]
    )
)

async with client.aio.live.connect(model="gemini-3.8-live", config=config) as session:
    pass  # Session is active

JavaScript

const session = await ai.live.connect({
  model: 'gemini-3.8-live',
  config: {
    responseModalities: ['audio'],
    systemInstruction: { parts: [{ text: 'You are a helpful assistant.' }] }
  },
  callbacks: {
    onopen: () => console.log('Connected'),
    onmessage: (response) => console.log('Message:', response),
    onerror: (error) => console.error('Error:', error),
    onclose: () => console.log('Closed')
  }
});

テキストの送信

Python

await session.send_realtime_input(text="Hello, how are you?")

JavaScript

session.sendRealtimeInput({ text: 'Hello, how are you?' });

音声の送信

Python

await session.send_realtime_input(
    audio=types.Blob(data=chunk, mime_type="audio/pcm;rate=16000")
)

JavaScript

session.sendRealtimeInput({
  audio: { data: chunk.toString('base64'), mimeType: 'audio/pcm;rate=16000' }
});

動画の送信

Python

# frame: raw JPEG-encoded bytes
await session.send_realtime_input(
    video=types.Blob(data=frame, mime_type="image/jpeg")
)

JavaScript

session.sendRealtimeInput({
  video: { data: frame.toString('base64'), mimeType: 'image/jpeg' }
});

音声とテキストの受信

重要

1 つのサーバーイベントに、複数のコンテンツパートが同時に含まれることがあります（例：音声チャンクと文字起こし）。コンテンツを見落とさないよう、各イベントのすべてのパートを必ず処理してください。

Python

async for response in session.receive():
    content = response.server_content
    if content:
        # Audio — process ALL parts in each event
        if content.model_turn:
            for part in content.model_turn.parts:
                if part.inline_data:
                    audio_data = part.inline_data.data
        # Transcription
        if content.input_transcription:
            print(f"User: {content.input_transcription.text}")
        if content.output_transcription:
            print(f"Gemini: {content.output_transcription.text}")
        # Interruption
        if content.interrupted is True:
            pass  # Stop playback, clear audio queue

JavaScript

// Inside the onmessage callback
const content = response.serverContent;
if (content?.modelTurn?.parts) {
  for (const part of content.modelTurn.parts) {
    if (part.inlineData) {
      const audioData = part.inlineData.data; // Base64 encoded
    }
  }
}
if (content?.inputTranscription) console.log('User:', content.inputTranscription.text);
if (content?.outputTranscription) console.log('Gemini:', content.outputTranscription.text);
if (content?.interrupted) { /* Stop playback, clear audio queue */ }

---

バックグラウンド推論（拡張思考）

音声エージェントで複雑なデータの評価、複数ステップの計画、または長時間実行されるツールの処理が必要な場合は、gemini-3.8-live-extended-thinking を使用してください。このモデルは、非同期ツールをバックグラウンドで実行しながら、自然な会話のつなぎ言葉（例：「フライトの選択肢を確認しています……」）を話します。

主な要件：

• 思考の設定：thinking_config=types.ThinkingConfig(thinking_level="low")（"minimal" | "low" | "medium" | "high"）を設定します。
• ノンブロッキングツール：すべての関数宣言で、必ず behavior="NON_BLOCKING" を設定してください。同期ブロッキングモードはサポートされておらず、エラーが返されます。
• ライフサイクルの追跡（interaction_status）：ターンの完了を検出する際に、turn_complete=True だけに依存しないでください。message.interaction_status（Python）/ message.interactionStatus（JS）を監視します。
  • "IN_PROGRESS"：サーバーが推論中、会話のつなぎ言葉を話している、または非同期ツールの応答を待機しています。
  • "IDLE"：サーバーがすべてのバックグラウンド推論とツール呼び出しを完了し、セッションがユーザー入力を受け付ける状態です。

Python と JavaScript の完全な実装例については、references/migration.md と Live API の思考ガイドを参照してください。

---

ライブ翻訳（Gemini Live Translate）

Live API は、70 以上の言語間で音声をリアルタイムかつ低レイテンシでストリーミング翻訳できます。オプションと機能の詳細については、ライブ翻訳ガイドをご覧ください。

モデル

• gemini-3.5-live-translate-preview — Live Translate のすべてのユースケースで推奨される翻訳モデルです。

設定（TranslationConfig）

翻訳を有効にするには、ライブセッションの設定内で TranslationConfig オブジェクトを指定します。

• Python SDK：LiveConnectConfig の translation_config を使って接続を設定します。

  config = types.LiveConnectConfig(
      response_modalities=[types.Modality.AUDIO],
      translation_config=types.TranslationConfig(
          target_language_code="es",  # Target language code (e.g. es, fr, pl)
          echo_target_language=True,
      ),
      input_audio_transcription=types.AudioTranscriptionConfig(),
      output_audio_transcription=types.AudioTranscriptionConfig(),
  )
  

• Raw WebSockets：generationConfig 内に translationConfig を配置します。

  {
    "setup": {
      "model": "models/gemini-3.5-live-translate-preview",
      "generationConfig": {
        "responseModalities": ["AUDIO"],
        "translationConfig": {
          "targetLanguageCode": "es",
          "echoTargetLanguage": true
        }
      }
    }
  }
  

---

ライブストリーミング文字起こし（Gemini Live Transcribe）

Live API は、低レイテンシの中間候補、確定した文字起こし、Hybrid VAD を備えた、WebSockets 経由のリアルタイム音声テキスト変換をサポートしています。詳細については、ライブ文字起こしガイドとColab クックブックをご覧ください。

モデル

• gemini-3.5-transcribe-live

モード

• smart：フィラー語を整理し、文中の自己訂正を解決し、書式を整えます。
• verbatim（デフォルト）：一語一句そのままの文字起こしです。

Python

config = types.LiveConnectConfig(
    response_modalities=["TEXT"],
    input_audio_transcription=types.AudioTranscriptionConfig(),
)

async with client.aio.live.connect(model="gemini-3.5-transcribe-live", config=config) as session:
    # Stream audio
    await session.send_realtime_input(audio=types.Blob(data=chunk, mime_type="audio/pcm;rate=16000"))
    # Hybrid VAD: notify turn end on client-detected silence for zero latency
    await session.send_realtime_input(audio_stream_end=True)

JavaScript

const session = await ai.live.connect({
  model: 'gemini-3.5-transcribe-live',
  config: {
    responseModalities: ['text'],
    inputAudioTranscription: { mode: 'smart' }
  },
  callbacks: {
    onmessage: (msg) => {
      if (msg.serverContent?.interimInputTranscription) {
        console.log('Interim:', msg.serverContent.interimInputTranscription.text);
      }
      if (msg.serverContent?.inputTranscription) {
        console.log('Final:', msg.serverContent.inputTranscription.text);
      }
    }
  }
});

session.sendRealtimeInput({ audio: { data: chunkBase64, mimeType: 'audio/pcm;rate=16000' } });
session.sendRealtimeInput({ audioStreamEnd: true }); // Hybrid VAD

Raw WebSockets

{
  "setup": {
    "model": "models/gemini-3.5-transcribe-live",
    "generationConfig": {
      "responseModalities": ["TEXT"],
      "speechConfig": {
        "voiceConfig": {}
      }
    },
    "inputAudioTranscription": {
      "mode": "smart"
    }
  }
}

---

制限事項

• レスポンスのモダリティ — 1 セッションにつき TEXT または AUDIO のみで、両方は指定できません。ネイティブ音声モデルは音声を出力します（response_modalities=["AUDIO"]）。テキストの文字起こしが必要な場合は、output_audio_transcription を有効にしてください。
• 音声のみのセッション — 圧縮なしで 15 分
• 音声＋動画のセッション — 圧縮なしで 2 分
• 接続の継続時間 — 約 10 分（セッション再開を使用してください）
• コンテキストウィンドウ — 入力トークン 128k／出力トークン 64k
• コード実行／URL コンテキスト — サポートされていません

アップグレードと移行

gemini-3.1-flash-live-preview、gemini-2.5-flash-native-audio-*、または gemini-2.0-flash-live-001 から Gemini 3.8 Live または Gemini 3.8 Live Extended Thinking にアップグレードする際の、手順ごとの移行チェックリストとプロトコルの変更点については、references/migration.mdをご覧ください。

ベストプラクティス

1. マイク音声をテストするときは、エコーや音声の自己中断を防ぐためにヘッドフォンを使用してください。
2. 15 分を超えるセッションでは、コンテキストウィンドウの圧縮を有効にしてください。
3. 接続のリセットを適切に処理できるよう、セッション再開を実装してください。
4. クライアント側にデプロイする場合は、エフェメラルトークンを使用してください。ブラウザーで API キーを公開しないでください。
5. リアルタイムのユーザー入力（音声、動画、テキスト）には send_realtime_input を使用してください。ストリームの途中にコンテキストターンを挿入する場合は、明示的に user／model ロールを指定して send_client_content を使用してください。
6. マイクが一時停止されたとき、またはユーザーが話し終えたときは、audioStreamEnd／audio_stream_end を送信してください（Hybrid VAD）。
7. 中断シグナル（interrupted: true）を受信したら、音声再生キューをクリアしてください。
8. 各サーバーイベント内のすべてのパートを処理してください。イベントには複数のコンテンツパートが含まれる場合があります。
9. gemini-3.8-live-extended-thinking を使用する際は、turn_complete だけに頼らず、interaction_status（IN_PROGRESS と IDLE）を監視してください。

ドキュメントの検索

MCP がインストールされている場合（推奨）

search_docs ツール（Google MCP サーバーのもの）が利用できる場合は、ドキュメントソースとしてこれだけを使用してください。

1. クエリを指定して search_docs を呼び出します。
2. 返されたドキュメントを読みます。
3. API の詳細については、MCP の結果を信頼できる情報源として使用してください。常に最新の情報が得られます。

重要

MCP ツールが利用できる場合、URL を手動で取得しないでください。MCP は、URL の取得よりも正確でトークン効率に優れた、最新のインデックス済みドキュメントを提供します。

MCP がインストールされていない場合（フォールバックのみ）

MCP のドキュメントツールが利用できない場合は、公式ドキュメントのインデックスを取得してください。

llms.txt URL：https://ai.google.dev/gemini-api/docs/llms.txt

このインデックスには、.md.txt 形式のすべてのドキュメントページへのリンクが含まれています。Web 取得ツールを使用して、次の操作を行ってください。

1. llms.txt を取得し、利用可能なドキュメントページを確認します
2. 特定のページを取得します（例：https://ai.google.dev/gemini-api/docs/live-session.md.txt）

主なドキュメントページ

重要

ドキュメントページはこれだけではありません。llms.txt インデックスを使用して、利用可能なドキュメントページを確認してください。

• Live API の概要 — はじめに、WebSocket の直接利用
• Live API の思考 — バックグラウンド推論、会話中のつなぎ言葉、interaction_status、ノンブロッキングツール
• モデルカード：Gemini 3.8 Live — デフォルトの低レイテンシ音声エージェントモデルと移行ガイド
• モデルカード：Gemini 3.8 Live Extended Thinking — 高度な推論に対応した音声モデルとアップグレードガイド
• Live の文字起こし — リアルタイム音声認識、中間仮説、スマートフォーマット、Hybrid VAD
• Live の翻訳 — 翻訳の設定オプションと機能
• Live API 機能ガイド — 音声設定、文字起こし設定、VAD 設定、メディア解像度
• Live API のツール利用 — 関数呼び出し（同期および非同期）、Google Search によるグラウンディング
• セッション管理 — コンテキストウィンドウの圧縮、セッションの再開、GoAway シグナル
• エフェメラルトークン — ブラウザー／モバイル向けの安全なクライアント側認証
• WebSockets API リファレンス — WebSocket プロトコルの詳細
• 移行とアップグレードのガイド — Gemini 3.8 Live および Extended Thinking 向けの手順別チェックリストとコード例

対応言語

Live API は、英語、スペイン語、フランス語、ドイツ語、イタリア語、ポルトガル語、中国語、日本語、韓国語、ヒンディー語、アラビア語、ロシア語など、70 言語に対応しています。ネイティブ音声モデルは言語を自動的に検出し、切り替えます。