前言¶

开会录了一段音频，事后要整理纪要；播客要做文字稿；视频素材要抽字幕。这类需求并不新鲜，麻烦通常出在流程上：先找转录接口，再写调用脚本，还得处理说话人分离、输出格式、长音频分块。每次换项目又重来一遍。

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