Gemini 中文指南
获取 API 密钥 ↗

Live API 功能指南

↓ 下载 MarkdownInteractions API

这是一份全面的指南,涵盖了 Live API 可用的功能和配置。看 开始使用 Live API 页面,了解常见用例的概述和示例代码。

开始之前 #

  • 熟悉核心概念: 如果您还没有这样做,请阅读 开始使用 Live API 第一页。这将向您介绍 Live API 的基本原理、它的工作原理以及不同的 实施方法.
  • 在 AI Studio 中尝试 Live API: 您可能会发现尝试多式联运 Live API 很有用 Google AI Studio 在开始构建之前。要在 Google AI Studio 中使用 Live API,请选择 溪流.

型号对比 #

下表总结了之间的主要区别 Gemini 3.8 Live, Gemini 3.8 Live Extended Thinking, Gemini 3.1 Flash Live Preview, 和 Gemini 2.5 Flash Live Preview:

特点

Gemini 3.8 Live

Gemini 3.8 Live Extended Thinking

Gemini 3.1 Flash Live Preview

Gemini 2.5 Flash Live Preview

思考

支持(交错推理)。 thinkingLevel 不支持;从设置中省略。

支持(可配置后台推理: low, medium, high; minimal 不支持)。支持思想总结(includeThoughts).

用途 thinkingLevel (minimal, low, medium, high)。默认为 minimal 以优化最低延迟。

用途 thinkingBudget 设定思维token预算。

收到回复

单个服务器事件可以同时包含多个内容部分(例如, inlineData 和成绩单)。确保您的代码处理每个事件中的所有部分,以避免丢失内容。

单个服务器事件可以同时包含多个内容部分。当异步推理处于活动状态时, turnComplete: true 不指示空闲会话;检查 interaction_status (IN_PROGRESS 与 IDLE).

单个服务器事件可以同时包含多个内容部分(例如, inlineData 和成绩单)。确保您的代码处理每个事件中的所有部分,以避免丢失内容。

每个服务器事件仅包含一个内容部分。零件在单独的事件中交付。

客户内容

send_client_content 通过明确的角色在整个会话生命周期中得到支持(user 或 model). turn_complete=true 无条件中断生成。

send_client_content 通过明确的角色在整个会话生命周期中得到支持(user 或 model). turn_complete=true 无条件中断生成。

send_client_content 通过明确的角色在整个会话生命周期中得到支持(user 或 model). turn_complete=true 无条件中断生成。

send_client_content 在整个对话过程中支持发送增量内容更新和建立上下文。

转弯覆盖范围

默认为 TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO。模型的回合包括检测到的音频活动和所有视频帧。

默认为 TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO。模型的回合包括检测到的音频活动和所有视频帧。

默认为 TURN_INCLUDES_AUDIO_ACTIVITY_AND_ALL_VIDEO。模型的回合包括检测到的音频活动和所有视频帧。

默认为 TURN_INCLUDES_ONLY_ACTIVITY。模型的轮次仅包括检测到的活动。

定制VAD (activity_start/activity_end)

支持。禁用自动 VAD 和发送 activityStart 和 activityEnd 手动发送消息来控制转弯边界。

支持。禁用自动 VAD 和发送 activityStart 和 activityEnd 手动发送消息来控制转弯边界。

支持。禁用自动 VAD 和发送 activityStart 和 activityEnd 手动发送消息来控制转弯边界。

支持。禁用自动 VAD 和发送 activityStart 和 activityEnd 手动发送消息来控制转弯边界。

自动VAD配置

支持。配置参数如 start_of_speech_sensitivity, end_of_speech_sensitivity, prefix_padding_ms, 和 silence_duration_ms.

支持。配置参数如 start_of_speech_sensitivity, end_of_speech_sensitivity, prefix_padding_ms, 和 silence_duration_ms.

支持。配置参数如 start_of_speech_sensitivity, end_of_speech_sensitivity, prefix_padding_ms, 和 silence_duration_ms.

支持。配置参数如 start_of_speech_sensitivity, end_of_speech_sensitivity, prefix_padding_ms, 和 silence_duration_ms.

异步函数调用 (behavior: NON_BLOCKING)

支持(默认)。套装 behavior: NON_BLOCKING 或使用向后兼容的阻塞模式(behavior: BLOCKING)。函数调度(SILENT, WHEN_IDLE, INTERRUPTED)支持。

支持(仅限异步)。仅 NON_BLOCKING 支持执行。不支持阻塞模式和函数调度。

不支持。 函数调用仅是同步的。模型在响应之前等待工具响应。

