使用 Gemini Live API 实时转写
Gemini Live API 使用以下功能支持低延迟、实时语音到文本转录 gemini-3.5-transcribe-live 模型。通过通过 WebSocket 连接到 Live API 或使用 Google Gen AI SDK,您可以流式传输连续的音频输入,并在语音发生时接收增量实时文本转录。
尝试在 Google AI Studio 中进行实时转录
打开 Colab 食谱
使用编码智能体技巧
通过利用 Gemini Live API,开发者平台,例如 集市, 鱼酱, 直播套件, 管道猫, 韦尔塞尔, 和 愿景智能体 使开发人员能够轻松构建和部署高性能语音驱动界面。这些平台在后台管理复杂的实时媒体流基础设施,使开发人员能够完全专注于打造用户体验。
实时智能体与实时转录 #
虽然两者都使用 Live API 双向流连接,但实时转录作为专用的低延迟语音识别管道运行,而不是会话式智能体。
| 特点 | 直播智能体 | 实时转录 |
|---|---|---|
| 主要角色 | 能够倾听、推理和回复的会话助理。 | 用于转录传入音频的实时语音到文本管道。 |
| 响应方式 | 语音和文本(response_modalities=["AUDIO"]). | 流式文本转录(response_modalities=["TEXT"]). |
| 交互方式 | 回合制对话,具有暂停检测和中断功能。 | 演讲者讲话时进行连续流处理。 |
| 支持的功能 | 函数调用、Google 搜索、系统指令、带语音偏置的输入音频转录(custom_vocabulary) 上 gemini-3.8-live. | 语音偏差(custom_vocabulary)、语言检测、手动和混合 VAD、智能转录。 |
| 输入流 | 多模态:音频、视频、图像、文本。 | 音频输入(原始 16 位 PCM)。 |
快速入门 #
以下示例演示了如何使用以下命令打开双向流会话 gemini-3.5-transcribe-live 并接收实时转录。
import asyncio
from google import genai
from google.genai import types
client = genai.Client(http_options={"api_version": "v1beta"})
model = "gemini-3.5-transcribe-live"
config = types.LiveConnectConfig(
response_modalities=["TEXT"],
input_audio_transcription=types.AudioTranscriptionConfig(
language_codes=[], # Automatic language detection
),
)
async def main():
async with client.aio.live.connect(model=model, config=config) as session:
print("Session established with Live Transcription")
# Receive transcription events
async for response in session.receive():
server_content = response.server_content
if server_content and server_content.input_transcription:
print("Transcript:", server_content.input_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.5-transcribe-live';
const config = {
responseModalities: [Modality.TEXT],
inputAudioTranscription: {
languageCodes: [], // Automatic language detection
},
};
async function main() {
const session = await ai.live.connect({
model: model,
config: config,
callbacks: {
onopen: () => console.log('Connected to Live Transcription'),
onmessage: (message) => {
const content = message.serverContent;
if (content?.inputTranscription) {
console.log('Transcript:', content.inputTranscription.text);
}
},
onerror: (e) => console.error('Error:', e.message),
onclose: (e) => console.log('Connection closed:', e.reason),
},
});
}
await main();
const API_KEY = "YOUR_API_KEY";
const MODEL_NAME = "gemini-3.5-transcribe-live";
const WS_URL = `wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent?key=${API_KEY}`;
const websocket = new WebSocket(WS_URL);
websocket.onopen = () => {
console.log('WebSocket connected');
const setupMessage = {
setup: {
model: `models/${MODEL_NAME}`,
generationConfig: {
responseModalities: ['TEXT'],
},
inputAudioTranscription: {
languageCodes: []
}
}
};
websocket.send(JSON.stringify(setupMessage));
};
websocket.onmessage = (event) => {
const response = JSON.parse(event.data);
const content = response.serverContent;
if (content?.inputTranscription) {
console.log('Transcript:', content.inputTranscription.text);
}
};
临时和最终转录 #
当音频流进入 Live API 时,服务器会在内部发出两个互补的转录字段 server_content:
interim_input_transcription:低延迟、推测性部分假设在说话者积极讲话时更新。这些部分更新以最小的延迟快速发生。使用interim_input_transcription渲染响应式实时 UI 字幕或预览字幕。input_transcription:当演讲者暂停、回合完成或演讲结束时发出的最终文本。一旦发出,该文本就代表模型对该语音片段的权威转录。在智能转录模式下,这将包括经过清理、格式化的响应。
以下示例演示了如何显示流式中间部分并提交最终成绩单:
async def receive_transcripts(session):
async for response in session.receive():
server_content = response.server_content
if not server_content:
continue
# Real-time interim hypothesis (updates dynamically as user speaks)
if server_content.interim_input_transcription:
interim_text = server_content.interim_input_transcription.text
print(f"\r[Interim] {interim_text}", end="", flush=True)
# Finalized transcript (emitted on speech completion)
if server_content.input_transcription:
final_text = server_content.input_transcription.text
print(f"\n[Final] {final_text}")
onmessage: (message) => {
const content = message.serverContent;
if (!content) return;
if (content.interimInputTranscription) {
// Update live subtitle preview on screen
renderInterimPreview(content.interimInputTranscription.text);
}
if (content.inputTranscription) {
// Append final committed transcript to chat history
commitFinalTranscript(content.inputTranscription.text);
}
};
websocket.onmessage = (event) => {
const response = JSON.parse(event.data);
const content = response.serverContent;
if (content?.interimInputTranscription) {
console.log('[Interim]:', content.interimInputTranscription.text);
}
if (content?.inputTranscription) {
console.log('[Final]:', content.inputTranscription.text);
}
};
发送音频 #
通过活动连接将音频块作为原始 16 位 PCM 音频进行流式传输。
- 音频格式: 16kHz 的原始 16 位 PCM(单声道、小端)。
- 块大小: 以 100 毫秒为单位发送音频(1,024 到 2,048 帧)。
- MIME 类型:
audio/pcm;rate=16000(或匹配的采样率)。
# Stream a raw PCM audio chunk
await session.send_realtime_input(
audio=types.Blob(
data=audio_chunk_bytes,
mime_type="audio/pcm;rate=16000"
)
)
# Signal the end of the audio stream when finished
await session.send_realtime_input(audio_stream_end=True)
// Send base64-encoded PCM audio chunk
session.sendRealtimeInput({
audio: {
data: audioChunkBase64,
mimeType: 'audio/pcm;rate=16000'
}
});
// Signal stream end
session.sendRealtimeInput({
audioStreamEnd: true
});
// Send base64-encoded PCM audio chunk
websocket.send(JSON.stringify({
realtimeInput: {
audio: {
data: audioChunkBase64,
mimeType: 'audio/pcm;rate=16000'
}
}
}));
// Signal stream end
websocket.send(JSON.stringify({
realtimeInput: {
audioStreamEnd: true
}
}));
转录特征 #
自动语言检测 #
默认情况下,省略 language_codes 或设置 language_codes=[] 启用自动语言识别。该模型动态检测各种话语中的口语,包括多语言对话和语码转换。
config = types.LiveConnectConfig(
response_modalities=["TEXT"],
input_audio_transcription=types.AudioTranscriptionConfig(
language_codes=[],
),
)
const config = {
responseModalities: [Modality.TEXT],
inputAudioTranscription: {
languageCodes: [],
},
};
const setupMessage = {
setup: {
model: 'models/gemini-3.5-transcribe-live',
generationConfig: {
responseModalities: ['TEXT'],
},
inputAudioTranscription: {
languageCodes: [],
},
},
};
websocket.send(JSON.stringify(setupMessage));
具体语言提示 #
提供明确的 BCP-47 语言代码(例如, ["es-ES"] 对于西班牙语或 ["fr-FR"] 对于法语)使识别偏向于特定语言(参见 支持的语言).
config = types.LiveConnectConfig(
response_modalities=["TEXT"],
input_audio_transcription=types.AudioTranscriptionConfig(
language_codes=["es-ES"],
),
)
const config = {
responseModalities: [Modality.TEXT],
inputAudioTranscription: {
languageCodes: ['es-ES'],
},
};
const setupMessage = {
setup: {
model: 'models/gemini-3.5-transcribe-live',
generationConfig: {
responseModalities: ['TEXT'],
},
inputAudioTranscription: {
languageCodes: ['es-ES'],
},
},
};
websocket.send(JSON.stringify(setupMessage));
自定义词汇偏差 #
提供最多 1,000 短语、专有名词、品牌名称或技术术语的列表 custom_vocabulary 将语音识别偏向于特定术语(通常使用最多 100 术语可以获得最佳结果)。
config = types.LiveConnectConfig(
response_modalities=["TEXT"],
input_audio_transcription=types.AudioTranscriptionConfig(
language_codes=[],
custom_vocabulary=["Gemini", "Kubernetes", "BigQuery"],
),
)
const config = {
responseModalities: [Modality.TEXT],
inputAudioTranscription: {
languageCodes: [],
customVocabulary: ['Gemini', 'Kubernetes', 'BigQuery'],
},
};
const setupMessage = {
setup: {
model: 'models/gemini-3.5-transcribe-live',
generationConfig: {
responseModalities: ['TEXT'],
},
inputAudioTranscription: {
languageCodes: [],
customVocabulary: ['Gemini', 'Kubernetes', 'BigQuery'],
},
},
};
websocket.send(JSON.stringify(setupMessage));
智能转录 #
使用以下命令配置转录输出格式 mode 参数输入 input_audio_transcription:
VERBATIM(默认):生成所有所说内容的精确文字记录,保留原始填充词(“嗯”、“呃”、“喜欢”)、重复和错误的开头。SMART(智能转录):清理并构建文字记录以提高可读性:* 消除不流畅:删除填充词、口吃和错误的开头。- 内联自我更正:自然地解决口头更正。
- 结构化格式:自动设置列表、项目符号、数字、日期和段落分隔符的格式。
- 语法和大小写:应用自然大写和标点符号修饰。
config = types.LiveConnectConfig(
response_modalities=["TEXT"],
input_audio_transcription=types.AudioTranscriptionConfig(
mode="SMART",
),
)
const config = {
responseModalities: [Modality.TEXT],
inputAudioTranscription: {
mode: 'SMART',
},
};
const setupMessage = {
setup: {
model: 'models/gemini-3.5-transcribe-live',
generationConfig: {
responseModalities: ['TEXT'],
},
inputAudioTranscription: {
mode: 'SMART',
},
},
};
websocket.send(JSON.stringify(setupMessage));
语音活动检测 (VAD) 策略 #
自动VAD(默认) #
默认情况下,服务器端自动语音活动检测会检测扬声器何时开始和停止讲话。
混合VAD #
混合VAD 将服务器端自动语音开始检测与客户端语音结束检测相结合,以实现零延迟转弯完成:
- 服务器端自动VAD保持启用状态 通过前缀音频填充准确检测语音开头,防止前词截断。
- 客户端VAD检测到静默:当本地端VAD检测到说话人停止说话时,客户端发送
audio_stream_end立即发出信号。 - 快速定稿: 服务器处理
audio_stream_end作为立即的回合结束提示,绕过默认的服务器端静默等待时间并以最小的延迟返回最终的转录本。 - 回退:如果客户端VAD触发失败,服务器端VAD将作为自动回退。
config = types.LiveConnectConfig(
response_modalities=["TEXT"],
input_audio_transcription=types.AudioTranscriptionConfig(),
)
async with client.aio.live.connect(model=model, config=config) as session:
# Stream audio chunks...
await session.send_realtime_input(
audio=types.Blob(data=chunk, mime_type="audio/pcm;rate=16000")
)
# When client-side VAD detects end of speech, send audio_stream_end:
await session.send_realtime_input(audio_stream_end=True)
const config = {
responseModalities: [Modality.TEXT],
inputAudioTranscription: {},
};
// Stream audio...
session.sendRealtimeInput({
audio: { data: chunkBase64, mimeType: 'audio/pcm;rate=16000' }
});
// When client VAD detects end of speech, send audioStreamEnd:
session.sendRealtimeInput({
audioStreamEnd: true
});
const setupMessage = {
setup: {
model: 'models/gemini-3.5-transcribe-live',
generationConfig: {
responseModalities: ['TEXT'],
},
inputAudioTranscription: {},
},
};
websocket.send(JSON.stringify(setupMessage));
// Stream audio...
websocket.send(JSON.stringify({
realtimeInput: {
audio: { data: chunkBase64, mimeType: 'audio/pcm;rate=16000' }
}
}));
// When client VAD detects end of speech, send audioStreamEnd:
websocket.send(JSON.stringify({
realtimeInput: {
audioStreamEnd: true
}
}));
手动 VAD(一键通) #
对于对讲机接口或一键通按钮,完全禁用自动 VAD 并使用显式控制转弯边界 activity_start 和 activity_end:
config = types.LiveConnectConfig(
response_modalities=["TEXT"],
realtime_input_config=types.RealtimeInputConfig(
automatic_activity_detection=types.AutomaticActivityDetection(
disabled=True
)
),
input_audio_transcription=types.AudioTranscriptionConfig(),
)
async with client.aio.live.connect(model=model, config=config) as session:
# Button pressed: signal speech start
await session.send_realtime_input(activity_start=types.ActivityStart())
# Stream audio chunks...
await session.send_realtime_input(audio=types.Blob(data=chunk, mime_type="audio/pcm;rate=16000"))
# Button released: signal speech end
await session.send_realtime_input(activity_end=types.ActivityEnd())
const config = {
responseModalities: [Modality.TEXT],
realtimeInputConfig: {
automaticActivityDetection: {
disabled: true,
},
},
inputAudioTranscription: {},
};
// Signal speech start
session.sendRealtimeInput({ activityStart: {} });
// Stream audio...
// Signal speech end
session.sendRealtimeInput({ activityEnd: {} });
const setupMessage = {
setup: {
model: 'models/gemini-3.5-transcribe-live',
generationConfig: {
responseModalities: ['TEXT'],
},
realtimeInputConfig: {
automaticActivityDetection: {
disabled: true,
},
},
inputAudioTranscription: {},
},
};
websocket.send(JSON.stringify(setupMessage));
// Button pressed: signal speech start
websocket.send(JSON.stringify({
realtimeInput: {
activityStart: {},
},
}));
// Stream audio...
websocket.send(JSON.stringify({
realtimeInput: {
audio: { data: chunkBase64, mimeType: 'audio/pcm;rate=16000' },
},
}));
// Button released: signal speech end
websocket.send(JSON.stringify({
realtimeInput: {
activityEnd: {},
},
}));
客户端应用程序中的临时 token #
对于客户端到服务器应用程序(例如直接从麦克风流式传输的移动或 Web 应用程序),请使用 短暂的 token 以避免在客户端代码中暴露您的 API 密钥。
在启动客户端连接之前,在服务器上创建受约束的临时 token:
import datetime
from google import genai
client = genai.Client(http_options={"api_version": "v1beta"})
expire_time = datetime.datetime.now(tz=datetime.timezone.utc) + datetime.timedelta(minutes=30)
token = client.auth_tokens.create(
config={
"uses": 1,
"expire_time": expire_time,
"live_connect_constraints": {
"model": "gemini-3.5-transcribe-live",
"config": {
"response_modalities": ["TEXT"],
"input_audio_transcription": {
"language_codes": [],
},
},
},
}
)
import { GoogleGenAI } from '@google/genai';
const client = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });
const expireTime = new Date(Date.now() + 30 * 60 * 1000).toISOString();
const token = await client.authTokens.create({
config: {
uses: 1,
expireTime: expireTime,
liveConnectConstraints: {
model: 'gemini-3.5-transcribe-live',
config: {
responseModalities: ['TEXT'],
inputAudioTranscription: {
languageCodes: [],
},
},
},
},
});
curl -X POST "https://generativelanguage.googleapis.com/v1beta/auth_tokens" \
-H "x-goog-api-key: ${GEMINI_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"uses": 1,
"expireTime": "YYYY-MM-DDTHH:MM:SSZ",
"liveConnectConstraints": {
"model": "models/gemini-3.5-transcribe-live",
"config": {
"responseModalities": ["TEXT"],
"inputAudioTranscription": {
"languageCodes": []
}
}
}
}'
支持的语言 #
Gemini 3.5 Transcribe Live 支持以下语言和 BCP-47 语言代码:
| 语言 | BCP-47 代码 | 语言 | BCP-47 代码 |
|---|---|---|---|
| 南非荷兰语 | af-ZA | 日语 | ja-JP |
| 阿姆哈拉语 | am-ET | 爪哇语 | jv-ID |
| 阿拉伯语(埃及) | ar-EG | 卡布韦尔迪亚努 | kea-CV |
| 亚美尼亚语 | hy-AM | 卡纳达语 | kn-IN |
| 阿萨姆语 | as-IN | 哈萨克语 | kk-KZ |
| 阿塞拜疆语 | az-AZ | 韩语 | ko-KR |
| 白俄罗斯语 | be-BY | 吉尔吉斯斯坦 | ky-KG |
| 孟加拉语(孟加拉国) | bn-BD | 拉脱维亚语 | lv-LV |
| 孟加拉语(印度) | bn-IN | 林加拉语 | ln-CD |
| 波斯尼亚语 | bs-BA | 立陶宛语 | lt-LT |
| 保加利亚语 | bg-BG | 马其顿语 | mk-MK |
| 保加利亚语(阿罗马尼亚语) | rup-BG | 马来语 | ms-MY |
| 缅甸语 | my-MM | 马拉雅拉姆语 | ml-IN |
| 粤语(繁体) | yue-Hant-HK | 马耳他语 | mt-MT |
| 加泰罗尼亚语 | ca-ES | 普通话(简体) | cmn-Hans-CN |
| 宿务语 | ceb | 马拉地语 | mr-IN |
| 中高棉语 | km-KH | 蒙古语 | mn-MN |
| 克罗地亚语 | hr-HR | 尼泊尔语 | ne-NP |
| 捷克语 | cs-CZ | 挪威语 | nb-NO |
| 丹麦语 | da-DK | 奥里亚语 | or-IN |
| 荷兰语 | nl-NL | 波兰语 | pl-PL |
| 英语(英国) | en-GB | 葡萄牙语(巴西) | pt-BR |
| 英语(印度) | en-IN | 葡萄牙语(葡萄牙) | pt-PT |
| 英语(美国) | en-US | 旁遮普语 | pa-IN |
| 爱沙尼亚语 | et-EE | 旁遮普语(古尔穆基文) | pa-Guru-IN |
| 波斯语 | fa-IR | 罗马尼亚语 | ro-RO |
| 菲律宾人 | fil-PH | 俄语 | ru-RU |
| 芬兰语 | fi-FI | 塞尔维亚语 | sr-RS |
| 法语 | fr-FR | 信德语(阿拉伯文字) | sd-Arab-IN |
| 加利西亚语 | gl-ES | 斯洛伐克语 | sk-SK |
| 格鲁吉亚语 | ka-GE | 斯洛文尼亚语 | sl-SI |
| 德语 | de-DE | 西班牙语(拉丁美洲) | es-419 |
| 希腊语 | el-GR | 西班牙语(美国) | es-US |
| 古吉拉特语 | gu-IN | 斯瓦希里语(肯尼亚) | sw-KE |
| 豪萨语 | ha-NG | 瑞典语 | sv-SE |
| 希伯来语 | he-IL | 塔吉克族 | tg-TJ |
| 印地语 | hi-IN | 泰卢固语 | te-IN |
| 匈牙利语 | hu-HU | 泰语 | th-TH |
| 冰岛语 | is-IS | 土耳其语 | tr-TR |
| 印度语英语 | en-IN | 乌克兰语 | uk-UA |
| 印度尼西亚语 | id-ID | 乌兹别克语 | uz-UZ |
| 意大利语 | it-IT | 越南语 | vi-VN |
参数参考 #
使用以下字段配置实时转录 input_audio_transcription 和 realtime_input_config:
| 参数 | 类型 | 说明 |
|---|---|---|
language_codes | 字符串数组 | BCP-47 语言代码(例如, ["en-US"])。如果省略或为空 ([]),模型自动检测语言并处理多语言语音。 |
custom_vocabulary | 字符串数组 | 最多 1,000 自定义术语、首字母缩略词、品牌名称或专有名词来影响语音识别。 |
mode | 字符串 | 转录模式: "VERBATIM" (默认)或 "SMART" (智能转录)。当设置为 "SMART",该模型删除填充词、格式化列表并纠正不流畅之处。 |
automatic_activity_detection.disabled | 布尔值 | 设置为 true 禁用自动语音活动检测并手动发送 activityStart 和 activityEnd 信号。 |
服务器响应字段 #
| 领域 | 说明 |
|---|---|
server_content.interim_input_transcription | 当用户主动说话时,低延迟、临时部分转录假设连续发出。 |
server_content.input_transcription | 语音回合结束时发出最终的、权威的输入记录。 |
限制 #
- 会话持续时间: 实时转录会话支持长达 10 分钟的连续流式传输。
- 说话人分类: 直播会话中不支持发言人分类。对于说话者分类,请使用非流式 音频转写 端点。
- 字级时间戳: Live API 不支持字级时间戳。 Live API 发出话语级时间戳(
interim_input_transcription和input_transcription). - 自定义词汇: 您最多可以提供 1,000 条款
custom_vocabulary,但通常使用最多 100 项即可获得最佳结果。 - 模式兼容性: 智能转录(
"mode": "SMART") 删除填充词并格式化意图感知文本,但不能与单词注释组合。
后续步骤 #
- 阅读 Gemini 转录文档 对于非流式音频文件。
- 阅读 Live API概述 用于对话语音智能体。
- 阅读 实时翻译指南 用于实时语音到语音翻译。
- 检查 定价页面 Live API 流定价。
- 探索 Live API 功能指南.