语音生成技能(Speech Generation Skill)用于为当前项目生成口播音频,包含旁白、产品演示配音、IVR 提示音与可访问性朗读等用途。默认使用 gpt-4o-mini-tts-2025-12-15 模型与内置音色,并优先采用随附的 CLI,以获得确定、可复现的运行结果。
一、适用场景
- 从文本生成单条语音片段
- 生成一批提示(多行文本、多文件)
二、单条与批量的判断
- 如果用户提供了多行文本/提示,或希望得到多个输出,则走批量流程
- 否则走单条流程
三、工作流程
- 先确定意图:单条还是批量(见上面的判断规则)
- 提前收集输入:精确文本(逐字)、目标音色、表达风格、格式及任何约束
- 如果是批量:在 tmp/ 下写一个临时 JSONL(每行一个任务),运行一次,然后删除该 JSONL
- 将指令补充为一段简短的带标签规格,但不改写输入文本
- 使用合理默认值运行随附 CLI(scripts/text_to_speech.py)(参见 references/cli.md)
- 对重要片段进行校验:可懂度、节奏、发音以及对约束的符合度
- 每次只做一处针对性修改(音色、速度或指令),然后重新检查
- 保存/返回最终输出,并注明最终文本、指令与所用参数
四、临时文件与输出约定
- 中间文件使用 tmp/speech/(例如 JSONL 批次),完成后删除
- 在本仓库工作时,最终产物写入 output/speech/
- 使用 --out 或 --out-dir 控制输出路径;保持文件名稳定且具描述性
五、依赖安装(缺失时安装)
- 优先使用 uv 进行依赖管理
- Python 包:uv pip install openai
- 若 uv 不可用:python3 -m pip install openai
六、环境要求
- 真实 API 调用必须设置 OPENAI_API_KEY
- 若缺少该密钥,向用户提供以下步骤:
- 在 OpenAI 平台界面创建 API 密钥:https://platform.openai.com/api-keys
- 在其系统中将 OPENAI_API_KEY 设置为环境变量
- 如需,可提出引导用户按其操作系统/shell 设置该环境变量
- 绝不要让用户在聊天中粘贴完整密钥。请其在本地设置并在准备好后确认
- 如果当前环境无法安装,告知用户缺少哪个依赖以及如何在本地安装
七、默认值与规则
- 除非用户要求其他模型,否则使用 gpt-4o-mini-tts-2025-12-15
- 默认音色:cedar。如果用户想要更明亮的音色,优先用 marin
- 仅使用内置音色。自定义音色不在本技能范围内
- GPT-4o mini TTS 模型支持 instructions,但 tts-1 或 tts-1-hd 不支持
- 每次请求输入长度必须 <= 4096 字符。更长的文本需拆分
- 强制每分钟 50 个请求。CLI 将 --rpm 上限设为 50
- 任何真实 API 调用前都需要 OPENAI_API_KEY
- 向最终用户提供清晰披露,说明语音为 AI 生成
- 所有 API 调用使用 OpenAI Python SDK(openai 包);不要使用原始 HTTP
- 优先使用随附 CLI(scripts/text_to_speech.py),而不是另写一次性脚本
- 绝不修改 scripts/text_to_speech.py。如果缺少什么,先询问用户再行动
八、指令补充(Instruction augmentation) 将用户指示改写为简短的带标签规格。只把隐含细节显式化;不要编造新要求。 快速区分(补充 vs 编造):
- 如果用户说“为演示做旁白”,你可以补充隐含的表达约束(清晰、稳定节奏、友好语气)
- 不要引入用户未要求的新人设、口音或情绪风格
模板(只包含相关行):
- Voice Affect: <语音的整体特征与质感>
- Tone: <态度、正式程度、温暖度>
- Pacing: <缓慢、稳定、轻快>
- Emotion: <要传达的关键情绪>
- Pronunciation: <需要清晰发音或强调的词>
- Pauses: <在何处加入有意的停顿>
- Emphasis: <需要重读的关键词或短语>
- Delivery: <语调或节奏说明>
补充规则:
- 保持简短;只添加用户已暗示或已提供的细节
- 不要改写输入文本
- 如果有任何关键细节缺失并阻碍成功,提出一个问题;否则继续
九、示例 单条示例(旁白) 输入文本:“Welcome to the demo. Today we'll show how it works.” 指令:
- Voice Affect: Warm and composed.
- Tone: Friendly and confident.
- Pacing: Steady and moderate.
- Emphasis: Stress “demo” and “show”.
批量示例(IVR 提示音) {"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"}
十、指令编写最佳实践(简要)
- 按以下结构组织指示:affect -> tone -> pacing -> emotion -> pronunciation/pauses -> emphasis
- 保持 4 到 8 条短行;避免相互冲突的指引
- 对于姓名/缩写,添加发音提示(例如“enunciate A-I”)或在文本中提供音标拼写
- 编辑/迭代时,重复不变量(例如“keep pacing steady”)以减少漂移
- 用单处修改的后续调整进行迭代
- 更多原则:references/prompting.md。可复制粘贴的规格:references/sample-prompts.md
十一、按使用场景的指引 当请求针对特定表达风格时使用这些模块。它们提供针对性的默认值与模板。
- 旁白/解说:references/narration.md
- 产品演示/配音:references/voiceover.md
- IVR/电话提示音:references/ivr.md
- 可访问性朗读:references/accessibility.md
十二、CLI 与环境说明
- CLI 命令与示例:references/cli.md
- API 参数速查:references/audio-api.md
- 指令模式与示例:references/voice-directions.md
- 如果网络审批/沙箱设置造成阻碍:references/codex-network.md
十三、参考文件地图
- references/cli.md:如何通过 scripts/text_to_speech.py 运行语音生成/批量(命令、参数、配方)
- references/audio-api.md:API 参数、限制、音色列表
- references/voice-directions.md:指令模式与示例
- references/prompting.md:指令最佳实践(结构、约束、迭代模式)
- references/sample-prompts.md:可复制粘贴的指令配方(仅为示例;不含额外理论)
- references/narration.md:旁白与解说的模板与默认值
- references/voiceover.md:产品演示配音的模板与默认值
- references/ivr.md:IVR/电话提示音的模板与默认值
- references/accessibility.md:可访问性朗读的模板与默认值
- references/codex-network.md:环境/沙箱/网络审批故障排查