Gemini 3.5 Transcribe 实战：多语言转录API与批量字幕生成

这次我们来看的是 Gemini 3.5 Transcribe。做音视频内容处理的人都明白转录工作最麻烦的部分往往不是“语音识别”本身而是处理语言混合、时间戳对齐和批量任务调度。Gemini 3.5 Transcribe 的发布重点就是多语言转录适合把一段音频或视频内容直接转换为带时间信息的文本再交给字幕工具、知识库或者翻译管线继续处理。这篇文章会按照“环境准备 - API 配置 - 单文件测试 - 批量任务 - 字幕导出 - 异常排查”的顺序展开帮你快速判断它能不能接入现有的工作流。先给结论这类转录能力最终要通过 API 调用本地不需要庞大 GPU 资源部署重点在网络连通性、凭证管理和文件预处理。真正需要花功夫的是批量场景下的节奏控制、超时重试和输出格式统一。如果你正在做播客文字稿、课堂录音整理、短视频字幕生成或会议纪要自动化下面的流程可以直接当作一套基础模板。全文会围绕三个核心问题来写多语言转录怎么调用返回结果怎么解析批量任务怎么稳定跑完。文章末尾还会给出一份常见问题排查表方便你收藏后直接对照处理。1. 核心能力速览把 Gemini 3.5 Transcribe 的关键信息整理成一张表。这里需要说明部分字段例如具体支持语言列表、单次请求文件上限、模型名称会随服务版本和账号权限变化落地时以官方文档和实际返回结果为准。能力项说明项目类型多语言语音转写 / 多语言转录服务主要功能音频转写、多语言识别、时间戳输出、字幕导出支持语言从发布信息看主打多语言具体列表需以官方文档为准调用方式HTTP API / 官方 SDK部署方式云端服务本地通过接口调用本地硬件门槛不需要独立 GPU普通主机即可是否支持 API支持按接口凭证调用是否支持批量任务可以在业务层实现文件夹批量处理是否支持自定义输出通过提示词或参数控制输出 JSON、Markdown、SRT 等适合场景字幕生成、会议纪要、音视频归档、多语言内容再加工从这张表可以看出Gemini 3.5 Transcribe 的核心价值不是“又一个语音识别接口”而是把识别能力、多语言支持和结构化输出放到同一个处理链路里。对于开发者来说最需要关心的是返回结果能否稳定解析以及批量任务在长音频场景下是否容易中断。这两个点后面的章节会重点演示。有一点要提前强调如果你是首次使用这类转录服务不要一上来就处理 1 小时的录音。先用 30 秒到 2 分钟的短音频跑通流程确认返回结果格式再逐步放大。这样可以避免把“提示词格式问题”和“文件时长问题”混在一起排查。2. 适用场景与使用边界先讲适合的使用场景。多语言转录最直接的落地场景是字幕和文字稿生成。例如短视频创作者把口播音频转成字幕播客编辑把整期节目转成文字稿课程平台把教师讲课录音转成结构化的学习笔记。这个过程如果能通过脚本批量完成会大幅省去人工听写的时间。第二个场景是内容归档与检索。很多公司会把会议录音、访谈材料、客户沟通记录保存下来但纯音频文件难以检索。转录成文字后可以继续做关键词搜索、摘要生成、标签提取。这里的转录质量会直接决定下游检索效果因此多语言支持是否稳定、专有名词是否准确是需要重点验证的。第三个场景是翻译和本地化前处理。把原文转成带时间戳的文字后可以交给翻译模型生成多语言字幕。相比直接让模型听音频翻译先转录再翻译的思路更可控也更容易人工校对。再看不适合的场景。实时同传或低延迟语音识别并不完全符合这类转录服务的典型用法。多语言转录通常需要先上传文件再异步拿到结果启动速度快不代表流式能力强。如果你需要麦克风实时转写应该优先评估专门的流式语音识别方案而不是把文件转录服务硬套到实时场景。使用边界必须明确。语音转录涉及大量个人信息、商业机密和版权内容使用时需要满足三个前提音频素材来源合法已获得相关说话人和版权方的授权涉及个人信息的音频在传输和存储过程中做好脱敏、访问控制和日志保护转录结果用于公开发布或商业用途前必须经过人工复核避免因识别错误导致误解。此外批量任务的设计者应当为接口配置独立的访问凭证不使用共享账号并且定期轮换密钥。这属于工程上的基本安全习惯在录制内容较为敏感的场景下尤其重要。3. 环境准备与前置条件Gemini 3.5 Transcribe 的转录能力跑在云端本地环境主要用于调用接口、上传文件和解析返回结果。所以环境准备的重点不是显卡驱动而是 Python 环境、SDK、音频预处理工具和凭证管理。推荐的操作系统是 Linux 或 macOSWindows 也能跑但文件路径和命令行写法需要相应调整。Python 建议使用 3.10 或更高版本方便使用新版 SDK 中的类型注解和异步能力。如果你的机器上同时存在多个 Python 版本建议为项目单独创建虚拟环境。这里给出一个通用环境准备流程# 1. 创建项目目录 mkdir gemini-transcribe-demo cd gemini-transcribe-demo # 2. 创建虚拟环境 python -m venv venv # 3. 激活虚拟环境 # Linux / macOS source venv/bin/activate # Windows PowerShell # venv\Scripts\Activate.ps1 # 4. 安装依赖 pip install --upgrade google-genai python-dotenvgoogle-genai是 Gemini API 的官方 Python SDK负责文件上传和内容生成请求。python-dotenv用来加载环境变量避免把密钥写进代码文件。音频预处理工具方面建议安装ffmpeg。转录服务对上传文件的格式和时长往往有默认限制而待处理的原始素材可能是 m4a、wma、flv、mov 等非常规格式先用 ffmpeg 统一转成 mp3 或 wav能减少很多兼容性问题。# Ubuntu / Debian sudo apt update sudo apt install -y ffmpeg # macOSHomebrew # brew install ffmpeg # 验证安装 ffmpeg -version上传之前建议先查看音频基础信息确认采样率、时长和声道数量ffprobe -show_format -show_streams demo_audio.mp3这一步可以帮助你判断是否需要降采样、转单声道或切片。一般来说语音转写场景对采样率不是越高越好16kHz 到 44.1kHz 都常见但声道越多文件越大清晰度提升有限。对单说话人录音转成单声道通常更稳妥。凭证准备是另一个关键步骤。需要先从对应平台的控制台创建一个 API 密钥并把密钥写入项目根目录的.env文件内容如下GEMINI_API_KEY你的_API_密钥注意.env文件不要提交到代码仓库。如果使用 Git确认.gitignore中已经包含.env。无论使用哪种密钥管理方式都不要把密钥硬编码到脚本里这是本地部署类项目最常见的泄漏点。4. 安装部署与配置依赖安装完成并配置好凭证后就可以写最小调用脚本了。这里先演示单文件转录的基本流程模型名先用gemini-3.5-transcribe作为示例。实际调用时请以你账号中可用的模型名称为准。import os from dotenv import load_dotenv from google import genai load_dotenv() client genai.Client(api_keyos.getenv(GEMINI_API_KEY)) audio_file client.files.upload(pathdemo_audio.mp3) response client.models.generate_content( modelgemini-3.5-transcribe, contents[ audio_file, 请将这段音频转写成文字输出带时间戳的文本。, ], ) print(response.text)运行方式python transcribe_single.py如果一切正常控制台会打印出转录文本。这段脚本做的事情可以分成三步读取 API 密钥初始化客户端把本地音频文件上传到服务端拿到一个可引用的文件对象调用模型生成转录结果并输出。这里有一个需要注意的点client.files.upload返回的文件 ID 或引用对象在后续请求中可以直接作为多模态输入的一部分传入。对于长音频上传过程可能比短音频耗时更多所以代码里最好加上异常处理避免中途失败时直接退出。另外初次跑通后不要直接进入批量处理。先把返回的response.text打印出来观察格式是否符合预期。如果默认文本中没有时间戳通常是因为提示词没有明确要求或者模型按默认的纯文本格式返回。你需要指定输出模板例如“每行包含开始时间、结束时间和文本内容”。下面是一个更完整的配置示例加入了输出文件保存from pathlib import Path output_path Path(transcripts) / demo_audio.txt output_path.parent.mkdir(exist_okTrue) output_path.write_text(response.text, encodingutf-8) print(f转录结果已保存到 {output_path})这样单文件流程就跑通了。接下来的章节会继续扩展先细化功能测试包括多语言、较长时间段、噪声环境的情况再讲解批量任务和接口参数的组织方式。5. 功能测试与效果验证单文件流程跑通之后需要做一轮功能测试确认转录能力在不同条件下表现稳定。建议准备一组测试集而不是只测一个文件。测试集可以按以下规则组织测试编号素材特征测试目的T01单人中文朗读安静环境验证基础中文转录能力T02英文访谈双人对话验证英语和说话人切换T03中英混合口播验证多语言混说识别T04含背景音乐或轻微噪声验证抗噪声能力T055 分钟以上长录音验证超时和长文件稳定性测试时可以写一个小脚本循环处理整个目录import os import time from pathlib import Path from dotenv import load_dotenv from google import genai load_dotenv() client genai.Client(api_keyos.getenv(GEMINI_API_KEY)) input_dir Path(test_audio) output_dir Path(test_output) output_dir.mkdir(exist_okTrue) for audio_path in sorted(input_dir.glob(*.mp3)): print(f处理: {audio_path.name}) try: uploaded client.files.upload(pathstr(audio_path)) response client.models.generate_content( modelgemini-3.5-transcribe, contents[ uploaded, 请转写这段音频返回格式为 [开始时间] [结束时间] 文本内容 说话人交替时另起一行。, ], ) output_file output_dir / f{audio_path.stem}.txt output_file.write_text(response.text, encodingutf-8) print(f已保存: {output_file}) except Exception as exc: print(f失败: {audio_path.name}, 错误: {exc}) time.sleep(1)判断成功与否不能只看脚本有没有报错。建议从三个维度评估文本正确率核心人名、地名、数字、专业术语是否准确时间戳对齐程度字幕逐句出现的时间点是否与实际语音匹配稳定性同一段音频重复调用两次结果差异是否在可接受范围内。对 T01 这类安静环境单说话人音频预期结果是文本内容与原始口播高度一致时间戳能对应到每个句子。对 T02 双人访谈需要关注说话人之间的切换是否被正确分段。对 T03 中英混合最容易出现的问题是语言切换处内容错乱因此要用短句居多、切换明显的素材单独验证。对 T04 和 T05主要看识别率下降程度和长文件是否出现超时。如果某一项测试不通过先不要怀疑模型本身。按顺序排查三个因素音频质量是否太差噪声和混响是否过大提示词是否明确是否要求了特定的输出格式文件是否超过当前服务的单次限制如果超过就需要切片。对于带背景音乐的素材先用 ffmpeg 降噪或去除人声以外的频段通常能提升转录准确率。命令可以参考ffmpeg -i noisy_audio.mp3 -af highpassf200,lowpassf8000 clean_audio.mp3这个命令保留 200Hz 到 8000Hz 的频段适合语音为主的素材。具体参数需要根据实际音频调整不要当作固定公式直接用。在得到稳定的单文件结果后再把注意力切到批量任务和接口能力上。6. 接口 API 与批量任务Gemini 3.5 Transcribe 的接口调用模式决定了它可以很方便地接入到自动化流程中。批处理的核心是在脚本里维护一个任务队列逐个上传音频、发起转录、保存结果并在失败时重试。下面是一个批量转录脚本的完整示例。它支持自动扫描目录下的所有 mp3、wav、m4a 文件输出结果按原始文件名保存为 txt 文件已处理文件跳过避免重复消耗配额单个文件失败后自动重试最多重试 3 次。import os import time from pathlib import Path from dotenv import load_dotenv from google import genai load_dotenv() client genai.Client(api_keyos.getenv(GEMINI_API_KEY)) INPUT_DIR Path(audio_in) OUTPUT_DIR Path(transcripts_out) MAX_RETRIES 3 SLEEP_SECONDS 1 SUPPORTED_SUFFIX {.mp3, .wav, .m4a, .flac} def transcribe_audio(path: Path) - str: uploaded client.files.upload(pathstr(path)) response client.models.generate_content( modelgemini-3.5-transcribe, contents[ uploaded, 请转录这段音频输出格式\n [开始时间] [结束时间] 文本\n 如果存在多个说话人请在切换说话人时换行。, ], ) return response.text def process_file(path: Path) - bool: output_path OUTPUT_DIR / f{path.stem}.txt if output_path.exists(): print(f跳过已处理文件: {path.name}) return True for attempt in range(1, MAX_RETRIES 1): try: print(f开始处理: {path.name} (第 {attempt} 次尝试)) text transcribe_audio(path) output_path.write_text(text, encodingutf-8) return True except Exception as exc: print(f失败: {path.name}, {exc}) time.sleep(SLEEP_SECONDS * attempt) return False def main(): OUTPUT_DIR.mkdir(exist_okTrue) files [ p for p in INPUT_DIR.glob(*) if p.suffix.lower() in SUPPORTED_SUFFIX ] print(f共发现 {len(files)} 个待处理文件) success 0 failed [] for file_path in files: if process_file(file_path): success 1 else: failed.append(file_path.name) time.sleep(SLEEP_SECONDS) print(f成功: {success} / {len(files)}) if failed: print(失败文件:) for name in failed: print(f - {name}) if __name__ __main__: main()运行python batch_transcribe.py这个脚本的价值不只是批量处理文件更重要的是它把“可重试”这个机制固化下来。转录任务中常见的失败原因包括网络波动、配额超限、上传超时等加上重试之后整体完成率会显著提升。重试间隔使用递增策略即第一次失败等 1 秒第二次等 2 秒第三次等 3 秒避免在服务端还未恢复时密集打请求。批量任务建议配合日志使用。最简单的方式是在脚本里增加logging配置把每次处理的状态输出到一个日志文件import logging logging.basicConfig( levellogging.INFO, format%(asctime)s [%(levelname)s] %(message)s, handlers[ logging.StreamHandler(), logging.FileHandler(transcribe_batch.log, encodingutf-8), ], )日志里应该至少包含三个字段文件名、尝试次数、最终结果。后续如果要重跑只需要看日志中哪些文件成功、哪些文件失败而不需要重新扫描整个内容。除了脚本调用也可以直接用 curl 模拟请求便于快速联调。这里给出一个通用示例实际 URL、请求头和参数结构必须以官方 API 文档为准curl -X POST \ https://example.api.endpoint/transcribe \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d { audio_url: https://example.com/audio/demo.mp3, language: auto, output_format: srt }需要明确说明这是一个占位示例。真实项目中的接口地址、请求字段和返回结构请以 Gemini API 文档为准不要直接复制到生产环境。批量任务的输出格式需要尽量统一。如果最终目标是字幕建议在提示词中要求模型输出 SRT 或 VTT 格式并单独做一个后处理脚本把返回文本拆成标准的字幕文件。一个简单的 SRT 后处理思路是先用正则把[开始时间] [结束时间] 文本的行结构解析出来再按 SRT 序号、时间轴、文本三部分重新格式化。时间格式也可能需要从秒或分钟制转为00:00:01,000的格式。这些解析逻辑并不复杂但需要单独写脚本并保持稳定。7. 资源占用与性能观察由于转录主要在云端完成本地性能观察的重点会和其他本地推理项目不同。我们不需要盯显卡显存而是要看网络传输、内存占用和接口延迟。先看本地资源。调用client.files.upload时本地会有一定的内存占用用于分片读取和上传但整体压力小于本地跑语音识别模型。真正需要关注的是硬件的网络带宽长音频文件上传越慢单个任务的耗时越大。如果待处理文件很多可以加大SLEEP_SECONDS或在业务侧做并发控制避免同时上传太多文件。再看接口耗时。一次转录任务的耗时可以被拆成三部分上传耗时受本地带宽和文件大小影响服务端处理耗时受音频长度、语言种类、模型负载影响文本生成本地解析耗时通常极短。实际测试时可以用 Python 的time模块记录各部分耗时import time start time.time() uploaded client.files.upload(pathdemo.mp3) print(f上传耗时: {time.time() - start:.2f}s) start time.time() response client.models.generate_content(...) print(f推理耗时: {time.time() - start:.2f}s)如果发现上传耗时远大于服务端处理耗时可以优先压缩音频文件。比如把高码率 wav 转成 128kbps 的 mp3通常会明显减小文件体积同时不显著影响语音识别效果。如果发现服务端处理耗时异常偏高通常是文件较长或提示词复杂。这时先把提示词简化去掉不必要的要求再用同一段音频测试。文件较长时考虑切片处理。切片可以用 ffmpeg 完成。假设每段 10 分钟ffmpeg -i long_audio.mp3 -f segment -segment_time 600 -c copy segment_%03d.mp3切片之后每段单独转录再在业务层把结果拼接并调整时间戳偏移。这样做的好处