音频转写

Gemini API 使用 Gemini 3.5 Transcribe 模型 (gemini-3.5-transcribe) 将音频文件中的语音转换为文本。凭借 Gemini 的音频理解能力，该 API 可提供准确的转写内容，并支持自动语言识别、说话人日志记录、字级时间戳和自定义词汇提示。它还提供智能转写模式，可移除口语中的不流畅之处并进行智能格式设置。

如需转写音频文件，请上传音频并将其传递给 gemini-3.5-transcribe：

Python

from google import genai

client = genai.Client()

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

interaction = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[
        {
            "type": "audio",
            "uri": audio_file.uri,
            "mime_type": audio_file.mime_type,
        }
    ],
)

print(interaction.output_text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const audioFile = await client.files.upload({
  file: "path/to/sample.mp3",
  config: { mime_type: "audio/mp3" },
});

const interaction = await client.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [
    {
      type: "audio",
      uri: audioFile.uri,
      mime_type: audioFile.mimeType,
    },
  ],
});

console.log(interaction.output_text);

REST

# First upload the file via the Files API, then pass its URI:
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-transcribe",
    "input": [
      {
        "type": "audio",
        "uri": "YOUR_FILE_URI",
        "mime_type": "audio/mp3"
      }
    ]
  }'

概览

Gemini 3.5 Transcribe 针对语音转文字任务进行了优化。它可以处理各种口音、背景噪声和多语言对话。

主要功能包括：

  • 自动语音识别 (ASR)：自动检测 85 多种语言区域设置。无需手动配置即可处理句内和句间语码转换。
  • 自定义词汇：通过传递最多 1,000 个短语，使识别偏向于特定领域的术语、缩写和专有名词。
  • 说话人日志：区分多个说话人，并将说话片段归因于不同的标签。
  • 字词级时间戳：为每个识别出的字词生成精确的开始和结束时间偏移值。
  • 智能转写：清理口误、填充词、重复内容，并应用结构化格式。
  • 格式设置和归一化：应用大小写、标点和逆文本归一化，例如将“2600 万美元”转换为“2600 万美元”。

如需对音频内容进行一般性音频推理或问答，请使用音频理解。如需进行文字转语音音频合成，请使用 Text-to-speech。

语言检测和提示

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

如需使用自动检测，请省略 language_codes 或提供一个空列表：

Python

interaction = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[
        {
            "type": "audio",
            "uri": audio_file.uri,
            "mime_type": audio_file.mime_type,
        }
    ],
    generation_config={
        "transcription_config": {
            "language_codes": [],
        }
    },
)

JavaScript

const interaction = await client.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [
    {
      type: "audio",
      uri: audioFile.uri,
      mime_type: audioFile.mimeType,
    },
  ],
  generation_config: {
    transcription_config: {
      language_codes: [],
    },
  },
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-transcribe",
    "input": [
      {
        "type": "audio",
        "uri": "YOUR_FILE_URI",
        "mime_type": "audio/mp3"
      }
    ],
    "generation_config": {
      "transcription_config": {
        "language_codes": []
      }
    }
  }'

如果您提前知道语言，请在 language_codes 中指定 BCP-47 语言代码，以提高转写准确率（请参阅支持的语言）：

Python

generation_config = {
    "transcription_config": {
        "language_codes": ["es-ES"],
    }
}

JavaScript

const generationConfig = {
  transcription_config: {
    language_codes: ["es-ES"],
  },
};

REST

{
  "generation_config": {
    "transcription_config": {
      "language_codes": ["es-ES"]
    }
  }
}

自定义词汇

您可以引导语音模型识别不常见的字词、技术术语、品牌名称或专有名词。在 custom_vocabulary 数组中提供最多 1,000 个字词（通常最多提供 100 个字词可获得最佳效果）：

Python

