OpenAI Whisper 模式
快速指南: 使用
client.audio.transcriptions.create()进行语音转文字,使用client.audio.translations.create()将非英语音频转换为英语文本。对于最高准确率,选择gpt-4o-transcribe;对于成本效益,选择gpt-4o-mini-transcribe;对于时间戳/SRT/VTT,选择whisper-1;对于说话人识别,选择gpt-4o-transcribe-diarize。文件必须小于 25 MB——对大型文件进行分块。使用prompt来引导词汇和风格。通过stream: true可在gpt-4o-transcribe模型上实现流式传输,以进行渐进式输出。
<critical_requirements>
关键:使用此技能之前
所有代码必须遵循 CLAUDE.md 中的项目约定(kebab-case、命名导出、导入顺序、
import type、命名常量)
(您必须根据用例选择正确的模型——准确率用 gpt-4o-transcribe,时间戳/SRT/VTT 输出用 whisper-1,说话人标签用 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()翻译为英语 - 使用说话人参考进行说话人识别(diarization)
何时不使用:
- 文本转语音 (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 秒的音频片段,以 data 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)
转录 vs 翻译
音频是英语吗?
+-- 是 -> 使用 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(不支持)
中优先级问题:
- 在
gpt-4o-transcribe可以产生更高准确率时使用whisper-1(whisper-1 的幻觉率更高) - 在知道语言时未传递
language参数(自动检测可能对短音频或嘈杂音频有误) - 想要同语言转录时使用
audio.translations.create()(翻译总是输出英语) - 分块时在句子中间拆分音频(在边界处丢失上下文)
常见错误:
- 将
prompt参数视为指令(“请仔细转录”)—— 它是用于词汇和风格匹配的上下文 - 在需要 SRT/VTT 输出时使用
gpt-4o-transcribe—— 只有whisper-1支持这些格式 - 期望
gpt-4o-transcribe-diarize支持提示词或对数概率(它不支持) - 对英语音频使用翻译端点(它只将非英语翻译为英语)
- 转录拆分文件时不提供先前分块的上下文(降低边界处的准确性)
陷阱和边缘情况:
whisper-1上的prompt参数限制约为 224 tokens。更长的提示词会被截断。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。其他格式必须首先转换。
- 除非你提供包含短音频片段的
known_speaker_names和known_speaker_references,否则gpt-4o-transcribe-diarize将说话人标记为“A”、“B”、“C”。 - 翻译端点仅支持
whisper-1,并且仅输出英语 —— 无法通过此 API 翻译成其他语言。 - 流式转录会发出带有
delta字符串属性的transcript.text.delta事件,以及最终的transcript.text.done事件。
</red_flags>
<critical_reminders>
关键提醒
**…
[已截断以进行翻译]