前言¶

做产品 Demo、无障碍朗读或电话 IVR 提示音时，常见流程是：写好文案，再去平台控制台点一次「生成语音」，或者自己拼一段调用 OpenAI Audio API 的脚本。文案一改、音色一换、要批量出几十条提示音，脚本和参数很容易散落在各处，结果也不好复现。

OpenAI 在官方 openai/skills 仓库里提供了一个名为 speech 的 Agent Skill。它把「文本转语音」封装成可复用的 SKILL.md 工作流，并附带 CLI（scripts/text_to_speech.py），让 Cursor、Codex CLI、Claude Code 等支持 Agent Skills 的工具，在拿到明确文案后，按统一约定调用 OpenAI Speech API，输出音频文件。

这是什么¶

speech 是 OpenAI 官方 curated 技能之一，目录在：

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

定位很直接：当用户需要旁白、产品配音、无障碍朗读、IVR/音频提示，或批量生成语音时，由 Agent 读取该 Skill，优先用自带 CLI 调用 OpenAI Audio API（POST /v1/audio/speech），生成音频文件。自定义音色（voice cloning）不在本 Skill 范围内。

默认模型为 gpt-4o-mini-tts-2025-12-15，默认音色为 cedar；需要更明亮一点的音色时，官方建议优先用 marin。

核心功能与亮点¶

根据官方 SKILL.md 与 references/ 文档，主要能力如下：

1. 单条与批量两条路径
   一条文案走 speak；多行/多文件走 speak-batch（临时 JSONL，一行一个任务）。Skill 里有明确的决策树，避免 Agent 每次临时写脚本。

2. 自带可复现 CLI
   入口是 scripts/text_to_speech.py，支持 speak、speak-batch、list-voices。官方要求优先用这个 CLI，不要擅自改脚本，也不要另写一次性 gen_audio.py（除非用户明确要求）。

3. 风格指令（instructions）
   对 GPT-4o mini TTS 系列，可用 instructions 描述音色气质、语气、语速、情绪、停顿与重音等。tts-1 / tts-1-hd 不支持该字段，CLI 会警告并丢弃。

4. 按场景准备的参考模板
   仓库里按用途拆了参考文档：旁白（narration.md）、产品配音（voiceover.md）、IVR（ivr.md）、无障碍朗读（accessibility.md），以及提示词写法（prompting.md、sample-prompts.md）。

5. 输出与限流约定清晰
   默认输出 mp3，也可选 opus、aac、flac、wav、pcm；单次输入不超过 4096 字符；批量请求默认并上限为每分钟 50 次（--rpm 最大 50）。

安装与启用¶

安装 Skill¶

该 Skill 基于通用 SKILL.md 格式，可用 Vercel 的 skills CLI 安装。常用写法：

npx skills add openai/skills --skill speech

按工具分别安装时，可指定 agent，例如：

npx skills add openai/skills --skill speech --agent cursor
npx skills add openai/skills --skill speech --agent codex
npx skills add openai/skills --skill speech --agent claude-code

也可手动克隆仓库，把 skills/.curated/speech 拷到对应工具的 skills 目录。Cursor 常见路径包括项目内 .agents/skills/ 或用户级 ~/.cursor/skills/；Codex 侧 CLI 文档默认把技能放在 $CODEX_HOME/skills/（默认 ~/.codex）。

安装后，在对话里说明「用 speech 把这段文案合成语音」，或按工具习惯用 /speech 等方式显式调用即可。Agent 会根据 Skill 的 description 判断是否触发。

依赖与环境变量¶

真实调用 API 需要：

1. 安装 Python 包 openai（官方优先推荐 uv）：

uv pip install openai

若没有 uv：

python3 -m pip install openai

2. 设置环境变量 OPENAI_API_KEY（在 OpenAI API Keys 创建）。不要把完整密钥贴进聊天，本地设好后告诉 Agent「已配置好」即可。

典型用法示例¶

以下命令来自官方 references/cli.md。先设定 CLI 路径（以 Codex 默认安装位置为例）：

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export TTS_GEN="$CODEX_HOME/skills/speech/scripts/text_to_speech.py"

1. 先 dry-run（不调 API）¶

python "$TTS_GEN" speak --input "Test" --dry-run

--dry-run 只打印请求载荷，不需要网络，也不依赖已安装 openai 包，适合检查参数是否正确。

2. 生成单条旁白¶

uv run --with openai python "$TTS_GEN" speak \
  --input "Today is a wonderful day to build something people love!" \
  --voice cedar \
  --instructions "Voice Affect: Warm and composed. Tone: upbeat and encouraging." \
  --response-format mp3 \
  --out speech.mp3

没有 uv 时：

python "$TTS_GEN" speak --input "Hello" --voice cedar --out speech.mp3

查看可用内置音色：

python "$TTS_GEN" list-voices

官方列出的内置音色包括：alloy、ash、ballad、cedar、coral、echo、fable、marin、nova、onyx、sage、shimmer、verse。

3. 批量生成 IVR 提示音¶

mkdir -p tmp/speech
cat > tmp/speech/jobs.jsonl << 'JSONL'
{"input":"Thank you for calling. Please hold.","voice":"cedar","response_format":"mp3","out":"hold.mp3"}
{"input":"For sales, press 1. For support, press 2.","voice":"marin","instructions":"Tone: clear and neutral. Pacing: slow.","response_format":"wav"}
JSONL

python "$TTS_GEN" speak-batch --input tmp/speech/jobs.jsonl --out-dir out --rpm 50
rm -f tmp/speech/jobs.jsonl

JSONL 每一行可覆盖 model、voice、response_format、speed、instructions、out。官方建议临时文件放在 tmp/speech/，跑完删除，不要提交进仓库；成品可放到 output/speech/ 或用 --out / --out-dir 指定。

4. 给 Agent 的提示写法¶

Skill 要求：先收集「原文（逐字）、音色、风格、格式、约束」，再把风格整理成短标签说明，不要改写原文。例如：

Input text: "Welcome to the demo. Today we'll show how it works."
Instructions:
Voice Affect: Warm and composed.
Tone: Friendly and confident.
Pacing: Steady and moderate.
Emphasis: Stress "demo" and "show".

迭代时一次只改一项（音色、语速或 instructions），便于对比。重要片段合成后，建议人工听一遍：清晰度、节奏、专有名词发音是否符合要求。

适用场景与注意事项¶

适合：

• 产品 Demo / 讲解视频配音
• 应用引导、帮助页、无障碍朗读素材
• 电话 IVR、客服提示音批量出片
• 需要固定音色与参数、可重复跑的自动化流水线

需要注意：

• 必须联网，且配置有效的 OPENAI_API_KEY；离线环境只能 --dry-run。
• 不支持自定义音色创建；只能用内置 voice。
• 单次文本最长 4096 字符，更长内容需拆块或走 batch。
• instructions 仅对 GPT-4o mini TTS 类模型生效；换到 tts-1 / tts-1-hd 时风格指令会被忽略。
• 面向最终用户时，官方要求明确告知「该语音由 AI 生成」。
• 不要修改 scripts/text_to_speech.py；缺能力时先问用户，再决定是否另写脚本。

小结¶

speech Skill 把 OpenAI 文本转语音能力收成一套可安装、可复现的 Agent 工作流：单条用 speak，批量用 JSONL + speak-batch，默认模型和音色明确，并附带旁白、配音、IVR、无障碍等参考模板。对需要频繁做 Demo 配音、提示音或多媒体内容自动化的开发者，比每次临时拼 API 调用更稳。

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