interaction = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[
        {
            "type": "audio",
            "uri": audio_file.uri,
            "mime_type": audio_file.mime_type,
        }
    ],
    generation_config={
        "transcription_config": {
            "custom_vocabulary": ["Gemini", "Kubernetes", "BigQuery"],
        }
    },
)

JavaScript

const interaction = await client.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [
    {
      type: "audio",
      uri: audioFile.uri,
      mime_type: audioFile.mimeType,
    },
  ],
  generation_config: {
    transcription_config: {
      custom_vocabulary: ["Gemini", "Kubernetes", "BigQuery"],
    },
  },
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-transcribe",
    "input": [
      {
        "type": "audio",
        "uri": "YOUR_FILE_URI",
        "mime_type": "audio/mp3"
      }
    ],
    "generation_config": {
      "transcription_config": {
        "custom_vocabulary": ["Gemini", "Kubernetes", "BigQuery"]
      }
    }
  }'

讲话人区分

讲话人区分功能可识别录音中的不同语音，并为每个片段添加讲话人标识符（例如 spk_1 或 spk_2）。最多支持 8 位发言者（3 位或更多发言者的归因功能处于实验阶段）。

通过在 mode 中配置 diarization_mode 来启用区分：

Python

interaction = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[
        {
            "type": "audio",
            "uri": audio_file.uri,
            "mime_type": audio_file.mime_type,
        }
    ],
    generation_config={
        "transcription_config": {
            "mode": {
                "type": "verbatim",
                "diarization_mode": "speaker",
            },
        }
    },
)

JavaScript

const interaction = await client.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [
    {
      type: "audio",
      uri: audioFile.uri,
      mime_type: audioFile.mimeType,
    },
  ],
  generation_config: {
    transcription_config: {
      mode: {
        type: "verbatim",
        diarization_mode: "speaker",
      },
    },
  },
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-transcribe",
    "input": [
      {
        "type": "audio",
        "uri": "YOUR_FILE_URI",
        "mime_type": "audio/mp3"
      }
    ],
    "generation_config": {
      "transcription_config": {
        "mode": {
          "type": "verbatim",
          "diarization_mode": "speaker"
        }
      }
    }
  }'

字词级时间戳

字词级时间戳可为音频串流中识别出的每个字词提供确切的开始和结束偏移值。

通过在 mode 中配置 timestamp_granularities 来启用时间戳：

Python

interaction = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[
        {
            "type": "audio",
            "uri": audio_file.uri,
            "mime_type": audio_file.mime_type,
        }
    ],
    generation_config={
        "transcription_config": {
            "mode": {
                "type": "verbatim",
                "timestamp_granularities": ["word"],
            },
        }
    },
)

JavaScript

const interaction = await client.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [
    {
      type: "audio",
      uri: audioFile.uri,
      mime_type: audioFile.mimeType,
    },
  ],
  generation_config: {
    transcription_config: {
      mode: {
        type: "verbatim",
        timestamp_granularities: ["word"],
      },
    },
  },
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-transcribe",
    "input": [
      {
        "type": "audio",
        "uri": "YOUR_FILE_URI",
        "mime_type": "audio/mp3"
      }
    ],
    "generation_config": {
      "transcription_config": {
        "mode": {
          "type": "verbatim",
          "timestamp_granularities": ["word"]
        }
      }
    }
  }'

您可以在 mode 中结合使用 diarization_mode 和 timestamp_granularities，以同时接收说话人标签和字词时间戳：

Python

generation_config = {
    "transcription_config": {
        "custom_vocabulary": ["Gemini"],
        "mode": {
            "type": "verbatim",
            "diarization_mode": "speaker",
            "timestamp_granularities": ["word"],
        },
    }
}

JavaScript

const generationConfig = {
  transcription_config: {
    custom_vocabulary: ["Gemini"],
    mode: {
      type: "verbatim",
      diarization_mode: "speaker",
      timestamp_granularities: ["word"],
    },
  },
};

REST

