前言¶

開會錄了一段音頻，事後要整理紀要；播客要做文字稿；視頻素材要抽字幕。這類需求並不新鮮，麻煩通常出在流程上：先找轉錄接口，再寫調用腳本，還得處理說話人分離、輸出格式、長音頻分塊。每次換項目又重來一遍。

OpenAI 在 Agent Skills 精選目錄裏提供了 transcribe。它把「何時該用轉錄」「默認選哪個模型」「怎麼跑帶說話人標註的流程」寫進 SKILL.md，並附帶可複用的 CLI。Agent 讀到後，就能按固定步驟調用 OpenAI 轉錄 API，減少臨場拼腳本的成本。

本文基於官方倉庫中的 Skill 原文與 API 說明整理，說明它是什麼、怎麼裝、怎麼用，以及使用時要注意的限制。

這是什麼¶

transcribe 是 OpenAI 官方維護的 Agent Skill（目錄名 transcribe，界面展示名 Audio Transcribe），源碼位於：

https://github.com/openai/skills/tree/main/skills/.curated/transcribe

它的定位很明確：用 OpenAI 的音頻轉錄能力，把音頻（以及帶音軌的視頻容器）轉成文本；需要時再做說話人分離（diarization），並可提供已知說話人的參考音頻。Skill 明確建議優先使用自帶的 scripts/transcribe_diarize.py，以便結果可重複、步驟可覈對。

這類 Skill 採用通用的 SKILL.md 格式，在支持 Agent Skills 標準的工具裏（如 Codex CLI、Cursor、Claude Code）都可以按各自目錄約定安裝啓用。

核心功能與亮點¶

結合 SKILL.md、references/api.md 以及配套 CLI，已覈實的能力如下。

1、默認快速轉寫
默認模型是 gpt-4o-mini-transcribe，默認輸出格式是純文本（--response-format text），適合先拿到一份可讀稿。

2、可選說話人分離
需要標註「誰在說話」時，切換到 gpt-4o-transcribe-diarize，並把響應格式設爲 diarized_json。官方說明該模型面向會話場景，會把語音片段與不同說話人關聯起來。

3、已知說話人提示（最多 4 人）
可通過 --known-speaker "姓名=參考音頻路徑" 傳入參考樣本（內部以 data URL 形式提交）。適合訪談、例會等說話人相對固定的場景。

4、長音頻分塊策略
音頻超過約 30 秒時，Skill 要求保留 --chunking-strategy auto，由服務端做響度歸一化，再用語音活動檢測（VAD）切分後再轉寫。

5、輸出與校驗約定
支持 text / json / diarized_json。Agent 工作流裏會校驗轉寫質量、說話人標籤和片段邊界；多文件時用 --out-dir，避免互相覆蓋。在 Skill 倉庫內評估時，約定落到 output/transcribe/ 下。

6、依賴與密鑰
運行前需要安裝 openai Python SDK，並設置環境變量 OPENAI_API_KEY。Skill 要求：密鑰缺失時讓用戶在本地自行配置，不要在對話裏粘貼完整密鑰。

安裝與啓用¶

Codex CLI¶

精選 Skill 可通過內置的 $skill-installer 按名稱安裝。在 Codex 中安裝 transcribe：

$skill-installer transcribe

也可按 GitHub 目錄安裝：

$skill-installer install https://github.com/openai/skills/tree/main/skills/.curated/transcribe

安裝完成後重啓 Codex，使新 Skill 生效。用戶級路徑默認爲 $CODEX_HOME/skills（未設置時即 ~/.codex/skills）。

Skill 文檔建議一次性設置 CLI 路徑：

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export TRANSCRIBE_CLI="$CODEX_HOME/skills/transcribe/scripts/transcribe_diarize.py"

依賴安裝（優先 uv）：

uv pip install openai

若沒有 uv：

python3 -m pip install openai

並導出 API Key（在本機 shell 中配置，勿貼到聊天裏）：

export OPENAI_API_KEY="你的密鑰"

Cursor¶

Cursor 會自動發現以下目錄中的 Skill：項目級 .cursor/skills/、.agents/skills/；用戶級 ~/.cursor/skills/、~/.agents/skills/。爲兼容其他工具，也會加載 .claude/skills/、.codex/skills/ 以及對應的用戶目錄。

把官方 transcribe 目錄（含 SKILL.md、scripts/、references/ 等）放到例如：