支持(同步和异步)。

主动音频

永久启用(proactive_audio: false 返回错误)。

永久启用(proactive_audio: false 返回错误)。

不支持

支持(可配置)。套装 proactive_audio 到 true 在 proactivity 配置。

情感对话

不支持(已删除;省略 enable_affective_dialog).

不支持(已删除;省略 enable_affective_dialog).

不支持

支持。套装 enable_affective_dialog 到 true 在会话配置中。

要从 Gemini 3.1 Flash Live Preview 迁移到 Gemini 3.8 Live,请参阅 迁移指南。要了解有关思考的更多信息,请参阅 Live API 中的思考能力 和 升级到Gemini 3.8 Live Extended Thinking.

建立连接 #

以下示例显示如何创建与 API 密钥的连接:

python
import asyncio
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

model = "gemini-3.8-live"
config = {"response_modalities": ["AUDIO"]}

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        print("Session started")
        # Send content...

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

互动方式 #

以下部分提供了 Live API 中可用的不同输入和输出模式的示例和支持上下文。

发送音频 #

音频需要作为原始 PCM 数据发送(原始 16 位 PCM 音频,16kHz,小端)。

python
# Assuming 'chunk' is your raw PCM audio bytes
await session.send_realtime_input(
    audio=types.Blob(
        data=chunk,
        mime_type="audio/pcm;rate=16000"
    )
)

音频格式 #

多模态 Live API 中的音频数据始终是原始、小端、16 位 PCM。音频输出始终使用 24kHz 的采样率。输入音频本身为 16kHz,但多模态 Live API 将在需要时重新采样,以便可以发送任何采样率。要传达输入音频的采样率,请设置每个包含音频的 MIME 类型 斑点 到像这样的值 audio/pcm;rate=16000.

接收音频 #

模型的音频响应作为数据块被接收。

python
async for response in session.receive():
    if response.server_content and response.server_content.model_turn:
        for part in response.server_content.model_turn.parts:
            if part.inline_data:
                audio_data = part.inline_data.data
                # Process or play the audio data

发送文本 #

可以使用发送文本 send_realtime_input (Python)或 sendRealtimeInput (JavaScript)。

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

发送视频 #

视频帧以特定帧速率(每秒最大 1 帧)作为单独图像(例如 JPEG 或 PNG)发送。

python
# Assuming 'frame' is your JPEG-encoded image bytes
await session.send_realtime_input(
    video=types.Blob(
        data=frame,
        mime_type="image/jpeg"
    )
)

增量内容更新 #

使用增量更新发送文本输入、建立会话上下文或恢复会话上下文。对于简短的上下文,您可以发送逐轮交互来表示事件的确切顺序:

python
turns = [
    {"role": "user", "parts": [{"text": "What is the capital of France?"}]},
    {"role": "model", "parts": [{"text": "Paris"}]},
]

await session.send_client_content(turns=turns, turn_complete=False)

turns = [{"role": "user", "parts": [{"text": "What is the capital of Germany?"}]}]

await session.send_client_content(turns=turns, turn_complete=True)

对于较长的上下文,建议提供单个消息摘要,以释放上下文窗口用于后续交互。参见 会话恢复 另一种加载会话上下文的方法。

音频转录 #

除了模型响应之外,您还可以接收音频输出和音频输入的转录。

要启用模型音频输出的转录,请发送 output_audio_transcription 在设置配置中。转录语言是根据模型的响应推断出来的。

python
import asyncio
from google import genai
from google.genai import types

client = genai.Client(http_options={"api_version": "v1beta"})
model = "gemini-3.8-live"

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

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        message = "Hello? Gemini are you there?"

        await session.send_client_content(
            turns={"role": "user", "parts": [{"text": message}]}, turn_complete=True
        )

        async for response in session.receive():
            if response.server_content.model_turn:
                print("Model turn:", response.server_content.model_turn)
            if response.server_content.output_transcription:
                print("Transcript:", response.server_content.output_transcription.text)

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

要启用模型音频输入的转录,请发送 input_audio_transcription 在设置配置中。

python
import asyncio
from pathlib import Path
from google import genai
from google.genai import types

client = genai.Client(http_options={"api_version": "v1beta"})
model = "gemini-3.8-live"

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

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        audio_data = Path("16000.pcm").read_bytes()

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

        async for msg in session.receive():
            if msg.server_content.input_transcription:
                print('Transcript:', msg.server_content.input_transcription.text)

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

