Gemini 中文指南
获取 API 密钥 ↗

音频转写

↓ 下载 Markdown

Gemini API 使用 Gemini 3.5 Transcribe 模型将音频文件中的语音转换为文本(gemini-3.5-transcribe)。基于 Gemini 的音频理解功能,它可以通过自动语言识别、说话人分类、词级时间戳和自定义词汇提示来提供准确的转录。它还提供了一个 智能转录 具有不流畅消除和智能格式化功能的模式。

要转录音频文件,请上传音频并将其传递到 gemini-3.5-transcribe:

python
from google import genai

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

audio_file = client.files.upload(file="path/to/sample.mp3")

response = client.models.generate_content(
    model="gemini-3.5-transcribe",
    contents=[audio_file],
)

print(response.text)

概览 #

Gemini 3.5 Transcribe 针对语音转文本任务进行了优化。它可以处理不同的口音、背景噪音和多语言对话。

主要能力包括:

  • 自动语音识别(ASR): 自动检测跨语言 85+ 区域设置。无需手动配置即可处理句内和句间代码转换。
  • 自定义词汇: 通过传递最多 1,000 短语,将识别偏向于特定于域的术语、首字母缩略词和专有名称。
  • 说话人分类: 区分多个说话者并将语音片段分配给不同的标签。
  • 字级时间戳: 为每个识别的单词生成精确的开始和结束时间偏移。
  • 智能转录: 清理不流畅、填充词、重复并应用结构化格式。
  • 格式化和规范化: 应用大写、标点符号和反向文本规范化,例如将“2600 万美元”转换为“$26M”。

对于一般音频推理或通过音频内容回答问题,请使用 音频理解。对于文本到语音的音频合成,请使用 文字转语音.

语言检测和提示 #

默认情况下,模型会自动检测口语。当说话者进行语码转换时,它会动态地在语言之间切换。

要使用自动检测,请省略 language_codes 或提供一个空列表:

python
from google import genai
from google.genai import types

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

response = client.models.generate_content(
    model="gemini-3.5-transcribe",
    contents=[audio_file],
    config=types.GenerateContentConfig(
        audio_transcription_config=types.AudioTranscriptionConfig(
            language_codes=[],
        )
    ),
)

如果您事先知道语言,请在中指定 BCP-47 语言代码 language_codes 提高转录准确性(参见 支持的语言):

python
config = types.GenerateContentConfig(
    audio_transcription_config=types.AudioTranscriptionConfig(
        language_codes=["es-ES"],
    )
)

自定义词汇 #

您可以将语音模型引导至不常见的单词、技术术语、品牌名称或专有名词。供应最多 1,000 条款 custom_vocabulary 数组(通常使用最多 100 项即可获得最佳结果):

python
from google import genai
from google.genai import types

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

response = client.models.generate_content(
    model="gemini-3.5-transcribe",
    contents=[audio_file],
    config=types.GenerateContentConfig(
        audio_transcription_config=types.AudioTranscriptionConfig(
            custom_vocabulary=["Gemini", "Kubernetes", "BigQuery"],
        )
    ),
)

说话人分类 #

说话人分类可识别录音中的不同声音,并用说话人标识符标记每个片段,例如 spk_1 或 spk_2。最多支持 8 扬声器(3 或更多扬声器的归属尚处于试验阶段)。

通过设置启用二值化 diarization 到 True:

python
from google import genai
from google.genai import types

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

response = client.models.generate_content(
    model="gemini-3.5-transcribe",
    contents=[audio_file],
    config=types.GenerateContentConfig(
        audio_transcription_config=types.AudioTranscriptionConfig(
            diarization=True,
        )
    ),
)

字级时间戳 #

字级时间戳为音频流中每个已识别的字提供准确的开始和结束偏移量。

通过设置启用时间戳 word_timestamp 到 True:

python
from google import genai
from google.genai import types

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

response = client.models.generate_content(
    model="gemini-3.5-transcribe",
    contents=[audio_file],
    config=types.GenerateContentConfig(
        audio_transcription_config=types.AudioTranscriptionConfig(
            word_timestamp=True,
        )
    ),
)

你可以结合 diarization 和 word_timestamp 在单个请求中接收说话者标签和单词时间戳:

python
config = types.GenerateContentConfig(
    audio_transcription_config=types.AudioTranscriptionConfig(
        diarization=True,
        word_timestamp=True,
    )
)

转录模式 #

Gemini 3.5 Transcribe 支持两种转录模式 mode 参数:

  • VERBATIM (默认):返回所有所说内容的精确逐字记录,保留原始填充词(“嗯”、“呃”、“喜欢”、“你知道”)、重复、停顿和错误的开头。使用时间戳或说话人分类时需要。
  • SMART (智能转录):通过应用智能后处理优化阅读文字记录:* 消除不流畅:去除会话填充词、口吃和错误的开头。
  • 内联自我更正:直接解决口头更正(例如, “我们周二见面吧,其实不,周三两点见面” 变成 “我们周三在 2:00 PM 见面”).
  • 自动结构化格式化:自动将口头想法构建为段落、编号列表、项目符号、格式化日期、货币和数字。
  • 语法清理:应用自然标点符号、句子大小写和流程。

语音音频

VERBATIM 输出

SMART (智能转录)输出

