Communitygithub.com

majiayu000/claude-skill-registry-data

透過 OpenAI 音訊 API 進行語音轉文字與翻譯——支援模型、回應格式、時間戳記、提示、串流、分段與說話者辨識

claude-skill-registry-data 是什麼?

此技能提供使用 OpenAI 音訊 API 進行語音辨識(語音轉文字)與翻譯的完整實作模式與最佳實踐。它涵蓋多種模型選擇:`gpt-4o-transcribe` 用於最高準確率、`gpt-4o-mini-transcribe` 用於成本效益、`whisper-1` 用於 SRT/VTT 字幕與詳細時間戳記、`gpt-4o-transcribe-diarize` 用於說話者辨識。主要功能包括基本轉錄、模型能力比較矩陣、使用提示(prompt)參數引導詞彙與風格、處理大於 25 MB 的音訊檔案(分段轉錄並保留上下文)、`gpt-4o-transcribe` 模型的串流轉錄、透過 `audio.translations.create()` 將非英語音訊翻譯為英文,以及針對多說話者音訊的說話者日誌化(diarization)。技能明確列出紅旗警示,例如未使用正確的 `response_format` 搭配 `timestamp_granularities`、發送過大檔案、或在不支援的模型上使用串流。

相容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/majiayu000/claude-skill-registry-data/tree/HEAD/ai-llm/api-ai-openai-whisper

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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

範例索引


理念

OpenAI 音訊 API 透過多種針對不同需求最佳化的模型,提供語音轉文字的轉錄與翻譯。API 很簡單——您傳送一個音訊檔案並取回文字——但選擇正確的模型、回應格式和參數對於獲得高品質結果至關重要。

核心原則:

  1. 模型選擇很重要——gpt-4o-transcribe 提供最高準確率與較低的幻覺率。whisper-1 是唯一支援 SRT/VTT/verbose_json 並附帶時間戳記的模型。gpt-4o-transcribe-diarize 增加了說話者辨識功能。
  2. 檔案大小是主要限制——25 MB 限制意味著您必須分段處理較長音訊。在句子邊界處分割以保留上下文。
  3. 提示可提高準確率——prompt 參數引導詞彙、縮寫和格式化風格。它並非提供指令——而是提供模型比對的上下文。
  4. 回應格式決定可用功能——時間戳記需要在 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-1gpt-4o-transcribegpt-4o-mini-transcribegpt-4o-transcribe-diarize
回應格式json, text, srt, vtt, verbose_jsonjson, textjson, textjson, 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>

重要提醒

**

…

[為翻譯而截斷]

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

majiayu000/claude-skill-registry-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

Analyzes current state and user query to answer BMad questions or recommend the next workflow or agent. Use when user says what should I do next, what do I do now, or asks a question about BMad

majiayu000/claude-skill-registry-data

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry-data

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry-data

Portfolio allocation and rebalancing optimizer. Manages asset allocation across stocks/cash/bonds, performs periodic rebalancing, and ensures diversification according to market regime and risk tolerance.

majiayu000/claude-skill-registry-data

Create a hilarious and ultra-realistic video of an anthropomorphic animal acting like a human vlogger in a real-world setting.

majiayu000/claude-skill-registry-data

This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.

majiayu000/claude-skill-registry-data

小省导购员数字人带货版即梦视频提示词生成系统,基于四大智能体协同(提示词生成师、质量管控师、知识库运维师、跨环节适配师),按照"主体+运动+场景+(镜头语言+光影+氛围)"公式输出中英文双版提示词,适配5s短视频。确保人物一致性、视觉连贯性、情绪连贯性,支持知识库智能复用和跨工具适配(Suno音乐、AI绘画),为数字人带货视频提供高质量提示词生成服务。

majiayu000/claude-skill-registry-data

Upload and manage files using Google Gemini File API via scripts/. Use for uploading images, audio, video, PDFs, and other files for use with Gemini models. Supports file upload, status checking, and file management. Triggers on "upload file", "file API", "upload image", "upload PDF", "upload video", "file management".

majiayu000/claude-skill-registry-data

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry-data

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry-data

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

majiayu000/claude-skill-registry-data

Conduct domain and industry research. Use when the user says "lets create a research report on [domain or industry]

majiayu000/claude-skill-registry-data

Conduct market research on competition and customers. Use when the user says "create a market research report about [business idea]".

majiayu000/claude-skill-registry-data

Conduct technical research on technologies and architecture. Use when the user says "create a technical research report on [topic]".

majiayu000/claude-skill-registry-data

Understand an existing codebase through systematic exploration

majiayu000/claude-skill-registry-data

Builds, edit or validate Agent Skill through conversational discovery. Use when the user requests to "Create an Agent", "Optimize an Agent" or "Edit an Agent".

相關技能