要改进输入转录识别特定术语(例如专有名词、品牌名称或技术术语)的方式,请添加 custom_vocabulary 列出至 input_audio_transcription。您最多可以提供 1,000 项,但通常使用最多 100 项才能获得最佳结果。有关更多详细信息,请参阅 自定义词汇偏差.

python
config = {
    "response_modalities": ["AUDIO"],
    "input_audio_transcription": {
        "custom_vocabulary": ["Gemini", "Kubernetes", "BigQuery"],
    },
}

改变声音和语言 #

原生音频输出 模型支持我们可用的任何声音 文本转语音(TTS) 模型。你可以听到所有的声音 人工智能工作室.

要指定语音,请在以下内容中设置语音名称: speechConfig 对象作为会话配置的一部分:

python
config = {
    "response_modalities": ["AUDIO"],
    "speech_config": {
        "voice_config": {"prebuilt_voice_config": {"voice_name": "Kore"}}
    },
}

原生音频功能 #

我们最新型号的特点 原生音频输出,提供自然、逼真的语音和改进的多语言性能。

思考 #

Gemini 3.8 Live Extended Thinking 和 Gemini 3.1 型号使用 thinkingLevel 来控制思维深度。对于 gemini-3.8-live, thinkingLevel 不受支持,必须在设置中省略。 Gemini 3.8 Live Extended Thinking 支持 low, medium, 和 high (minimal 不支持)。 Gemini 3.1型号支持 minimal, low, medium, 和 high。有关完整的详细信息和代码示例,请参阅 Live API 中的思考能力.

python
model = "gemini-3.8-live-extended-thinking"

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    thinking_config=types.ThinkingConfig(
        thinking_level="MEDIUM",
    )
)

async with client.aio.live.connect(model=model, config=config) as session:
    # Send audio input and receive audio

此外,您可以通过设置启用思想摘要 includeThoughts 到 true 在你的配置中。参见 接收思想摘要 欲了解更多信息:

python
model = "gemini-3.8-live-extended-thinking"

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    thinking_config=types.ThinkingConfig(
        thinking_level="HIGH",
        include_thoughts=True
    )
)

情感对话 #

此功能使 Gemini 能够根据输入的表情和语气调整其响应风格。

要使用情感对话框,请将 api 版本设置为 v1beta 并设置 enable_affective_dialog 到 true 在设置消息中:

python
client = genai.Client(http_options={"api_version": "v1beta"})

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    enable_affective_dialog=True
)

主动音频 #

启用此功能后,如果内容不相关,Gemini 可以主动决定不响应。

要使用它,请将 api 版本设置为 v1beta 并配置 proactivity 设置消息中的字段并设置 proactive_audio 到 true:

python
client = genai.Client(http_options={"api_version": "v1beta"})

config = types.LiveConnectConfig(
    response_modalities=["AUDIO"],
    proactivity={'proactive_audio': True}
)

实时翻译 #

Live API 支持语音对话的实时、低延迟翻译。此功能可让您构建实时语音到语音翻译应用程序。

有关更多信息和示例,请参阅 实时翻译指南.

语音活动检测 (VAD) #

语音活动检测 (VAD) 允许模型识别人何时说话。这对于创建自然对话至关重要,因为它允许用户随时中断模型。

当VAD检测到中断时,正在进行的生成被取消并丢弃。只有已经发送到客户端的信息才会保留在会话历史记录中。然后服务器发送一个 BidiGenerateContentServerContent 报告中断的消息。

然后,Gemini 服务器丢弃任何挂起的函数调用并发送一个 BidiGenerateContentServerContent 包含已取消呼叫 ID 的消息。

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

        # If realtime playback is implemented in your application,
        # you should stop playing audio and clear queued playback here.

自动VAD #

默认情况下,模型自动对连续音频输入流执行 VAD。 VAD 可以配置为 realtimeInputConfig.automaticActivityDetection 的领域 设置配置.

当音频流暂停超过一秒时(例如,因为用户关闭麦克风), audioStreamEnd 应发送事件以刷新所有缓存的音频。客户端可以随时恢复发送音频数据。

python
# example audio file to try:
# URL = "https://storage.googleapis.com/generativeai-downloads/data/hello_are_you_there.pcm"
# !wget -q $URL -O sample.pcm
import asyncio
from pathlib import Path
from google import genai
from google.genai import types

client = genai.Client(http_options={"api_version": "v1beta"})
model = "gemini-3.8-live"

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

async def main():
    async with client.aio.live.connect(model=model, config=config) as session:
        audio_bytes = Path("sample.pcm").read_bytes()

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

        # if stream gets paused, send:
        # await session.send_realtime_input(audio_stream_end=True)

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

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

