SuperAPI AI 工具集

speech

通用与其它

查看项目

更新于 10-16 09:37

技能介绍

语音生成技能(Speech Generation Skill)用于为当前项目生成口播音频,包含旁白、产品演示配音、IVR 提示音与可访问性朗读等用途。默认使用 gpt-4o-mini-tts-2025-12-15 模型与内置音色,并优先采用随附的 CLI,以获得确定、可复现的运行结果。

一、适用场景

  • 从文本生成单条语音片段
  • 生成一批提示(多行文本、多文件)

二、单条与批量的判断

  • 如果用户提供了多行文本/提示,或希望得到多个输出,则走批量流程
  • 否则走单条流程

三、工作流程

  1. 先确定意图:单条还是批量(见上面的判断规则)
  2. 提前收集输入:精确文本(逐字)、目标音色、表达风格、格式及任何约束
  3. 如果是批量:在 tmp/ 下写一个临时 JSONL(每行一个任务),运行一次,然后删除该 JSONL
  4. 将指令补充为一段简短的带标签规格,但不改写输入文本
  5. 使用合理默认值运行随附 CLI(scripts/text_to_speech.py)(参见 references/cli.md)
  6. 对重要片段进行校验:可懂度、节奏、发音以及对约束的符合度
  7. 每次只做一处针对性修改(音色、速度或指令),然后重新检查
  8. 保存/返回最终输出,并注明最终文本、指令与所用参数

四、临时文件与输出约定

  • 中间文件使用 tmp/speech/(例如 JSONL 批次),完成后删除
  • 在本仓库工作时,最终产物写入 output/speech/
  • 使用 --out 或 --out-dir 控制输出路径;保持文件名稳定且具描述性

五、依赖安装(缺失时安装)

  • 优先使用 uv 进行依赖管理
  • Python 包:uv pip install openai
  • 若 uv 不可用:python3 -m pip install openai

六、环境要求

  • 真实 API 调用必须设置 OPENAI_API_KEY
  • 若缺少该密钥,向用户提供以下步骤:
    1. 在 OpenAI 平台界面创建 API 密钥:https://platform.openai.com/api-keys
    2. 在其系统中将 OPENAI_API_KEY 设置为环境变量
    3. 如需,可提出引导用户按其操作系统/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:环境/沙箱/网络审批故障排查