技能使用指南

speech（语音生成技能）Skill 是什么？如何一键安装并批量生成语音？

语音生成技能 speech Skill 基于 OpenAI 音频 API，默认模型与内置语音开箱可用，支持单次与 JSONL 批量文本转语音，内置指令增强、场景模板与输出约定，适用于演示旁白、IVR 提示与无障碍朗读。本文详解安装前提、使用步骤、竞品对比与常见问题，帮你快速把文字变成可发布音频。

语音生成技能Skill"speech"
8 个章节 约 14 分钟阅读 AI 智能生成

语音生成技能：让 AI 把你的文字变成可直接发布的旁白音频

  • 一句话定位：一个围绕 OpenAI 音频 API 构建的文本转语音（TTS）技能，用捆绑的命令行工具把文本稳定地变成旁白、演示配音、IVR 提示和可访问性朗读音频。
  • 默认开箱可用：默认模型 gpt-4o-mini-tts-2025-12-15，默认语音 cedar，想要更明亮的音调可切换 marin，无需自己摸索参数组合。
  • 单次与批量都覆盖：一段话生成一个文件，或用 JSONL 一次性生成几十条提示音，适合需要反复出稿的工程项目。
  • 有明确边界：仅支持内置语音，不支持自定义音色克隆；单次输入不超过 4096 字符，速率被限制在 50 请求/分钟。
  • 前置条件清晰：实时调用必须有 OPENAI_API_KEY，依赖只需安装 openai 一个 Python 包。

该技能叫什么？如何一键安装 AI 技能提升开发效率？

这个技能的中文名是语音生成技能，英文名是 speech，技能 ID 为 12048。它要解决的问题很具体：当你需要一段"能听"的音频——产品演示旁白、课程叙述、电话语音提示、无障碍朗读——时，不必再打开网页版工具逐条复制粘贴，也不必自己从零写一套调用脚本，而是把文本交给技能，由它按统一的规则调用 OpenAI 音频 API 产出音频文件。

它和"临时写个脚本"的最大区别在于一致性。 技能内置了决策流程（先判断单次还是批量）、默认模型与语音、指令增强模板、输出目录约定和验证步骤，同样一段文本，今天跑和下周跑得到的结果是可控、可复现的。

安装思路上，AI 技能通常分两层：技能本体和运行依赖。

  1. 准备运行环境：需要一个可用的 Python 环境，并推荐使用 uv 做依赖管理。技能详情明确给出的依赖安装方式是 uv pip install openai；如果你的环境里没有 uv，则使用 python3 -m pip install openai 作为备选。
  2. 配置密钥：实时调用必须设置环境变量 OPENAI_API_KEY。密钥需在 OpenAI 平台的 API Keys 页面自行创建（地址见技能说明），然后在本地终端或系统环境变量中设置。请不要把完整密钥粘贴到聊天窗口里，技能本身也明确要求只让你在本地设置并确认就绪。
  3. 安装技能本体：在支持该技能的平台中按官方入口添加或启用技能，具体命令与入口以官方说明为准。启用后，确认技能目录下存在捆绑脚本 scripts/text_to_speech.py，以及 references/ 下的参考文档。
  4. 验证是否生效：先用一段两句话的短文本发起一次单次生成，指定 --out 输出路径；若能正常产出音频文件，且文件名、格式符合预期，说明技能与密钥都已打通。若报错，优先检查三项：OPENAI_API_KEY 是否在当前终端会话中可见、openai 包是否装在当前解释器、网络/沙箱是否拦截了外部请求。

该技能的主要功能和特点

  • 文本转语音的完整闭环：从接收文本、增强指令、调用 API、落盘保存到结果验证，形成一条流水线，而不是只提供一个 API 调用点。
  • 单次与批量双模式：技能内置决策树——用户给出多行文本或多个提示时走批量；否则走单次。批量模式下会在 tmp/speech/ 下生成临时 JSONL（每行一个任务），跑完即删，避免仓库被中间文件污染。
  • 默认值经过挑选：默认模型 gpt-4o-mini-tts-2025-12-15，默认语音 cedar，需要更明亮音色时优先 marin。初学者不必懂参数也能出可用结果。
  • 指令增强而非改写：把用户模糊的描述（如"演示的叙述"）转成带标签的规范，例如"语音影响 / 语气 / 节奏 / 情感 / 发音 / 停顿 / 强调 / 交付"，只把隐含细节显性化，绝不改写原文本、不新增人物与口音。
  • 按场景提供参考模板：叙述与解说、产品演示旁白、IVR 电话提示、可访问性朗读四类场景各自有对应的参考文档，给出针对性默认值和模板。
  • 输出路径可约定：通过 --out 或 --out-dir 控制产物位置；在本仓库中工作时，最终成品写入 output/speech/，中间文件写入 tmp/speech/。
  • 可控的成本与稳定性护栏：单请求输入 ≤ 4096 字符，超长文本需分块；CLI 把 --rpm 限制在 50，强制执行每分钟 50 请求上限。
  • 合规提示内置：要求向最终用户明确披露"语音为 AI 生成"。