自动VAD配置 #

为了更好地控制 VAD 活动,您可以配置以下参数。参见 API参考 了解更多信息。

python
from google.genai import types

config = {
    "response_modalities": ["AUDIO"],
    "realtime_input_config": {
        "automatic_activity_detection": {
            "disabled": False, # default
            "start_of_speech_sensitivity": types.StartSensitivity.START_SENSITIVITY_LOW,
            "end_of_speech_sensitivity": types.EndSensitivity.END_SENSITIVITY_LOW,
            "prefix_padding_ms": 20,
            "silence_duration_ms": 100,
        }
    }
}

混合VAD #

混合 VAD 结合了自动 VAD(鲁棒语音开始检测)和手动 VAD(低延迟响应完成)的优点。

在此配置中:

  1. 自动 VAD 保持启用状态 在服务器上。服务器自动检测用户语音的开头,使用前缀填充来避免剪切话语的开头。
  2. 客户端使用一个 客户端VAD 检测用户何时停止说话。
  3. 当客户端VAD检测到语音结束时,发送一个 audio_stream_end 向服务器发出信号。
  4. 服务器处理 audio_stream_end 信号作为立即完成提示,绕过默认的服务器端静音检测延迟,并以最小的延迟返回转录本和模型响应。
  5. 如果客户端VAD未能触发,服务器端VAD将作为后备来检测语音结束。

请注意,如果客户端VAD阈值设置得太过大,可能会导致语音中断。然而,这种方法可以防止手动 VAD 可能出现的前端截断问题。

python
# Set up with automatic VAD enabled (default)
config = {
    "response_modalities": ["AUDIO"],
}

async with client.aio.live.connect(model=model, config=config) as session:
    # Send audio data normally
    await session.send_realtime_input(
        audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
    )

    # When client-side VAD detects the end of speech, send:
    await session.send_realtime_input(audio_stream_end=True)

禁用自动 VAD #

或者,可以通过设置禁用自动 VAD realtimeInputConfig.automaticActivityDetection.disabled 到 true 在设置消息中。在此配置中,客户端负责检测用户语音并发送 activityStart 和 activityEnd 在适当的时间发送消息。一个 audioStreamEnd 在此配置中不发送。相反,任何流的中断都会被标记为 activityEnd 信息。

python
config = {
    "response_modalities": ["AUDIO"],
    "realtime_input_config": {"automatic_activity_detection": {"disabled": True}},
}

async with client.aio.live.connect(model=model, config=config) as session:
    # ...
    await session.send_realtime_input(activity_start=types.ActivityStart())
    await session.send_realtime_input(
        audio=types.Blob(data=audio_bytes, mime_type="audio/pcm;rate=16000")
    )
    await session.send_realtime_input(activity_end=types.ActivityEnd())
    # ...

了解 VAD 参数及其对质量的影响 #

使用自动 VAD 时,两个关键参数控制音频在发送到模型之前如何分段为语音轮流:

  • prefixPaddingMs:要包含的音频量 之前 检测到语音。这种“回顾”确保模型捕获完整的语音开始,包括可能在 VAD 触发之前开始的第一个音节。值为 0 可能会导致单词的开头被剪切。
  • silenceDurationMs:服务器在结束发言之前等待静默的时间。这决定了系统对自然句子中间停顿(例如思考、呼吸或子句边界)的容忍度。

的影响 silenceDurationMs 关于音频质量#

该 silenceDurationMs 值直接影响模型接收处理的音频块的大小和完整性:

  • 建议(500 毫秒–800 毫秒): 提供了良好的平衡——模型接收完整的、上下文丰富的音频块,同时保持合理的延迟。服务器的内部默认值约为 800ms。
  • 太低(例如,100ms–200ms): 系统在自然停顿期间结束语音轮流,将单个话语分成多个小音频片段。该模型单独接收这些片段,丢失跨片段上下文并导致转录和响应质量降低。
  • 太高(例如,2000ms+): 用户停止说话后,系统会等待很长时间,从而增加模型响应之前的感知延迟。

手动(客户端)VAD 的最佳实践#

当您禁用自动 VAD 并管理 activityStart/activityEnd 来自您自己的客户端语音检测的信号,请注意服务器的内置音频缓冲机制被绕过。这意味着:

  1. 无语音前缓冲区: 服务器不再在检测到的语音开始之前添加音频。您的客户端在发送之前应包含足够的音频上下文 activityStart.
  2. 无沉默容忍度: 服务器立即对您的操作进行操作 activityEnd 信号,无需额外等待。如果您的客户端 VAD 使用激进的语音结束阈值(例如 200 毫秒的静音),则语音可能会在自然停顿期间在句子中被切断。