.cursor/skills/transcribe/SKILL.md

或用戶級：

~/.cursor/skills/transcribe/SKILL.md

之後可在 Agent 對話裏用 / 搜索 transcribe 手動調用；當用戶明確提出轉寫錄音、提取講話文本、給訪談/會議打說話人標籤時，Agent 也可能按 description 自動選用。

Claude Code¶

可按同樣的 SKILL.md 包結構，放到項目級 .claude/skills/transcribe/，或用戶級 ~/.claude/skills/transcribe/。具體觸發方式以 Claude Code 當前文檔爲準。

說明：openai/skills 倉庫 README 已標註該目錄倉庫偏向歸檔，當前 Codex 的 Skill/插件示例更推薦參考 OpenAI Plugins 相關文檔；但本文所述的 transcribe 內容仍以該精選路徑下的 SKILL.md 與腳本爲準。

典型用法示例¶

以下命令均來自官方 Skill 文檔或配套 CLI 的約定參數。

1. 單文件快速轉成純文本¶

python3 "$TRANSCRIBE_CLI" \
  path/to/audio.wav \
  --out transcript.txt

不額外指定模型時，使用默認的 gpt-4o-mini-transcribe 與 text 格式。

2. 顯式指定純文本輸出¶

python3 "$TRANSCRIBE_CLI" \
  interview.mp3 \
  --response-format text \
  --out interview.txt

3. 會議錄音：說話人分離 + 已知說話人¶

python3 "$TRANSCRIBE_CLI" \
  meeting.m4a \
  --model gpt-4o-transcribe-diarize \
  --known-speaker "Alice=refs/alice.wav" \
  --known-speaker "Bob=refs/bob.wav" \
  --response-format diarized_json \
  --out-dir output/transcribe/meeting

已知說話人最多 4 個；diarized_json 必須搭配 gpt-4o-transcribe-diarize。

4. 給 Agent 的觸發示例¶

在支持該 Skill 的 Agent 裏，可以直接說清文件與目標，例如：

請把 ./recordings/standup.m4a 轉成文字；如果聽得出多人發言，請做說話人標註。

或：

轉錄這篇訪談音頻，已知說話人蔘考 refs/host.wav 和 refs/guest.wav，輸出 diarized_json。

Agent 應按 Skill 工作流：收集路徑與格式 → 確認 OPENAI_API_KEY → 調用捆綁 CLI → 檢查文本質量與說話人/片段邊界 → 需要時再做一次有針對性的調整。

適用場景與注意事項¶

較適合的場景

• 會議、站會錄音轉紀要底稿
• 播客、訪談轉文字稿，並按說話人拆段
• 從 mp4/webm 等帶音軌文件中抽取講話內容，再做字幕或摘要的前置步驟
• 希望 Agent 按固定決策（默認 mini 模型；要說話人就換 diarize 模型）執行，而不是每次手寫調用參數

使用前需要清楚的限制（來自官方參考與 CLI）

1. 單次請求文件大小上限爲 25 MB；超限時 CLI 會告警。
2. 輸入格式以官方列舉爲準：mp3、mp4、mpeg、mpga、m4a、wav、webm。
3. gpt-4o-transcribe-diarize 不支持 prompt；CLI 在檢測到該模型時會拒絕 --prompt。
4. 超過約 30 秒的音頻應使用 chunking_strategy=auto（CLI 默認即爲 auto）。
5. 必須配置有效的 OPENAI_API_KEY，調用會產生 OpenAI 轉錄 API 費用；具體定價以 OpenAI 模型與計費頁爲準。
6. 轉寫結果仍建議人工抽查專有名詞、重疊發言和嘈雜環境片段；Skill 本身也會提示校驗後再定稿。

小結¶

transcribe 把 OpenAI 轉錄 API 的常見用法收成一套可被 Agent 發現的工作流：默認用 gpt-4o-mini-transcribe 快速出稿，需要說話人時切到 gpt-4o-transcribe-diarize 與 diarized_json，並用捆綁 CLI 保證參數與輸出路徑一致。對經常處理會議錄音、播客和視頻口播的開發者來說，把它裝進 Codex / Cursor / Claude Code 的 skills 目錄，比每次從零拼請求更省事。

官方地址：https://github.com/openai/skills/tree/main/skills/.curated/transcribe