和普通工具相比，它强在"把最佳实践固化成流程"：你不用记住哪个模型支持 instructions（gpt-4o-mini-tts-2025-12-15 支持，tts-1 / tts-1-hd 不支持），也不用纠结该不该用原始 HTTP 请求——技能明确规定所有调用走 OpenAI Python SDK，并且优先使用捆绑 CLI，不要另写一次性脚本，也不要修改 scripts/text_to_speech.py。

如何使用该技能？

第 1 步：明确意图。 先判断是单次还是批量。只给一段文本 → 单次；给了多行提示或明确要多份音频 → 批量。

第 2 步：收集输入。 技能会要求你把信息一次说清：精确的逐字文本、期望语音、交付风格、音频格式和任何约束。文本务必逐字确认，避免生成后才发现漏句。

第 3 步：增强指令。 把口语化要求整理成简短带标签的规范，控制在 4 到 8 行，避免自相矛盾的描述。以技能给出的单次示例为参考：

输入文本：“欢迎来到演示。今天我们将展示它是如何工作的。”
指令：
语音影响：温暖且沉着。
语气：友好且自信。
节奏：稳定且适中。
强调：强调“演示”和“展示”。

第 4 步：执行生成。 调用捆绑 CLI scripts/text_to_speech.py，用 --voice 指定音色、--out 指定输出文件、--response_format 指定格式（如 mp3、wav），用 --instructions 传入上面的指令规范。完整命令与标志写法参见技能内的 references/cli.md。

第 5 步：批量场景改用 JSONL。 在 tmp/speech/ 下写入每行一个任务的 JSONL，一次运行完成全部生成，随后删除临时文件。示例：

{"input":"感谢您的来电。请稍候。","voice":"cedar","response_format":"mp3","out":"hold.mp3"}
{"input":"销售请按1。支持请按2。","voice":"marin","instructions":"语气：清晰且中立。节奏：慢。","response_format":"wav"}

第 6 步：验证成品。 对重要片段逐条检查四项：可理解性、节奏、发音、约束遵守情况。人名与缩写建议在文本里加发音提示，例如"清晰发音 A-I"。

第 7 步：单点迭代。 不满意时一次只改一个变量——只换语音、只调速度或只调指令——然后重新检查。批量返工时要重复不变条件（如"保持节奏稳定"）以减少漂移。

第 8 步：交付与记录。 把成品写入 output/speech/，文件名保持稳定且具描述性，并记录最终文本、指令和使用的标志，方便日后复现。最后提醒听众：这段语音由 AI 生成。

同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
语音生成技能（speech） 面向项目交付的 TTS 工作流技能 单次/批量生成、指令增强、场景模板、输出约定、结果验证 需 Python 环境与 OPENAI_API_KEY；安装 openai 包；技能添加入口以官方说明为准 演示旁白、课程叙述、IVR 提示、无障碍朗读 优势：流程规范、可复现、批量省事；不足：仅内置语音，不支持自定义音色，超 4096 字符需分块
自行编写 API 调用脚本 通用开发路径 直接调用音频 API，参数自由组合 需自行处理鉴权、分块、重试、限速、落盘 高度定制化、需嵌入自有系统 优势：完全可控；不足：前期投入大，指令写法与验证规范要自己踩坑，容易每次结果不一致
云厂商语音合成服务 商业 TTS 平台 多音色、多语言、控制台试听与调参 需开通账号与服务，按官方计费 企业级客服、播报系统 优势：音色库大、有 SLA；不足：接入与计费门槛高，切换成本大，与当前 AI 工作流分离
本地开源 TTS 引擎 离线自托管方案 本地推理，无需外部 API 需自行部署模型与算力 内网、隐私敏感、离线环境 优势：数据不出内网；不足：音质与自然度参差，部署与调优成本高，缺乏现成的批量规范

从上表可以看出：如果你追求"开箱即用的自然度 + 工程化的稳定流程"，本技能路径最短；如果必须离线或必须使用自有音色，则本地开源或自建方案更合适。

该技能的典型应用场景与实际体验情况