“嗯,所以对于这次会议,我认为我们应该,呃,邀请爱丽丝,等等,鲍勃和卡罗尔。”

“嗯,所以对于这次会议,我认为我们应该呃邀请爱丽丝,不要等待鲍勃和卡罗尔。”

“对于这次会议,我认为我们应该邀请鲍勃和卡罗尔。”

“第一项审查预算第二项最终确定时间表第三项发送回顾”

“第一项审查预算第二项最终确定时间表第三项发送回顾”

  1. 审查预算
  2. 最终确定时间表
  3. 发送回顾
python
from google import genai
from google.genai import types

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

response = client.models.generate_content(
    model="gemini-3.5-transcribe",
    contents=[audio_file],
    config=types.GenerateContentConfig(
        audio_transcription_config=types.AudioTranscriptionConfig(
            mode="SMART",
        )
    ),
)
print(response.text)

解析转录输出 #

完整的转录文本返回于 response.text.

当 word_timestamp 或 diarization 启用后,API 还会返回附加到候选部件的详细单词级注释和说话人标签。

以下是提取和迭代单词时间戳和发言者轮流的方法:

python
def extract_word_transcriptions(response):
    words = []
    for candidate in getattr(response, "candidates", []) or []:
        content = getattr(candidate, "content", None)
        for part in getattr(content, "parts", []) or []:
            transcription = getattr(part, "audio_transcription", None)
            if transcription:
                speaker = getattr(transcription, "speaker_label", "")
                for word_info in getattr(transcription, "words", []) or []:
                    word = getattr(word_info, "word", "")
                    start = getattr(word_info, "start_offset", "")
                    end = getattr(word_info, "end_offset", "")
                    words.append({
                        "word": word,
                        "speaker": speaker,
                        "start_offset": start,
                        "end_offset": end,
                    })
    return words

words = extract_word_transcriptions(response)

for w in words:
    speaker = f"[{w['speaker']}] " if w["speaker"] else ""
    timing = f"({w['start_offset']} -> {w['end_offset']}) " if w["start_offset"] and w["end_offset"] else ""
    print(f"{speaker}{timing}{w['word']}")

支持的语言 #

Gemini 3.5 Transcribe 支持以下语言和 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

支持的音频格式 #

Gemini 3.5 Transcribe 支持以下音频格式 MIME 类型:

  • 音频- audio/wav
  • MP3- audio/mp3
  • 亚洲国际电影节- audio/aiff
  • AA- audio/aac
  • 奥格- audio/ogg
  • FLAC- audio/flac
  • MPEG- audio/mpeg
  • M4A - audio/m4a
  • L16 - audio/l16
  • 作品- audio/opus
  • 法律- audio/alaw
  • 穆洛 - audio/mulaw
  • 网络M- audio/webm

有关支持的 MIME 类型和参数架构的完整列表,请参阅 Interactions API参考.

参数参考 #

通过设置内的字段来配置转录 audio_transcription_config 对象在 GenerateContentConfig:

领域类型说明
language_codes字符串数组BCP-47 语言代码(例如, ["en-US"])。如果省略或为空 ([]),模型自动检测语言并处理代码切换。
custom_vocabulary字符串数组最多 1,000 自定义术语、首字母缩写词或专有名称,以影响语音识别。与说话者分类和字级时间戳不兼容。
word_timestamp布尔值设置为 True 包括单词开始和结束偏移量。如果省略或 False,不返回单词时间戳。与自定义词汇不兼容。
diarization布尔值设置为 True 识别并标记不同的说话者。与自定义词汇不兼容。
mode字符串转录模式。支持的值: "VERBATIM" (默认)和 "SMART"。与时间戳和二值化不兼容。

最佳实践 #

  • 提供干净的音频: 确保录音具有清晰的语音分离并避免严重的削波。
  • 已知时提供语言提示: 如果您事先知道音频语言,请指定 language_codes 以最大限度地提高准确性。
  • 目标自定义词汇: 仅包含不同的领域术语、品牌名称或专有名词 custom_vocabulary 而不是常见的日常用语。
  • 选择正确的文件输入方式: 上传本地录音 client.files.upload,或者通过传递跳过上传步骤 外部 HTTP 或签名 URL (高达 15 MB), 已注册 Google Cloud 存储 URI (最高至 2 GB),或 内联 Base64 音频。参见 文件输入方式 了解详情。

限制 #

  • 音频时长: 标准一元请求支持长达 1 小时的音频文件。当启用扬声器分类或字级时间戳等功能时,音频处理仅限于 30 分钟。超过这些限制的音频将被截断,同时仍返回完整的响应,因此在发送请求之前将较长的录音分割成 30 分钟或更短的块。
  • 字级时间戳: 启用单词级时间戳可能会降低整体转录准确性。
  • 说话人分类: 扬声器分类最多支持 8 扬声器。 3 或更多扬声器的扬声器归属是实验性的。
  • 自定义词汇: 您最多可以提供 1,000 条款 custom_vocabulary,但通常使用最多 100 项即可获得最佳结果。你不能合并 custom_vocabulary 具有说话者分类或单词级时间戳; API 拒绝指定的请求 custom_vocabulary 与任一功能一起。
  • 模式兼容性: 智能转录(mode: "SMART") 不能与 word_timestamp 或 diarization.

后续步骤 #

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