Gemini 3.5 Transcribe API 指南：预录转写、实时字幕与验证方法

Gemini 3.5 Transcribe 是 Google 在 2026 年 8 月 26 日发布的专用语音转文字模型。它不是 gemini-3.5-flash 的别名，也不是会说话的 Live Agent。接入前先按输入形态选路线：已有录音文件用 gemini-3.5-transcribe，麦克风或实时音频流用 gemini-3.5-transcribe-live。

两条路线都处于 public preview。前者通过 Files API 上传音频，再调用 Interactions API；后者通过 Live API 建立双向流式连接。选择错误不只是延迟不同，还会影响输入格式、最长时长、说话人标注、逐词时间戳和事件处理方式。

这些能力和限制来自当前 Gemini 3.5 Transcribe 模型页。如果你的产品同时需要“先转写，再总结或调用工具”，应把转写和后续推理拆成两个明确步骤，分别记录输入、输出和失败状态。

先跑通预录音频转写

下面的 Python 示例沿用 Google 当前的 Audio transcription 官方指南。先安装或更新 SDK，并通过环境变量提供 API key：

bash
python -m pip install -U google-genai
export GEMINI_API_KEY="YOUR_API_KEY"

不要把真实 key 写进仓库、前端代码或公开日志。随后上传音频，并把 Files API 返回的 URI 交给 Interactions API：

python
from google import genai

client = genai.Client()

audio_file = client.files.upload(file="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)

第一次运行只验证四件事：文件上传成功、请求状态完成、output_text 非空、输出确实对应输入音频。不要一开始就同时加语言提示、自定义词汇、说话人标注和时间戳；否则失败时很难判断是基础调用、参数组合还是音频本身的问题。

smart 和 verbatim 不是同一种结果

默认的 verbatim 尽量保留口头语、重复和自我纠正，适合审计、质检、字幕对齐或后续人工编辑。smart 会移除填充词、处理口误和自我纠正，并把数字、日期、列表和段落整理得更适合阅读。

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": "smart"},
            "language_codes": ["cmn-Hans-CN"],
            "custom_vocabulary": [
                "Gemini 3.5 Transcribe",
                "Interactions API",
                "LaoZhang AI",
            ],
        }
    },
)

print(interaction.output_text)

简体普通话在当前支持列表里的代码是 cmn-Hans-CN，不是常见但不对应此表的 zh-CN。如果音频会在中英文之间切换，可以省略 language_codes 或传空数组，让模型自动识别。custom_vocabulary 最多可传 1,000 个词，但 Google 的模型页提示通常在 100 个以内效果更好；优先放产品名、人名、缩写、订单号模式和行业术语，不要把整份词典塞进去。

最重要的参数边界是：smart 不能与 timestamp_granularities 或 diarization_mode 同时使用。 如果需要逐词时间戳或区分说话人，应改回 verbatim：

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", "BigQuery"],
            "mode": {
                "type": "verbatim",
                "diarization_mode": "speaker",
                "timestamp_granularities": ["word"],
            },
        }
    },
)

print(interaction.output_text)

output_text 只是合并后的完整文本。开启时间戳或说话人标注后，逐词信息位于 interaction 的 content annotations 中；如果你的下游要生成 SRT、定位录音片段或统计各说话人时长，就必须解析 annotations，而不能只保存 output_text。

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


for word in extract_word_annotations(interaction):
    speaker = getattr(word, "speaker", None) or "unknown"
    start = getattr(word, "start_offset", "")
    end = getattr(word, "end_offset", "")
    print(speaker, start, end, word.text)

当前详细模型页写的是最多 8 位说话人，同时明确 3 位以上仍属 experimental；发布文章则只突出 up to three speakers。生产设计应采用更保守的边界：三人以上会议必须拿真实样本验证，不要把“支持最多 8 人”当作稳定的分离质量保证。

实时字幕要处理的是流，不是文件

实时路线使用 gemini-3.5-transcribe-live。虽然它与 Live Agent 都建立双向连接，但两者的输出目标不同：Live Agent 负责听、推理和说话；Live Transcription 负责连续接收音频并返回文字。Google 的 Live transcription 指南 当前要求发送 raw 16-bit PCM 音频，推荐 16 kHz、单声道、little-endian，并以约 100 ms 的小块持续发送。

下面展示连接与接收事件的最小骨架，音频采集部分应由你的麦克风、媒体服务器或通话基础设施提供：

python
import asyncio
from google import genai
from google.genai import types

client = genai.Client()

config = types.LiveConnectConfig(
    response_modalities=["TEXT"],
    input_audio_transcription=types.AudioTranscriptionConfig(
        language_codes=[],
        custom_vocabulary=["Gemini", "LaoZhang AI"],
    ),
)


async def receive_transcripts(session):
    async for response in session.receive():
        content = response.server_content
        if content and content.input_transcription:
            print("FINAL:", content.input_transcription.text)


async def main():
    async with client.aio.live.connect(
        model="gemini-3.5-transcribe-live",
        config=config,
    ) as session:
        receiver = asyncio.create_task(receive_transcripts(session))

        async for audio_chunk in your_pcm_chunk_source():
            await session.send_realtime_input(
                audio=types.Blob(
                    data=audio_chunk,
                    mime_type="audio/pcm;rate=16000",
                )
            )

        await session.send_realtime_input(audio_stream_end=True)
        await receiver


asyncio.run(main())