{
  "generation_config": {
    "transcription_config": {
      "custom_vocabulary": ["Gemini"],
      "mode": {
        "type": "verbatim",
        "diarization_mode": "speaker",
        "timestamp_granularities": ["word"]
      }
    }
  }
}

转写模式

Gemini 3.5 Transcribe 通过 mode 参数支持两种转写模式：

  • verbatim（默认）：返回所有语音内容的逐字逐句的转写，保留原始的填充词（“嗯”“呃”“像”“你知道”）、重复、停顿和错误开头。在此模式 ({"type": "verbatim", ...}) 下，系统会配置时间戳和讲话人区分。
  • smart（智能转写）：通过应用智能后处理来优化转写内容，以便于阅读：
    • 去除口语障碍：去除对话中的填充词、口吃和误启动。
    • 内嵌自我修正：直接解决语音修正问题（例如，“我们周二见面吧，不，周三下午两点”会变成“我们周三下午两点见面吧”）。
    • 自动结构化格式：自动将语音中的想法整理成段落、编号列表、项目符号、格式化日期、货币和数字。
    • 语法清理：应用自然的标点符号、句子大小写和流畅度。
朗读音频 verbatim 输出 smart（智能转写）输出
“嗯，关于会议，我觉得我们应该邀请 Alice 和，等等，是 Bob 和 Carol。” “嗯，所以对于会议，我认为我们应该邀请 Alice，等等，不，是 Bob 和 Carol。” “我认为我们应该邀请 Bob 和 Carol 参加这次会议。”
“First item review budget second item finalize timeline third item send recap” “first item review budget second item finalize timeline third item send recap” “1. 查看预算
2. 确定时间轴
3. 发送总结”

Python

interaction = client.interactions.create(
    model="gemini-3.5-transcribe",
    input=[
        {
            "type": "audio",
            "uri": audio_file.uri,
            "mime_type": audio_file.mime_type,
        }
    ],
    generation_config={
        "transcription_config": {
            "mode": "smart",
        }
    },
)
print(interaction.output_text)

JavaScript

const interaction = await client.interactions.create({
  model: "gemini-3.5-transcribe",
  input: [
    {
      type: "audio",
      uri: audioFile.uri,
      mime_type: audioFile.mimeType,
    },
  ],
  generation_config: {
    transcription_config: {
      mode: "smart",
    },
  },
});
console.log(interaction.output_text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-transcribe",
    "input": [
      {
        "type": "audio",
        "uri": "YOUR_FILE_URI",
        "mime_type": "audio/mp3"
      }
    ],
    "generation_config": {
      "transcription_config": {
        "mode": "smart"
      }
    }
  }'

解析转写输出

完整的转写文本会返回到 interaction.output_text 中。

启用 timestamp_granularities 或 diarization_mode 后，该 API 还会返回附加到互动内容的详细字词级注释。

以下代码展示了如何提取字词时间戳和发言者轮换并对其进行迭代：

Python

def extract_word_annotations(interaction):
    words = []
    for step in getattr(interaction, "steps", []) or []:
        for content in getattr(step, "content", []) or []:
            for annotation in getattr(content, "annotations", []) or []:
                if getattr(annotation, "type", None) == "word_info":
                    words.append(annotation)
    return words

words = extract_word_annotations(interaction)

for w in words:
    speaker = f"[{w.speaker}] " if getattr(w, "speaker", None) else ""
    start = getattr(w, "start_offset", "")
    end = getattr(w, "end_offset", "")
    timing = f"({start} -> {end}) " if start and end else ""
    print(f"{speaker}{timing}{w.text}")

JavaScript

function extractWordAnnotations(interaction) {
  const words = [];
  for (const step of interaction.steps ?? []) {
    for (const content of step.content ?? []) {
      for (const annotation of content.annotations ?? []) {
        if (annotation.type === "word_info") {
          words.push(annotation);
        }
      }
    }
  }
  return words;
}

