Live 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 |
|---|---|---|---|---|
支持(交错推理)。 | 支持(可配置后台推理: | 用途 | 用途 | |
单个服务器事件可以同时包含多个内容部分(例如, | 单个服务器事件可以同时包含多个内容部分。当异步推理处于活动状态时, | 单个服务器事件可以同时包含多个内容部分(例如, | 每个服务器事件仅包含一个内容部分。零件在单独的事件中交付。 | |
|
|
|
| |
默认为 | 默认为 | 默认为 | 默认为 | |
定制VAD ( | 支持。禁用自动 VAD 和发送 | 支持。禁用自动 VAD 和发送 | 支持。禁用自动 VAD 和发送 | 支持。禁用自动 VAD 和发送 |
支持。配置参数如 | 支持。配置参数如 | 支持。配置参数如 | 支持。配置参数如 | |
异步函数调用 ( | 支持(默认)。套装 | 支持(仅限异步)。仅 | 不支持。 函数调用仅是同步的。模型在响应之前等待工具响应。 | 支持(同步和异步)。 |
永久启用( | 永久启用( | 不支持 | 支持(可配置)。套装 | |
不支持(已删除;省略 | 不支持(已删除;省略 | 不支持 | 支持。套装 |
要从 Gemini 3.1 Flash Live Preview 迁移到 Gemini 3.8 Live,请参阅 迁移指南。要了解有关思考的更多信息,请参阅 Live API 中的思考能力 和 升级到Gemini 3.8 Live Extended Thinking.
建立连接 #
以下示例显示如何创建与 API 密钥的连接:
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())
import { GoogleGenAI, Modality } from '@google/genai';
const ai = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });
const model = 'gemini-3.8-live';
const config = { responseModalities: [Modality.AUDIO] };
async function main() {
const session = await ai.live.connect({
model: model,
callbacks: {
onopen: function () {
console.debug('Opened');
},
onmessage: function (message) {
console.debug(message);
},
onerror: function (e) {
console.debug('Error:', e.message);
},
onclose: function (e) {
console.debug('Close:', e.reason);
},
},
config: config,
});
console.debug("Session started");
// Send content...
session.close();
}
await main();
互动方式 #
以下部分提供了 Live API 中可用的不同输入和输出模式的示例和支持上下文。
发送音频 #
音频需要作为原始 PCM 数据发送(原始 16 位 PCM 音频,16kHz,小端)。
# Assuming 'chunk' is your raw PCM audio bytes
await session.send_realtime_input(
audio=types.Blob(
data=chunk,
mime_type="audio/pcm;rate=16000"
)
)
// Assuming 'chunk' is a Buffer of raw PCM audio
session.sendRealtimeInput({
audio: {
data: chunk.toString('base64'),
mimeType: 'audio/pcm;rate=16000'
}
});
音频格式 #
多模态 Live API 中的音频数据始终是原始、小端、16 位 PCM。音频输出始终使用 24kHz 的采样率。输入音频本身为 16kHz,但多模态 Live API 将在需要时重新采样,以便可以发送任何采样率。要传达输入音频的采样率,请设置每个包含音频的 MIME 类型 斑点 到像这样的值 audio/pcm;rate=16000.
接收音频 #
模型的音频响应作为数据块被接收。
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
// 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;
// Process or play audioData (base64 encoded string)
}
}
}
发送文本 #
可以使用发送文本 send_realtime_input (Python)或 sendRealtimeInput (JavaScript)。
await session.send_realtime_input(text="Hello, how are you?")
session.sendRealtimeInput({
text: 'Hello, how are you?'
});
发送视频 #
视频帧以特定帧速率(每秒最大 1 帧)作为单独图像(例如 JPEG 或 PNG)发送。
# Assuming 'frame' is your JPEG-encoded image bytes
await session.send_realtime_input(
video=types.Blob(
data=frame,
mime_type="image/jpeg"
)
)
// Assuming 'frame' is a Buffer of JPEG-encoded image data
session.sendRealtimeInput({
video: {
data: frame.toString('base64'),
mimeType: 'image/jpeg'
}
});
增量内容更新 #
使用增量更新发送文本输入、建立会话上下文或恢复会话上下文。对于简短的上下文,您可以发送逐轮交互来表示事件的确切顺序:
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)
let inputTurns = [
{ "role": "user", "parts": [{ "text": "What is the capital of France?" }] },
{ "role": "model", "parts": [{ "text": "Paris" }] },
]
session.sendClientContent({ turns: inputTurns, turnComplete: false })
inputTurns = [{ "role": "user", "parts": [{ "text": "What is the capital of Germany?" }] }]
session.sendClientContent({ turns: inputTurns, turnComplete: true })
对于较长的上下文,建议提供单个消息摘要,以释放上下文窗口用于后续交互。参见 会话恢复 另一种加载会话上下文的方法。
音频转录 #
除了模型响应之外,您还可以接收音频输出和音频输入的转录。
要启用模型音频输出的转录,请发送 output_audio_transcription 在设置配置中。转录语言是根据模型的响应推断出来的。
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())
import { GoogleGenAI, Modality } from '@google/genai';
const ai = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });
const model = 'gemini-3.8-live';
const config = {
responseModalities: [Modality.AUDIO],
outputAudioTranscription: {}
};
async function live() {
const responseQueue = [];
async function waitMessage() {
let done = false;
let message = undefined;
while (!done) {
message = responseQueue.shift();
if (message) {
done = true;
} else {
await new Promise((resolve) => setTimeout(resolve, 100));
}
}
return message;
}
async function handleTurn() {
const turns = [];
let done = false;
while (!done) {
const message = await waitMessage();
turns.push(message);
if (message.serverContent && message.serverContent.turnComplete) {
done = true;
}
}
return turns;
}
const session = await ai.live.connect({
model: model,
callbacks: {
onopen: function () {
console.debug('Opened');
},
onmessage: function (message) {
responseQueue.push(message);
},
onerror: function (e) {
console.debug('Error:', e.message);
},
onclose: function (e) {
console.debug('Close:', e.reason);
},
},
config: config,
});
const inputTurns = 'Hello how are you?';
session.sendClientContent({ turns: inputTurns });
const turns = await handleTurn();
for (const turn of turns) {
if (turn.serverContent && turn.serverContent.outputTranscription) {
console.debug('Received output transcription: %s\n', turn.serverContent.outputTranscription.text);
}
}
session.close();
}
async function main() {
await live().catch((e) => console.error('got error', e));
}
await main();
要启用模型音频输入的转录,请发送 input_audio_transcription 在设置配置中。
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())
import { GoogleGenAI, Modality } from '@google/genai';
import * as fs from "node:fs";
import pkg from 'wavefile';
const { WaveFile } = pkg;
const ai = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });
const model = 'gemini-3.8-live';
const config = {
responseModalities: [Modality.AUDIO],
inputAudioTranscription: {}
};
async function live() {
const responseQueue = [];
async function waitMessage() {
let done = false;
let message = undefined;
while (!done) {
message = responseQueue.shift();
if (message) {
done = true;
} else {
await new Promise((resolve) => setTimeout(resolve, 100));
}
}
return message;
}
async function handleTurn() {
const turns = [];
let done = false;
while (!done) {
const message = await waitMessage();
turns.push(message);
if (message.serverContent && message.serverContent.turnComplete) {
done = true;
}
}
return turns;
}
const session = await ai.live.connect({
model: model,
callbacks: {
onopen: function () {
console.debug('Opened');
},
onmessage: function (message) {
responseQueue.push(message);
},
onerror: function (e) {
console.debug('Error:', e.message);
},
onclose: function (e) {
console.debug('Close:', e.reason);
},
},
config: config,
});
// Send Audio Chunk
const fileBuffer = fs.readFileSync("16000.wav");
// Ensure audio conforms to API requirements (16-bit PCM, 16kHz, mono)
const wav = new WaveFile();
wav.fromBuffer(fileBuffer);
wav.toSampleRate(16000);
wav.toBitDepth("16");
const base64Audio = wav.toBase64();
// If already in correct format, you can use this:
// const fileBuffer = fs.readFileSync("sample.pcm");
// const base64Audio = Buffer.from(fileBuffer).toString('base64');
session.sendRealtimeInput(
{
audio: {
data: base64Audio,
mimeType: "audio/pcm;rate=16000"
}
}
);
const turns = await handleTurn();
for (const turn of turns) {
if (turn.text) {
console.debug('Received text: %s\n', turn.text);
}
else if (turn.data) {
console.debug('Received inline data: %s\n', turn.data);
}
else if (turn.serverContent && turn.serverContent.inputTranscription) {
console.debug('Received input transcription: %s\n', turn.serverContent.inputTranscription.text);
}
}
session.close();
}
async function main() {
await live().catch((e) => console.error('got error', e));
}
await main();
要改进输入转录识别特定术语(例如专有名词、品牌名称或技术术语)的方式,请添加 custom_vocabulary 列出至 input_audio_transcription。您最多可以提供 1,000 项,但通常使用最多 100 项才能获得最佳结果。有关更多详细信息,请参阅 自定义词汇偏差.
config = {
"response_modalities": ["AUDIO"],
"input_audio_transcription": {
"custom_vocabulary": ["Gemini", "Kubernetes", "BigQuery"],
},
}
const config = {
responseModalities: [Modality.AUDIO],
inputAudioTranscription: {
customVocabulary: ['Gemini', 'Kubernetes', 'BigQuery'],
},
};
改变声音和语言 #
原生音频输出 模型支持我们可用的任何声音 文本转语音(TTS) 模型。你可以听到所有的声音 人工智能工作室.
要指定语音,请在以下内容中设置语音名称: speechConfig 对象作为会话配置的一部分:
config = {
"response_modalities": ["AUDIO"],
"speech_config": {
"voice_config": {"prebuilt_voice_config": {"voice_name": "Kore"}}
},
}
const config = {
responseModalities: [Modality.AUDIO],
speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: "Kore" } } }
};
略有不同。请参阅 语音生成指南 用于 generateContent 音频生成声音。
原生音频功能 #
我们最新型号的特点 原生音频输出,提供自然、逼真的语音和改进的多语言性能。
思考 #
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 中的思考能力.
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
const model = 'gemini-3.8-live-extended-thinking';
const config = {
responseModalities: [Modality.AUDIO],
thinkingConfig: {
thinkingLevel: 'MEDIUM',
},
};
async function main() {
const session = await ai.live.connect({
model: model,
config: config,
callbacks: ...,
});
// Send audio input and receive audio
session.close();
}
await main();
此外,您可以通过设置启用思想摘要 includeThoughts 到 true 在你的配置中。参见 接收思想摘要 欲了解更多信息:
model = "gemini-3.8-live-extended-thinking"
config = types.LiveConnectConfig(
response_modalities=["AUDIO"],
thinking_config=types.ThinkingConfig(
thinking_level="HIGH",
include_thoughts=True
)
)
const model = 'gemini-3.8-live-extended-thinking';
const config = {
responseModalities: [Modality.AUDIO],
thinkingConfig: {
thinkingLevel: 'HIGH',
includeThoughts: true,
},
};
情感对话 #
此功能使 Gemini 能够根据输入的表情和语气调整其响应风格。
要使用情感对话框,请将 api 版本设置为 v1beta 并设置 enable_affective_dialog 到 true 在设置消息中:
client = genai.Client(http_options={"api_version": "v1beta"})
config = types.LiveConnectConfig(
response_modalities=["AUDIO"],
enable_affective_dialog=True
)
const ai = new GoogleGenAI({ httpOptions: {"apiVersion": "v1beta"} });
const config = {
responseModalities: [Modality.AUDIO],
enableAffectiveDialog: true
};
主动音频 #
启用此功能后,如果内容不相关,Gemini 可以主动决定不响应。
要使用它,请将 api 版本设置为 v1beta 并配置 proactivity 设置消息中的字段并设置 proactive_audio 到 true:
client = genai.Client(http_options={"api_version": "v1beta"})
config = types.LiveConnectConfig(
response_modalities=["AUDIO"],
proactivity={'proactive_audio': True}
)
const ai = new GoogleGenAI({ httpOptions: {"apiVersion": "v1beta"} });
const config = {
responseModalities: [Modality.AUDIO],
proactivity: { proactiveAudio: true }
}
实时翻译 #
Live API 支持语音对话的实时、低延迟翻译。此功能可让您构建实时语音到语音翻译应用程序。
有关更多信息和示例,请参阅 实时翻译指南.
语音活动检测 (VAD) #
语音活动检测 (VAD) 允许模型识别人何时说话。这对于创建自然对话至关重要,因为它允许用户随时中断模型。
当VAD检测到中断时,正在进行的生成被取消并丢弃。只有已经发送到客户端的信息才会保留在会话历史记录中。然后服务器发送一个 BidiGenerateContentServerContent 报告中断的消息。
然后,Gemini 服务器丢弃任何挂起的函数调用并发送一个 BidiGenerateContentServerContent 包含已取消呼叫 ID 的消息。
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.
const turns = await handleTurn();
for (const turn of turns) {
if (turn.serverContent && turn.serverContent.interrupted) {
// 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 应发送事件以刷新所有缓存的音频。客户端可以随时恢复发送音频数据。
# 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())
// 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 { GoogleGenAI, Modality } from '@google/genai';
import * as fs from "node:fs";
const ai = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });
const model = 'gemini-3.8-live';
const config = { responseModalities: [Modality.AUDIO] };
async function live() {
const responseQueue = [];
async function waitMessage() {
let done = false;
let message = undefined;
while (!done) {
message = responseQueue.shift();
if (message) {
done = true;
} else {
await new Promise((resolve) => setTimeout(resolve, 100));
}
}
return message;
}
async function handleTurn() {
const turns = [];
let done = false;
while (!done) {
const message = await waitMessage();
turns.push(message);
if (message.serverContent && message.serverContent.turnComplete) {
done = true;
}
}
return turns;
}
const session = await ai.live.connect({
model: model,
callbacks: {
onopen: function () {
console.debug('Opened');
},
onmessage: function (message) {
responseQueue.push(message);
},
onerror: function (e) {
console.debug('Error:', e.message);
},
onclose: function (e) {
console.debug('Close:', e.reason);
},
},
config: config,
});
// Send Audio Chunk
const fileBuffer = fs.readFileSync("sample.pcm");
const base64Audio = Buffer.from(fileBuffer).toString('base64');
session.sendRealtimeInput(
{
audio: {
data: base64Audio,
mimeType: "audio/pcm;rate=16000"
}
}
);
// if stream gets paused, send:
// session.sendRealtimeInput({ audioStreamEnd: true })
const turns = await handleTurn();
for (const turn of turns) {
if (turn.text) {
console.debug('Received text: %s\n', turn.text);
}
else if (turn.data) {
console.debug('Received inline data: %s\n', turn.data);
}
}
session.close();
}
async function main() {
await live().catch((e) => console.error('got error', e));
}
await main();
与 send_realtime_input,API将根据VAD自动响应音频。同时 send_client_content 按顺序将消息添加到模型上下文, send_realtime_input 以牺牲确定性排序为代价来优化响应能力。
自动VAD配置 #
为了更好地控制 VAD 活动,您可以配置以下参数。参见 API参考 了解更多信息。
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,
}
}
}
import { GoogleGenAI, Modality, StartSensitivity, EndSensitivity } from '@google/genai';
const config = {
responseModalities: [Modality.AUDIO],
realtimeInputConfig: {
automaticActivityDetection: {
disabled: false, // default
startOfSpeechSensitivity: StartSensitivity.START_SENSITIVITY_LOW,
endOfSpeechSensitivity: EndSensitivity.END_SENSITIVITY_LOW,
prefixPaddingMs: 20,
silenceDurationMs: 100,
}
}
};
混合VAD #
混合 VAD 结合了自动 VAD(鲁棒语音开始检测)和手动 VAD(低延迟响应完成)的优点。
在此配置中:
- 自动 VAD 保持启用状态 在服务器上。服务器自动检测用户语音的开头,使用前缀填充来避免剪切话语的开头。
- 客户端使用一个 客户端VAD 检测用户何时停止说话。
- 当客户端VAD检测到语音结束时,发送一个
audio_stream_end向服务器发出信号。 - 服务器处理
audio_stream_end信号作为立即完成提示,绕过默认的服务器端静音检测延迟,并以最小的延迟返回转录本和模型响应。 - 如果客户端VAD未能触发,服务器端VAD将作为后备来检测语音结束。
请注意,如果客户端VAD阈值设置得太过大,可能会导致语音中断。然而,这种方法可以防止手动 VAD 可能出现的前端截断问题。
# 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)
// Set up with automatic VAD enabled (default)
const config = {
responseModalities: [Modality.AUDIO],
};
// Send audio data normally
session.sendRealtimeInput({
audio: {
data: base64Audio,
mimeType: "audio/pcm;rate=16000"
}
});
// When client-side VAD detects the end of speech, send:
session.sendRealtimeInput({ audioStreamEnd: true });
禁用自动 VAD #
或者,可以通过设置禁用自动 VAD realtimeInputConfig.automaticActivityDetection.disabled 到 true 在设置消息中。在此配置中,客户端负责检测用户语音并发送 activityStart 和 activityEnd 在适当的时间发送消息。一个 audioStreamEnd 在此配置中不发送。相反,任何流的中断都会被标记为 activityEnd 信息。
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())
# ...
const config = {
responseModalities: [Modality.AUDIO],
realtimeInputConfig: {
automaticActivityDetection: {
disabled: true,
}
}
};
session.sendRealtimeInput({ activityStart: {} })
session.sendRealtimeInput(
{
audio: {
data: base64Audio,
mimeType: "audio/pcm;rate=16000"
}
}
);
session.sendRealtimeInput({ activityEnd: {} })
了解 VAD 参数及其对质量的影响 #
使用自动 VAD 时,两个关键参数控制音频在发送到模型之前如何分段为语音轮流:
prefixPaddingMs:要包含的音频量 之前 检测到语音。这种“回顾”确保模型捕获完整的语音开始,包括可能在 VAD 触发之前开始的第一个音节。值为0可能会导致单词的开头被剪切。silenceDurationMs:服务器在结束发言之前等待静默的时间。这决定了系统对自然句子中间停顿(例如思考、呼吸或子句边界)的容忍度。
的影响 silenceDurationMs 关于音频质量#
该 silenceDurationMs 值直接影响模型接收处理的音频块的大小和完整性:
- 建议(500 毫秒–800 毫秒): 提供了良好的平衡——模型接收完整的、上下文丰富的音频块,同时保持合理的延迟。服务器的内部默认值约为 800ms。
- 太低(例如,100ms–200ms): 系统在自然停顿期间结束语音轮流,将单个话语分成多个小音频片段。该模型单独接收这些片段,丢失跨片段上下文并导致转录和响应质量降低。
- 太高(例如,2000ms+): 用户停止说话后,系统会等待很长时间,从而增加模型响应之前的感知延迟。
手动(客户端)VAD 的最佳实践#
当您禁用自动 VAD 并管理 activityStart/activityEnd 来自您自己的客户端语音检测的信号,请注意服务器的内置音频缓冲机制被绕过。这意味着:
- 无语音前缓冲区: 服务器不再在检测到的语音开始之前添加音频。您的客户端在发送之前应包含足够的音频上下文
activityStart. - 无沉默容忍度: 服务器立即对您的操作进行操作
activityEnd信号,无需额外等待。如果您的客户端 VAD 使用激进的语音结束阈值(例如 200 毫秒的静音),则语音可能会在自然停顿期间在句子中被切断。
要通过手动 VAD 保持音频质量,请使用至少为 500毫秒 在客户端的语音活动检测器中。低于该值的阈值通常会导致音频碎片,从而降低转录和模型响应质量。
token数 #
可以查到总消费次数token在 使用元数据 返回的服务器消息字段。
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}")
const turns = await handleTurn();
for (const turn of turns) {
if (turn.usageMetadata) {
console.debug('Used %s tokens in total. Response token breakdown:\n', turn.usageMetadata.totalTokenCount);
for (const detail of turn.usageMetadata.responseTokensDetails) {
console.debug('%s\n', detail);
}
}
}
媒体分辨率 #
您可以通过设置来指定输入媒体的媒体分辨率 mediaResolution 字段作为会话配置的一部分:
from google.genai import types
config = {
"response_modalities": ["AUDIO"],
"media_resolution": types.MediaResolution.MEDIA_RESOLUTION_LOW,
}
import { GoogleGenAI, Modality, MediaResolution } from '@google/genai';
const config = {
responseModalities: [Modality.AUDIO],
mediaResolution: 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 |
后续步骤 #
- 阅读 Live API 中的思考能力, 工具使用, 和 会话管理 有关有效使用 Live API 的基本信息的指南。
- 尝试多式联运 Live API Google AI Studio.
- 有关 Live API 型号的更多信息,请参阅 Gemini 3.8 Live 和 Gemini 3.8 Live Extended Thinking 在模型页面上。
- 尝试更多示例 Live API食谱, 的 Live API 工具食谱,以及 Live API 入门脚本.