your_pcm_chunk_source() 是刻意保留的应用边界，不是 SDK 自带函数。浏览器麦克风通常产生 WebM、Opus 或 Web Audio 数据，电话系统也可能是 8 kHz μ-law；它们都不能在没有解码、重采样和声道处理的情况下冒充 16 kHz PCM。

实时 UI 还要区分 interim 与 final。中间结果适合覆盖当前字幕预览，最终结果才追加到已提交的 transcript。若把每次 interim 都持久化，用户会看到重复和回滚后的文本。当前 Live 路线也不提供说话人标注或逐词时间戳；如果业务必须得到这些结构，应录制音频后再走预录模型，而不是从实时事件中猜。

限制会直接改变架构

这些不是“以后再优化”的细节。超过 30 分钟的多人录音需要切分并设计跨片段说话人合并；超过 10 分钟的实时产品需要处理 session 轮换、连接恢复和 transcript 去重；需要后续总结、实体抽取或工具调用时，应把最终 transcript 交给另一个合适模型。

成本很低，但不要忽略输出和重试

截至 2026 年 8 月 27 日，Google Gemini Developer API 定价页 给出的估算是：

• 预录 Transcribe：音频输入约 $0.003/min，文本输出约 $0.002/min，合计约 $0.005/min；
• Live Transcribe：音频输入约 $0.005/min，文本输出约 $0.004/min，合计约 $0.009/min。

这是根据 Google 假设的音频与文本 token 速率得到的 blended estimate，账单仍按实际 token 消耗。按估算，100 小时预录音频约 $30，100 小时实时音频约 $54，还没有包括失败重试、音频存储、转码、媒体服务器、后续摘要模型和人工抽检。

免费层当前显示输入和输出免费，但定价页也标明免费层数据会用于改进 Google 产品，付费层则标为不会。涉及客户通话、内部会议、医疗、法律、财务或其他敏感录音时，不要因为“免费”就直接上传；先核对当前条款、地区要求、同意流程、保留策略和组织的数据治理规则。需要进一步理解账户、地区和结算边界，可查看站内的 Gemini API Key 价格与安全路径。

用自己的金标音频验收，而不是只看 WER 新闻

Google 的发布文章引用 Artificial Analysis 数据，报告平均 WER 为实时 4.0%、非实时 2.6%，并称相较 Chirp 3 的 final transcription 时间改善 70%。这些是 Google 引用或报告的结果，不是本站在你的语言、口音、噪声、设备和术语上完成的实测。

更可靠的上线门槛是建立一小套自己的金标：

1. 选取 20–50 段真实分布的音频，覆盖安静、噪声、远场、电话、口音、中英切换和多人重叠。
2. 由人工给出参考文本，并单独标记人名、产品名、数字、日期、地址、订单号等高代价字段。
3. 对比 verbatim、smart、自动语言识别和精简 custom vocabulary，不只计算整体 WER。
4. 对多人录音检查 speaker attribution，对字幕检查 final 延迟和重复率，对时间戳检查可否准确回跳。
5. 记录失败请求、重试、空输出、被截断片段、每分钟实际费用和人工修订时间。

一个模型即使整体 WER 很低，也可能在你最不能错的字段上表现不稳。客服质检更关心订单号和承诺内容，会议纪要更关心说话人归属，字幕更关心 final 延迟和断句。验收指标必须跟业务损失对应。

常见接入错误与停止判断

请求成功，但没有说话人或时间戳

先确认使用的是预录 gemini-3.5-transcribe，并且 mode.type 为 verbatim。随后检查是否配置了 diarization_mode 与 timestamp_granularities，以及下游是否真的解析了 annotations。只读取 output_text 看不到逐词结构。

开启 smart 后结构化标注消失

这是当前公开契约，不是提示词问题。smart 与说话人标注/逐词时间戳不兼容。需要干净文稿时用 smart；需要可追溯 transcript 时用 verbatim，再在下游进行受控清理。

实时字幕重复、跳字或最终结果来得慢

先检查 UI 是否把 interim 当成 final 追加保存，再检查 PCM 格式、采样率、声道和 chunk 节奏。结束一段音频时应明确发送 audio_stream_end，或按官方指南配置适合产品的 VAD。不要用 prompt 掩盖媒体管线错误。

模型能转写，却不能总结或调用工具

Transcribe 模型页当前明确不支持 function calling、thinking、Search grounding、file search 或 code execution。先保存可验证 transcript，再把它交给承担后续任务的文本模型。把两个步骤拆开也更容易审计成本和失败。

什么时候不该继续接入

如果你的硬性要求是实时说话人分离、实时逐词时间戳、单 session 超过 10 分钟且不能轮换、预录多人文件超过 30 分钟且不能切分，或者必须在一个模型里完成转写、推理与工具调用，那么当前 Transcribe 契约并不匹配。应先改架构或选择其他 STT 路线，而不是在 preview API 上堆补丁。

最稳妥的上线顺序

先用 gemini-3.5-transcribe 跑一段非敏感短录音，确认 Files API、Interactions API 和 output_text 全链路可用；再按业务选择 smart 或 verbatim，并只加入真正需要的结构化标注。需要实时字幕时，单独验证音频转码、interim/final 状态和 10 分钟 session 边界。

最后再用金标样本和真实分钟数核对质量、延迟、数据政策与总成本。Gemini 3.5 Transcribe 的价值在于把实时和预录 STT 放进 Gemini 开发者生态，但它仍是 public preview，也仍需要独立的媒体管线、验收集与停止条件。