前言¶
做產品 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/ 文檔，主要能力如下：
-
單條與批量兩條路徑
一條文案走speak；多行/多文件走speak-batch（臨時 JSONL，一行一個任務）。Skill 裏有明確的決策樹，避免 Agent 每次臨時寫腳本。 -
自帶可復現 CLI
入口是scripts/text_to_speech.py，支持speak、speak-batch、list-voices。官方要求優先用這個 CLI，不要擅自改腳本，也不要另寫一次性gen_audio.py（除非用戶明確要求）。 -
風格指令（instructions）
對 GPT-4o mini TTS 系列，可用instructions描述音色氣質、語氣、語速、情緒、停頓與重音等。tts-1/tts-1-hd不支持該字段，CLI 會警告並丟棄。 -
按場景準備的參考模板
倉庫裏按用途拆了參考文檔：旁白（narration.md）、產品配音（voiceover.md）、IVR（ivr.md）、無障礙朗讀（accessibility.md），以及提示詞寫法（prompting.md、sample-prompts.md）。 -
輸出與限流約定清晰
默認輸出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 需要：
- 安裝 Python 包
openai（官方優先推薦uv）：
uv pip install openai
若沒有 uv：
python3 -m pip install openai
- 設置環境變量
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
