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,需要時間戳記/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()翻譯為英語 - 帶有說話者參考的說話者辨識
不應使用的時機:
- 文字轉語音(TTS)——請使用 OpenAI TTS API(
client.audio.speech.create()) - 即時雙向語音對話——請使用 OpenAI Realtime API
- 使用非 OpenAI 提供者的轉錄——請使用提供者無關的語音 SDK
範例索引
- 核心:轉錄、翻譯、時間戳記、分段、串流、說話者辨識 —— 所有音訊 API 模式
理念
OpenAI Audio 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上可用。
何時使用 Audio 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 事件以獲得完成狀態。請勿將 stream: true 與 whisper-1 一起使用——它不受支援。
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:說話者辨識
識別多人音訊中的說話者。使用 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"
+-- 帶有 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 會回傳錯誤) - 將
stream: true與whisper-1一起使用(不受支援)
中優先級問題:
- 在
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。其他格式必須先進行轉換。
gpt-4o-transcribe-diarize將說話者標記為「A」、「B」、「C」,除非您提供了帶有短音訊剪輯的known_speaker_names和known_speaker_references。- 翻譯端點僅支援
whisper-1並且僅輸出英語——無法透過此 API 翻譯成其他語言。 - 串流轉錄會發射出帶有
delta字串屬性的transcript.text.delta事件,以及最終的transcript.text.done事件。
</red_flags>
<critical_reminders>
關鍵提醒
**
…
[truncated for translation]