要通过手动 VAD 保持音频质量,请使用至少为 500毫秒 在客户端的语音活动检测器中。低于该值的阈值通常会导致音频碎片,从而降低转录和模型响应质量。

token数 #

可以查到总消费次数token在 使用元数据 返回的服务器消息字段。

python
async for message in session.receive():
    # The server will periodically send messages that include UsageMetadata.
    if message.usage_metadata:
        usage = message.usage_metadata
        print(
            f"Used {usage.total_token_count} tokens in total. Response token breakdown:"
        )
        for detail in usage.response_tokens_details:
            match detail:
                case types.ModalityTokenCount(modality=modality, token_count=count):
                    print(f"{modality}: {count}")

媒体分辨率 #

您可以通过设置来指定输入媒体的媒体分辨率 mediaResolution 字段作为会话配置的一部分:

python
from google.genai import types

config = {
    "response_modalities": ["AUDIO"],
    "media_resolution": types.MediaResolution.MEDIA_RESOLUTION_LOW,
}

您可以配置 mediaResolution 用于包括音频、视频或图像输入的多模态会话。同时 mediaResolution 调整视觉输入每帧的 token 分配,音频流在所有分辨率设置中以每秒固定速率进行标记。欲了解更多信息,请参阅 媒体分辨率 指导。

限制 #

当您规划项目时,请考虑 Multimodal Live API 的以下限制。

响应方式 #

本机音频模型仅支持“音频响应模式”。如果您需要文本形式的模型响应,请使用 输出音频转录 功能。

客户端认证 #

默认情况下,多模态 Live API 仅提供服务器到服务器身份验证。如果您正在使用以下方式实现多模态 Live API 应用程序 客户端到服务器方法,你需要使用 短暂的 token 以降低安全风险。

会话持续时间 #

纯音频会话仅限于 15 分钟,音频加视频会话仅限于 2 分钟。不过,您可以配置不同的 会话管理技术 无限延长会话持续时间。

上下文窗口 #

会话的上下文窗口限制为:

  • 128k token 用于 原生音频输出 模型
  • 32k token 适用于其他多式联运 Live API 型号

支持的语言 #

多式联运 Live API 支持以下 99 语言。

语言BCP-47 代码语言BCP-47 代码
南非荷兰语af拉脱维亚语lv
阿寒ak立陶宛语lt
阿尔巴尼亚语sq马其顿语mk
阿姆哈拉语am马来语ms
阿拉伯语ar马拉雅拉姆语ml
亚美尼亚语hy马耳他语mt
阿萨姆语as毛利人mi
阿塞拜疆语az马拉地语mr
巴斯克语eu蒙古语mn
白俄罗斯语be尼泊尔语ne
孟加拉语bn挪威语no, nb
波斯尼亚语bs奥迪亚or
保加利亚语bg奥罗莫om
缅甸语my普什图语ps
加泰罗尼亚语ca波斯语fa
宿务语ceb波兰语pl
中文(简体)zh-Hans葡萄牙语(巴西)pt-BR
中文(繁体)zh-Hant葡萄牙语(葡萄牙)pt-PT
克罗地亚语hr旁遮普语pa
捷克语cs克丘亚语qu
丹麦语da罗马尼亚语ro
荷兰语nl罗曼什语rm
英语en俄语ru
爱沙尼亚语et塞尔维亚语sr
法罗语fo信德语sd
菲律宾人fil僧伽罗语si
芬兰语fi斯洛伐克语sk
法语fr斯洛文尼亚语sl
加利西亚语gl索马里语so
格鲁吉亚语ka南索托语st
德语de西班牙语es
希腊语el斯瓦希里语sw
古吉拉特语gu瑞典语sv
豪萨语ha塔吉克族tg
希伯来语he泰米尔语ta
印地语hi泰卢固语te
匈牙利语hu泰语th
冰岛语is茨瓦纳语tn
印度尼西亚语id土耳其语tr
爱尔兰语ga土库曼语tk
意大利语it乌克兰语uk
日语ja乌尔都语ur
卡纳达语kn乌兹别克语uz
哈萨克语kk越南语vi
高棉语km威尔士语cy
基尼亚卢旺达语rw西弗里斯兰语fy
韩语ko沃洛夫语wo
库尔德语ku约鲁巴语yo
吉尔吉斯斯坦ky祖鲁语zu
老挝lo

后续步骤 #

搜索标题、API 名称或正文内容