OpenAI Whisper 模式
快速指南: 使用
client.audio.transcriptions.create()进行语音转文字,使用client.audio.translations.create()将非英语音频转为英语文本。选择gpt-4o-transcribe以获得最高精度,gpt-4o-mini-transcribe以获得成本效益,whisper-1用于时间戳/SRT/VTT,或gpt-4o-transcribe-diarize用于说话人识别。文件必须小于25 MB——较大的文件请分块。使用prompt指导词汇和风格。通过stream: true在gpt-4o-transcribe模型上实现流式输出。
<critical_requirements>
关键要素:使用本技能前
所有代码必须遵循CLAUDE.md中的项目约定(kebab-case、命名导出、导入顺序、
import type、命名常量)
(您必须根据用例选择正确的模型——gpt-4o-transcribe用于精度,whisper-1用于时间戳/SRT/VTT输出,gpt-4o-transcribe-diarize用于说话人标签)
(您必须在发送到API之前将大于25 MB的音频文件分块——API拒绝超过此限制的文件)
(使用timestamp_granularities时,您必须传递response_format: "verbose_json"——时间戳仅在whisper-1上配合此格式工作)
(对超过30秒的音频使用gpt-4o-transcribe-diarize时,您必须设置chunking_strategy: "auto"——API要求如此)
</critical_requirements>
自动检测: Whisper, whisper-1, gpt-4o-transcribe, gpt-4o-mini-transcribe, gpt-4o-transcribe-diarize, audio.transcriptions, audio.translations, transcription, speech-to-text, diarization, diarized_json, timestamp_granularities, verbose_json
使用时机:
- 将音频文件(会议、采访、播客、语音笔记)转录为文本
- 将非英语音频翻译为英语文本
- 从音频生成SRT或VTT格式的字幕
- 获取词级或片段级时间戳以用于视频编辑
- 识别多说话人音频中的说话人(说话人分离)
- 随着模型处理音频,逐步流式输出转录结果
涵盖的关键模式:
- 模型选择(whisper-1 vs gpt-4o-transcribe vs gpt-4o-mini-transcribe vs gpt-4o-transcribe-diarize)
- 响应格式(json, text, srt, vtt, verbose_json, diarized_json)
- 时间戳(词级、片段级)和字幕生成
- 词汇、缩写和风格提示
- 大文件(> 25 MB)分块及上下文保留
- 使用
stream: true进行流式转录 - 通过
audio.translations.create()翻译为英语 - 使用说话人参考进行说话人分离
何时不使用:
- 文本转语音(TTS)——使用OpenAI TTS API (
client.audio.speech.create()) - 实时双向语音对话——使用OpenAI Realtime API
- 使用非OpenAI提供商的转录——使用提供商无关的语音SDK
示例索引
- 核心:转录、翻译、时间戳、分块、流式、说话人分离 —— 所有音频API模式
理念
OpenAI音频API提供语音转文字转录和翻译,通过多个针对不同需求优化的模型。API很简单——您发送一个音频文件并获取文本——但选择正确的模型、响应格式和参数对于获得高质量结果至关重要。
核心原则:
- 模型选择很重要——
gpt-4o-transcribe产生最高精度和更低的幻觉率。whisper-1是唯一支持SRT/VTT/verbose_json带时间戳的模型。gpt-4o-transcribe-diarize添加了说话人识别。 - 文件大小是主要限制——25 MB限制意味着您必须对更长的音频进行分块。在句子边界处拆分以保留上下文。
- 提示提高准确性——
prompt参数指导词汇、缩写和格式风格。它不提供指令——它提供模型匹配的上下文。 - 响应格式决定可用功能——时间戳需要
whisper-1上的verbose_json。说话人分离需要diarized_json。SRT/VTT仅在whisper-1上可用。
何时使用音频API:
- 您需要准确转录录制的音频文件
- 您需要从音频生成字幕(SRT/VTT)
- 您需要识别对话中的说话人
- 您需要将非英语语音翻译为英语文本
何时不使用:
- 实时语音聊天——请改用Realtime API
- 文本转语音——使用
client.audio.speech.create() - 您需要将转录结果输出为非英语目标语言(翻译仅输出英语)
核心模式
模式 1:基本转录
发送一个音频文件并接收文本返回。模型自动检测语言。
const transcription = await client.audio.transcriptions.create({
model: "gpt-4o-transcribe",
file: createReadStream(audioPath),
});
使用gpt-4o-transcribe以获得最高精度。当您只需要纯文本时,不要对whisper-1使用verbose_json——它增加了开销并具有更高的幻觉率。参见core.md获取完整示例。
模式 2:模型选择
每个模型具有不同的能力和权衡。
您需要什么?
+-- 最高精度,纯文本 -> gpt-4o-transcribe
+-- 成本效益,纯文本 -> gpt-4o-mini-transcribe
+-- 时间戳(词/片段) -> whisper-1 (verbose_json)
+-- SRT 或 VTT 字幕 -> whisper-1 (srt/vtt 格式)
+-- 说话人识别 -> gpt-4o-transcribe-diarize
+-- 流式输出 -> gpt-4o-transcribe 或 gpt-4o-mini-transcribe
模型能力矩阵
| 特性 | whisper-1 | gpt-4o-transcribe | gpt-4o-mini-transcribe | gpt-4o-transcribe-diarize |
|---|---|---|---|---|
| 响应格式 | json, text, srt, vtt, verbose_json | json, text | json, text | json, text, diarized_json |
| 时间戳 | 词 + 片段 | 无 | 无 | 无 |
| 流式 | 无 | 是 | 是 | 无 |
| 提示支持 | 是(224 tokens) | 是 | 是 | 无 |
| 对数概率 | 无 | 是 | 是 | 无 |
| 说话人标签 | 无 | 无 | 无 | 是 |
| 语言参数 | 是 | 是 | 是 | 是 |
模式 3:词汇和风格提示
prompt参数提供上下文——而非指令。它指导名称、缩写和格式风格的拼写。不要用它来给出“请仔细转录”这样的指令——它匹配风格和词汇上下文。
const VOCABULARY_PROMPT = "Kubernetes, kubectl, etcd, NGINX, gRPC, PostgreSQL";
const transcription = await client.audio.transcriptions.create({
model: "gpt-4o-transcribe",
file: createReadStream(audioPath),
prompt: VOCABULARY_PROMPT,
});
用例: 缩写/专有名词、跨分块保留上下文(传递前一个转录的尾部)、保留填充词、写作风格指导。参见core.md获取详细词汇示例。
模式 4:大文件分块
超过25 MB的音频文件必须在转录前拆分。在句子边界处拆分(例如通过 ffmpeg)以保留上下文。将前一个转录的尾部作为prompt传递,以保持跨分块的连续性。
const MAX_FILE_SIZE_BYTES = 25 * 1024 * 1024; // 25 MB
// 使用 ffmpeg 拆分:ffmpeg -i long.mp3 -f segment -segment_time 600 -c copy chunk_%03d.mp3
// 然后顺序转录,通过 prompt 传递前一个上下文
参见core.md获取包含大小验证和上下文保留的完整分块实现。
模式 5:流式转录
在模型处理音频时流式输出部分转录结果。只有gpt-4o-transcribe和gpt-4o-mini-transcribe支持stream: true。监听transcript.text.delta事件以获取渐进输出,以及transcript.text.done事件以获取完成状态。不要在whisper-1上使用stream: true——它不被支持。
const stream = await client.audio.transcriptions.create({
model: "gpt-4o-transcribe",
file: createReadStream(audioPath),
stream: true,
});
for await (const event of stream) {
if (event.type === "transcript.text.delta") process.stdout.write(event.delta);
}
参见core.md获取完整的流式和对数概率示例。
模式 6:翻译为英语
将非英语音频翻译为英语文本。只有whisper-1通过audio.translations.create()支持。对于同语言转录,请改用audio.transcriptions.create()。翻译仅输出英语——无法翻译成其他语言。
const translation = await client.audio.translations.create({
model: "whisper-1",
file: createReadStream(audioPath),
});
参见core.md获取完整的翻译示例,包括词汇提示。
模式 7:说话人分离(Diarization)
识别多说话人音频中的说话人。使用gpt-4o-transcribe-diarize配合response_format: "diarized_json"和chunking_strategy: "auto"(对于超过30秒的音频是必需的)。说话人分离不支持prompt、logprobs或timestamp_granularities。
const transcription = await client.audio.transcriptions.create({
model: "gpt-4o-transcribe-diarize",
file: createReadStream(audioPath),
response_format: "diarized_json",
chunking_strategy: "auto",
});
可选择提供known_speaker_names和known_speaker_references(2-10秒音频片段,格式为数据URL)以将片段映射到已知说话人(最多4个)。参见core.md获取完整的说话人分离示例。
<decision_framework>
决策框架
选择哪个模型
您需要从转录中获得什么?
+-- 仅文本(最高精度) -> gpt-4o-transcribe
+-- 仅文本(成本敏感) -> gpt-4o-mini-transcribe
+-- 词/片段时间戳 -> whisper-1 (verbose_json)
+-- SRT 或 VTT 字幕文件 -> whisper-1 (srt 或 vtt)
+-- 说话人识别 -> gpt-4o-transcribe-diarize
+-- 渐进/流式输出 -> gpt-4o-transcribe (stream: true)
使用哪个响应格式
您需要什么输出?
+-- 纯文本字符串 -> "text"
+-- 包含文本字段的 JSON -> "json"(默认)
+-- 视频字幕 -> "srt" 或 "vtt"(仅限 whisper-1)
+-- 时间戳(词/片段) -> "verbose_json"(仅限 whisper-1)
+-- 带说话人标签的片段 -> "diarized_json"(仅限 gpt-4o-transcribe-diarize)
转录与翻译
音频是否是英语?
+-- 是 -> 使用 audio.transcriptions.create()
+-- 否 -> 您希望输出为原始语言吗?
+-- 是 -> 使用 audio.transcriptions.create()(自动检测语言)
+-- 否(想要英语) -> 使用 audio.translations.create()(仅限 whisper-1)
</decision_framework>
<red_flags>
红牌警告
高优先级问题:
- 在
whisper-1上使用timestamp_granularities但未配合response_format: "verbose_json"(静默忽略) - 发送大于25 MB的文件(API返回错误)
- 对超过30秒的音频使用
gpt-4o-transcribe-diarize但未设置chunking_strategy(API返回错误) - 在
whisper-1上使用stream: true(不被支持)
中优先级问题:
- 使用
whisper-1而gpt-4o-transcribe可以产生更高精度时(whisper-1具有更高的幻觉率) - 在知道语言的情况下未传递
language参数(对于短音频或嘈杂音频,自动检测可能错误) - 当您想要同语言转录时却使用了
audio.translations.create()(翻译总是输出英语) - 分块时在句子中间拆分音频(在边界处丢失上下文)
常见错误:
- 将
prompt参数视为指令(“请仔细转录”)——它是用于词汇和风格匹配的上下文 - 当您需要SRT/VTT输出时使用
gpt-4o-transcribe——只有whisper-1支持这些格式 - 期望
gpt-4o-transcribe-diarize支持提示或对数概率(它不支持) - 对英语音频使用翻译端点(它只将非英语翻译为英语)
- 转录拆分文件时未提供前一个分块上下文(降低边界处的准确性)
陷阱与边界情况:
whisper-1上的prompt参数限制约为224个token。更长的提示会被截断。whisper-1可能会对无声或接近无声的音频片段产生幻觉文本。使用verbose_json中的no_speech_prob检测此情况。gpt-4o-transcribe和gpt-4o-mini-transcribe仅支持json和text响应格式——不支持srt、vtt或verbose_json。language参数使用ISO 639-1代码(例如"en"、"fr"、"ja")。对于短音频,设置它可以提高准确性。- 支持的文件格式:flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm。其他格式必须先转换。
gpt-4o-transcribe-diarize将说话人标记为“A”、“B”、“C”,除非您提供带有短音频片段的known_speaker_names和known_speaker_references。- 翻译端点仅支持
whisper-1且仅输出英语——无法通过此API翻译成其他语言。 - 流式转录发出
transcript.text.delta事件,带有delta字符串属性,以及一个最终的transcript.text.done事件。
</red_flags>
<critical_reminders>
关键提示
**
…[为翻译而截断]