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引導詞彙與風格。gpt-4o-transcribe模型可透過stream: true進行串流,以逐步輸出。
<critical_requirements>
重要:使用此技能前請注意
所有程式碼必須遵循 CLAUDE.md 中的專案慣例(kebab-case、具名匯出、匯入順序、
import type、具名常數)
(您必須根據使用情境選擇正確的模型——gpt-4o-transcribe 用於準確率、whisper-1 用於時間戳記/SRT/VTT 輸出、gpt-4o-transcribe-diarize 用於說話者標籤)
(大於 25 MB 的音訊檔案必須先分段再傳送給 API——API 會拒絕超過此限制的檔案)
(使用 timestamp_granularities 時,必須傳遞 response_format: "verbose_json"——時間戳記僅在 whisper-1 上搭配此格式運作)
(當使用 gpt-4o-transcribe-diarize 處理音訊長度超過 30 秒時,必須設定 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 格式的字幕
- 取得詞彙級或段落級時間戳記,用於影片編輯
- 在多說話者音訊中辨識說話者(diarization)
- 在模型處理音訊時,逐步串流轉錄結果
涵蓋的主要模式:
- 模型選擇(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)
- 您需要辨識對話中的說話者
- 您需要將非英語語音翻譯為英文文字
不應使用此 API 的情況:
- 即時語音聊天——請改用 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) | 是 | 是 | 否 |
| Logprobs | 否 | 是 | 是 | 否 |
| 說話者標籤 | 否 | 否 | 否 | 是 |
| 語言參數 | 是 | 是 | 是 | 是 |
模式 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);
}
完整的串流和 logprob 範例請參閱 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"(音訊長度 > 30s 時為必要)。日誌化不支援 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 會回傳錯誤)
- 使用
gpt-4o-transcribe-diarize處理音訊 > 30 秒卻未設定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支援提示或 logprobs(它不支援) - 對英文音訊使用翻譯端點(它只將非英語翻譯為英文)
- 在轉錄分割檔案時未提供前一段落的上下文(會降低邊界處的準確率)
陷阱與邊界情況:
- 在
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>
重要提醒
**
…
[為翻譯而截斷]