场景一：产品演示与宣传视频的旁白。 视频制作同学拿到脚本后逐句配音，往往要反复试音、反复导出。使用本技能时，把整段脚本按段拆成 JSONL 批量生成，统一用 cedar 音色和"温暖且沉着、节奏稳定"的指令，十几条旁白一次出齐。实际体验：上手难度低，默认值基本可用；注意批量返工时务必重复相同的不变条件，否则不同批次之间会出现语气漂移。

场景二：在线课程与知识付费的叙述音频。 讲师只想要"像人念稿"的效果，不想折腾参数。技能给出的叙述模板和"影响 → 语气 → 节奏 → 情感 → 发音/停顿 → 强调"的指令结构正好匹配。实际体验：把指令压到 4 到 8 行时效果最稳，写太长反而互相冲突；章节较长时需要按 4096 字符上限分块，并在块与块之间保持同样的指令。

场景三：IVR 与电话语音提示。 客服系统需要"销售请按 1。支持请按 2。"这类固定短句，格式多为 wav。用技能提供的 IVR 参考模板与 JSONL 批量模式最合适，文件名按 hold.mp3、menu.wav 这样的稳定规则命名便于系统引用。实际体验：短句生成速度快、清晰度好；但数字、按键提示一定要做发音校验，避免"1"读成别的音。

场景四：无障碍阅读与音频提示。 为文档生成朗读音频，需要清晰、无情绪化渲染、语速偏慢。技能的可访问性阅读模板给出了针对性默认值，并明确要求披露音频为 AI 生成，这一点在面向公众的产品里很重要。实际体验：整体流程顺畅，主要注意事项是合规披露与文本清洗——把代码块、表格符号等不适合朗读的内容先剔除。

该技能能为用户带来的价值

第一，把"会写脚本"变成"会提需求"。 过去生成一段合格旁白，你需要懂模型选择、鉴权、分块、限速和指令写法；现在这些都被技能固化成默认值和流程，只需提供文本和一句交付风格描述。

第二，把"一次性成功"变成"可持续复现"。 技能要求记录最终文本、指令与标志，迭代时坚持单一变量修改。这意味着团队里换个人接手，也能按记录跑出接近的结果，而不是重头猜。

第三，批量场景的时间收益最直接。 一份 20 条的电话提示音，网页版逐条操作可能占用大量碎片时间；用 JSONL 一次提交、一次运行、跑完删除临时文件，只剩下最终产物，节省的是重复劳动与整理成本。

第四，风险更低。 4096 字符上限与 50 请求/分钟的限速是显性护栏，避免无意中超长请求或瞬时超速；严禁修改捆绑脚本、禁止用原始 HTTP 调用、密钥不上聊天窗口，这些约束共同降低了"看起来能跑、线上翻车"的概率。

第五，长期价值在于规范沉淀。 指令模板、场景参考文档、输出目录约定会随着项目复用不断被继承，团队越用越顺手。

常见问题 FAQ

Q1：这个技能怎么安装？需要准备什么？ 需要三样东西：可用的 Python 环境、OPENAI_API_KEY 环境变量、以及通过官方入口添加本技能（具体入口与命令以官方说明为准）。依赖只需安装 openai 包，推荐 uv pip install openai，没有 uv 时用 python3 -m pip install openai。装好后用一段两句话的短文本跑一次单次生成，能正常产出音频即视为生效。

Q2：使用它收费吗？ 技能本身是一个调用封装，真正的计费来自 OpenAI 音频 API 的实际调用，价格请以 OpenAI 官方说明为准。技能侧的成本控制手段是明确写在规则里的：单请求输入不超过 4096 字符、请求速率限制在 50 请求/分钟，批量前建议先确认条数。

Q3：可以克隆我自己的声音吗？ 不可以。技能明确说明仅支持内置语音，自定义语音创建超出范围。默认语音是 cedar，需要更明亮的音调时优先使用 marin。

Q4：适合谁用？和直接调 API 或云厂商 TTS 怎么选？ 适合需要稳定产出旁白、演示配音、IVR 提示和无障碍朗读的开发者和内容团队。如果你希望流程可复现、还要批量出稿，选本技能最省事；如果必须使用自有音色或必须离线运行，本技能不覆盖，需要另选方案；如果企业需要大规模多语言音色库与商业 SLA，可评估云厂商服务，具体能力与计费以各家官方说明为准。

Q5：生成的中文或长文本有问题怎么办？ 先确认文本是否逐字准确、是否需要加发音提示（如缩写、数字按键）；再检查指令是否过长或自相矛盾，建议压到 4 到 8 行；长文本必须按 4096 字符分块，并保持块间指令一致。迭代时一次只改语音、速度或指令中的一项，改完重新检查可理解性、节奏、发音和约束遵守情况。