const words = extractWordAnnotations(interaction);

for (const w of words) {
  const speaker = w.speaker ? `[${w.speaker}] ` : "";
  const timing = (w.start_offset && w.end_offset) ? `(${w.start_offset} -> ${w.end_offset}) ` : "";
  console.log(`${speaker}${timing}${w.text}`);
}

REST

{
  "id": "interactions/abc123xyz",
  "status": "completed",
  "steps": [
    {
      "id": "step_001",
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Hello world",
          "annotations": [
            {
              "type": "word_info",
              "text": "Hello",
              "speaker": "spk_1",
              "start_offset": "0.100s",
              "end_offset": "0.450s"
            },
            {
              "type": "word_info",
              "text": "world",
              "speaker": "spk_1",
              "start_offset": "0.500s",
              "end_offset": "0.850s"
            }
          ]
        }
      ]
    }
  ]
}

支持的语言

Gemini 3.5 Transcribe 支持以下语言和 BCP-47 语言代码：

语言 BCP-47 代码 语言 BCP-47 代码
南非荷兰语 af-ZA 日语 ja-JP
阿姆哈拉语 am-ET 爪哇语 jv-ID
阿拉伯语（埃及） ar-EG Kabuverdianu 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

参数参考

通过在 generation_config 中设置 transcription_config 对象内的字段来配置转写：

字段 类型 说明
language_codes 字符串数组 BCP-47 语言代码（例如 ["en-US"]）。如果省略或为空 ([])，模型会自动检测语言并处理代码切换。
custom_vocabulary 字符串数组 最多可添加 1,000 个自定义术语、缩写或专有名词，以使语音识别偏向于这些词汇。
mode 对象或字符串 转写模式配置。接受 "smart" 或逐字转写模式对象 ({"type": "verbatim", ...})。默认为逐字转写。
mode.type 字符串 （仅限逐字模式）模式标识符。始终设置为 "verbatim"。
mode.timestamp_granularities 字符串数组 （仅限逐字模式）要返回的时间戳的粒度。传递 ["word"] 以启用字词开始和结束偏移值。
mode.diarization_mode 字符串 （仅限逐字模式）区分说话人模式。传递 "speaker" 以识别和标记不同的说话者。

最佳做法

  • 提供清晰的音频：确保音频录制具有清晰的人声分离度，并避免严重剪辑。
  • 在已知音频语言的情况下提供语言提示：如果您提前知道音频语言，请指定 language_codes 以尽可能提高准确性。
  • 以自定义词汇为目标：在 custom_vocabulary 中仅包含独特的领域术语、品牌名称或专有名词，而不是常见的日常用语。
  • 针对大型录制文件使用 Files API：对于时长超过几秒的文件，请使用 client.files.upload 上传文件，并将返回的文件 URI 传递给模型。

限制

  • 音频时长：标准一元请求支持时长不超过 1 小时的音频文件。启用讲话人区分或字词级时间戳等功能时，音频处理时长上限为 30 分钟。
  • 字词级时间戳：启用字词级时间戳可能会降低整体转写准确度。
  • 讲话人区分：讲话人区分功能最多支持 8 位讲话人。针对 3 个或更多发言者的发言者归因功能目前处于实验阶段。
  • 自定义词汇：您可以在 custom_vocabulary 中提供最多 1,000 个字词，但通常最多 100 个字词就能获得最佳效果。
  • 模式兼容性：智能转写 ("smart") 不能与 timestamp_granularities 或 diarization_mode 结合使用。

后续步骤

  • 使用 Live API 通过实时转写指南实时传输音频。
  • 探索音频理解功能，分析、总结或查询音频内容。
  • 了解如何使用 Text-to-speech 将文字合成为音频。
  • 如需了解模型价格和令牌限制，请参阅价格页面。
  • 如需详细了解如何上传和管理媒体文件，请参阅 Files API 指南。