音频转写
Gemini API 使用 Gemini 3.5 Transcribe 模型将音频文件中的语音转换为文本(gemini-3.5-transcribe)。基于 Gemini 的音频理解功能,它可以通过自动语言识别、说话人分类、词级时间戳和自定义词汇提示来提供准确的转录。它还提供了一个 智能转录 具有不流畅消除和智能格式化功能的模式。
要转录音频文件,请上传音频并将其传递到 gemini-3.5-transcribe:
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)
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });
const audioFile = await ai.files.upload({
file: "path/to/sample.mp3",
mimeType: "audio/mp3",
});
const response = await ai.models.generateContent({
model: "gemini-3.5-transcribe",
contents: [audioFile],
});
console.log(response.text);
# First upload the file via the Files API, then pass its URI:
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-transcribe:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"parts": [
{
"fileData": {
"fileUri": "YOUR_FILE_URI",
"mimeType": "audio/mp3"
}
}
]
}
]
}'
概览 #
Gemini 3.5 Transcribe 针对语音转文本任务进行了优化。它可以处理不同的口音、背景噪音和多语言对话。
主要能力包括:
- 自动语音识别(ASR): 自动检测跨语言 85+ 区域设置。无需手动配置即可处理句内和句间代码转换。
- 自定义词汇: 通过传递最多 1,000 短语,将识别偏向于特定于域的术语、首字母缩略词和专有名称。
- 说话人分类: 区分多个说话者并将语音片段分配给不同的标签。
- 字级时间戳: 为每个识别的单词生成精确的开始和结束时间偏移。
- 智能转录: 清理不流畅、填充词、重复并应用结构化格式。
- 格式化和规范化: 应用大写、标点符号和反向文本规范化,例如将“2600 万美元”转换为“$26M”。
对于一般音频推理或通过音频内容回答问题,请使用 音频理解。对于文本到语音的音频合成,请使用 文字转语音.
语言检测和提示 #
默认情况下,模型会自动检测口语。当说话者进行语码转换时,它会动态地在语言之间切换。
要使用自动检测,请省略 language_codes 或提供一个空列表:
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=[],
)
),
)
const response = await ai.models.generateContent({
model: "gemini-3.5-transcribe",
contents: [audioFile],
config: {
audioTranscriptionConfig: {
languageCodes: [],
},
},
});
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-transcribe:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"parts": [
{
"fileData": {
"fileUri": "YOUR_FILE_URI",
"mimeType": "audio/mp3"
}
}
]
}
],
"generationConfig": {
"audioTranscriptionConfig": {
"languageCodes": []
}
}
}'
如果您事先知道语言,请在中指定 BCP-47 语言代码 language_codes 提高转录准确性(参见 支持的语言):
config = types.GenerateContentConfig(
audio_transcription_config=types.AudioTranscriptionConfig(
language_codes=["es-ES"],
)
)
const config = {
audioTranscriptionConfig: {
languageCodes: ["es-ES"],
},
};
{
"generationConfig": {
"audioTranscriptionConfig": {
"languageCodes": ["es-ES"]
}
}
}
自定义词汇 #
您可以将语音模型引导至不常见的单词、技术术语、品牌名称或专有名词。供应最多 1,000 条款 custom_vocabulary 数组(通常使用最多 100 项即可获得最佳结果):
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"],
)
),
)
const response = await ai.models.generateContent({
model: "gemini-3.5-transcribe",
contents: [audioFile],
config: {
audioTranscriptionConfig: {
customVocabulary: ["Gemini", "Kubernetes", "BigQuery"],
},
},
});
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-transcribe:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"parts": [
{
"fileData": {
"fileUri": "YOUR_FILE_URI",
"mimeType": "audio/mp3"
}
}
]
}
],
"generationConfig": {
"audioTranscriptionConfig": {
"customVocabulary": ["Gemini", "Kubernetes", "BigQuery"]
}
}
}'
说话人分类 #
说话人分类可识别录音中的不同声音,并用说话人标识符标记每个片段,例如 spk_1 或 spk_2。最多支持 8 扬声器(3 或更多扬声器的归属尚处于试验阶段)。
通过设置启用二值化 diarization 到 True:
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,
)
),
)
const response = await ai.models.generateContent({
model: "gemini-3.5-transcribe",
contents: [audioFile],
config: {
audioTranscriptionConfig: {
diarization: true,
},
},
});
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-transcribe:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"parts": [
{
"fileData": {
"fileUri": "YOUR_FILE_URI",
"mimeType": "audio/mp3"
}
}
]
}
],
"generationConfig": {
"audioTranscriptionConfig": {
"diarization": true
}
}
}'
字级时间戳 #
字级时间戳为音频流中每个已识别的字提供准确的开始和结束偏移量。
通过设置启用时间戳 word_timestamp 到 True:
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,
)
),
)
const response = await ai.models.generateContent({
model: "gemini-3.5-transcribe",
contents: [audioFile],
config: {
audioTranscriptionConfig: {
wordTimestamp: true,
},
},
});
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-transcribe:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"parts": [
{
"fileData": {
"fileUri": "YOUR_FILE_URI",
"mimeType": "audio/mp3"
}
}
]
}
],
"generationConfig": {
"audioTranscriptionConfig": {
"wordTimestamp": true
}
}
}'
你可以结合 diarization 和 word_timestamp 在单个请求中接收说话者标签和单词时间戳:
config = types.GenerateContentConfig(
audio_transcription_config=types.AudioTranscriptionConfig(
diarization=True,
word_timestamp=True,
)
)
const config = {
audioTranscriptionConfig: {
diarization: true,
wordTimestamp: true,
},
};
{
"generationConfig": {
"audioTranscriptionConfig": {
"diarization": true,
"wordTimestamp": true
}
}
}
转录模式 #
Gemini 3.5 Transcribe 支持两种转录模式 mode 参数:
VERBATIM(默认):返回所有所说内容的精确逐字记录,保留原始填充词(“嗯”、“呃”、“喜欢”、“你知道”)、重复、停顿和错误的开头。使用时间戳或说话人分类时需要。SMART(智能转录):通过应用智能后处理优化阅读文字记录:* 消除不流畅:去除会话填充词、口吃和错误的开头。- 内联自我更正:直接解决口头更正(例如, “我们周二见面吧,其实不,周三两点见面” 变成 “我们周三在 2:00 PM 见面”).
- 自动结构化格式化:自动将口头想法构建为段落、编号列表、项目符号、格式化日期、货币和数字。
- 语法清理:应用自然标点符号、句子大小写和流程。
语音音频 |
|
|
|---|---|---|
“嗯,所以对于这次会议,我认为我们应该,呃,邀请爱丽丝,等等,鲍勃和卡罗尔。” | “嗯,所以对于这次会议,我认为我们应该呃邀请爱丽丝,不要等待鲍勃和卡罗尔。” | “对于这次会议,我认为我们应该邀请鲍勃和卡罗尔。” |
“第一项审查预算第二项最终确定时间表第三项发送回顾” | “第一项审查预算第二项最终确定时间表第三项发送回顾” |
|
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)
const response = await ai.models.generateContent({
model: "gemini-3.5-transcribe",
contents: [audioFile],
config: {
audioTranscriptionConfig: {
mode: "SMART",
},
},
});
console.log(response.text);
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-transcribe:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"parts": [
{
"fileData": {
"fileUri": "YOUR_FILE_URI",
"mimeType": "audio/mp3"
}
}
]
}
],
"generationConfig": {
"audioTranscriptionConfig": {
"mode": "SMART"
}
}
}'
解析转录输出 #
完整的转录文本返回于 response.text.
当 word_timestamp 或 diarization 启用后,API 还会返回附加到候选部件的详细单词级注释和说话人标签。
以下是提取和迭代单词时间戳和发言者轮流的方法:
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']}")
function extractWordTranscriptions(response) {
const words = [];
for (const candidate of response.candidates ?? []) {
for (const part of candidate.content?.parts ?? []) {
const transcription = part.audioTranscription;
if (transcription) {
const speaker = transcription.speakerLabel ?? "";
for (const wordInfo of transcription.words ?? []) {
words.push({
word: wordInfo.word ?? "",
speaker: speaker,
startOffset: wordInfo.startOffset ?? "",
endOffset: wordInfo.endOffset ?? "",
});
}
}
}
}
return words;
}
const words = extractWordTranscriptions(response);
for (const w of words) {
const speaker = w.speaker ? `[${w.speaker}] ` : "";
const timing = (w.startOffset && w.endOffset) ? `(${w.startOffset} -> ${w.endOffset}) ` : "";
console.log(`${speaker}${timing}${w.word}`);
}
{
"candidates": [
{
"content": {
"parts": [
{
"audioTranscription": {
"speakerLabel": "spk_1",
"words": [
{
"word": "Hello",
"startOffset": "0.100s",
"endOffset": "0.400s"
},
{
"word": "world",
"startOffset": "0.500s",
"endOffset": "0.800s"
}
]
}
}
],
"role": "model"
},
"finishReason": "STOP"
}
]
}
支持的语言 #
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.