ElevenLabs TTS Skill 实战指南：基于本地语音配置的可复用文本转语音工作流

【免费下载链接】SkillsAgent skills for designers and builders using Codex, Claude, Cursor, and other AI coding agents项目地址https://gitcode.com/gh_mirrors/skills48/Skills点击查看免费下载本指南以 Skills 仓库中agent-skills/codex/elevenlabs-tts技能下文简称「该技能」为核心系统讲解如何在 Codex、Claude、Cursor 等 AI 编码 Agent 中按需生成 ElevenLabs 文本转语音TTS音频从本地语音配置文件的组织方式、六步执行工作流到配套 generate_voice.py 脚本的全部命令行参数与底层实现。读完本文你将掌握一套「密钥与账号数据不出库、请求级参数灵活覆盖、可复用不泄密」的 TTS 自动化方案并能在自己的项目里直接复现完整调用链。技能定位与设计原则该技能在仓库中位于 SKILL.md其 frontmatter 明确声明了触发语义Generate ElevenLabs text-to-speech audio from scripts or inline text using local voice profiles. Use when the user asks for ElevenLabs, text-to-speech, TTS, narration, voiceover, speech audio, or voice generation; load voice names, voice ids, emails, owners, and account-specific defaults only from local config outside the skill.也就是说当用户提出「ElevenLabs」「TTS」「旁白narration」「配音voiceover」「语音生成」等请求时Agent 应激活该技能。它有两个核心设计约束保持可复用、非个人化reusable and non-personal技能本身不存储任何 API Key、voice name、voice id、邮箱、账号名、客户名或个人默认值运行期从本地读取ELEVENLABS_API_KEY从进程环境变量或最近的.env文件读取账号专属的语音配置从技能之外的本地 JSON 配置文件读取。这带来一个关键的安全与工程原则技能是「纯逻辑模板」账号数据是「本地资产」二者严格分离。这样同一份技能可以被团队、多个项目、多个账号共享而不会把任何敏感信息带入仓库。本地语音配置Local Profiles组织方式与字段说明配置文件来源优先级该技能不限定单一配置路径而是按以下优先级查找顺序靠前者优先生效命令行参数--config /path/to/profiles.json环境变量ELEVENLABS_TTS_CONFIG/path/to/profiles.json用户主目录下的local/elevenlabs/profiles.json。此外项目本地配置文件同样受支持——只要它被.gitignore忽略即可例如config/local/elevenlabs-tts.json。从源码 generate_voice.py 可以看到上述路径的实现DEFAULT_HOME_CONFIG Path.home() / local / elevenlabs / profiles.json PROJECT_CONFIG_PATHS ( Path(config/local/elevenlabs-tts.json), )resolve_config_path的解析顺序与文档一致显式--config或环境变量优先随后依次向上层目录查找config/local/elevenlabs-tts.json借助find_upward从当前目录逐级向上寻找最后回落到用户主目录配置。配置文件 JSON 结构该技能要求本地配置文件采用如下结构文档中的完整示例{ default_profile: default, profiles: { default: { voice_name: Voice name from the local account, voice_id: optional-direct-voice-id, voice_id_env: OPTIONAL_ENV_VAR_WITH_VOICE_ID, model_id: eleven_multilingual_v2, output_format: mp3_44100_128, voice_settings: { stability: 0.5, similarity_boost: 1.0, style: 0.0, speed: 1.0, use_speaker_boost: true }, output_dir: outputs/voiceovers, emails: [] } } }各字段含义与行为如下字段类型作用说明default_profilestring默认选中哪个 profile未通过--profile或ELEVENLABS_TTS_PROFILE指定时的兜底选择profilesobjectprofile 集合键为 profile 名值为 profile 配置对象voice_namestring账号内语音名称当未提供voice_id时脚本通过 ElevenLabs 语音搜索接口按名称精确匹配voice_idstring可选直接指定语音 ID存在时跳过名称搜索直接使用voice_id_envstring可选存放 voice_id 的环境变量名从该环境变量读取真实 voice_id适合把 ID 放进.env而非 JSONmodel_idstring合成模型默认回落到eleven_multilingual_v2output_formatstring输出音频编码格式默认回落到mp3_44100_12844.1kHz、128kbps 的 MP3voice_settingsobject请求级语音参数含stability、similarity_boost、style、speed、use_speaker_boostoutput_dirstring未指定输出路径时的默认目录未设置时回落到outputs/voiceovers/emailsarray本地路由/上下文备注仅用于本地流转脚本会忽略未知元数据字段关于emails、owners所有者、aliases别名、notes备注等字段文档明确说明它们仅用于本地路由与上下文脚本忽略未知元数据字段。因此你可以放心地在配置里加入团队路由信息而不会影响生成逻辑。profile 选择逻辑的源码细节select_profile 的实现揭示了两个贴心行为若配置中只有一个 profile即使没有default_profile也会自动选中它若有多个 profile 且未指定会抛出错误并列出全部可用 profile 名提示用--profile选择。也就是说多账号场景下必须显式指定--profile避免歧义。六步执行工作流SKILL.md 给出了 Agent 执行 TTS 的标准流程共六步选择 profile依次取--profile参数、ELEVENLABS_TTS_PROFILE环境变量最后回落default_profile优先使用助手脚本调用python3 skill-root/scripts/generate_voice.py --text-file script.txt --profile default --output output.mp3解析 voice_idprofile 有voice_id则直接使用有voice_id_env则读取对应环境变量否则按voice_name调用 ElevenLabs 语音搜索接口查询应用模型与参数使用 profile 的model_id、output_format、voice_settings除非用户对本次生成显式覆盖确定输出位置写入用户指定目标未指定时先用 profile 的output_dir再回落outputs/voiceovers/汇报结果报告输出路径与重要警告绝不打印任何密钥。这套流程把「账号数据解析」与「请求构建」解耦所有账号敏感信息只在第 1、3 步从本地配置中解析第 46 步完全基于解析结果工作。助手脚本完整参数手册仓库提供了开箱即用的 CLI 助手 generate_voice.py覆盖三种文本输入方式、profile 选择、一次性覆盖、试运行与语音列表等能力参数说明--text ...内联文本直接合成--text-file path.txt从 UTF-8 文本文件读取脚本无参数时读取 stdin 管道输入当两者都未提供且非 TTY 时--profile name选择本地 profile--config path.json指定本地 profile 配置文件--voice-id一次性显式指定 voice id--voice-name未设置 id 时按名称搜索的语音名--model-id覆盖模型默认取 profile 值再回落eleven_multilingual_v2--output-format覆盖输出格式默认取 profile 值再回落mp3_44100_128--settings-json本次生成的voice_settingsJSON 覆盖--output path.mp3指定输出文件路径--env-file指定.env文件路径默认找当前目录最近的.env--seed N可选 seed用于尽力而为的重复可生成性--dry-run只打印解析后的请求负载不调用 TTS 端点--list-voices列出匹配的 ElevenLabs 语音不生成音频文本输入的三种方式read_text 的优先级为--text→--text-file→ stdin 管道。三种均未提供且 stdin 是 TTY 时会报错提示空文本strip 后为空也会被拒绝。这意味着该脚本既能嵌入 Shell 管道也能直接处理剧本文件# 方式一内联文本 python3 scripts/generate_voice.py --text Hello from ElevenLabs --profile default # 方式二脚本文件 python3 scripts/generate_voice.py --text-file script.txt --profile narrator # 方式三stdin 管道 cat script.txt | python3 scripts/generate_voice.py --profile default请求级覆盖与 voice_settings 合并针对「不改动账号保存设置」的约束脚本实现了三层合并机制见 profile_settings先取 profile 中的voice_settings再叠加环境变量ELEVENLABS_TTS_SETTINGS_JSON最后叠加命令行--settings-json优先级最高。这样既保证了 profile 的默认风格又允许单次生成临时调整且不会回写任何已保存的 ElevenLabs 账号设置。试运行与语音查询--dry-run会打印包含config_path、profile、voice_id、voice_name、解析到的真实语音名、输出路径、output_format与完整 payload 的 JSON方便你在正式合成前核对配置与负载非常适合调试与 CI 检查。--list-voices则调用语音列表接口逐行输出voice_idTABvoice_name可直接用于确认账号内语音名是否正确、是否有重名python3 scripts/generate_voice.py --voice-name Rachel --list-voices python3 scripts/generate_voice.py --dry-run --text preview --profile default底层调用链与优先级解析环境变量与 .env 加载load_env 的规则是以进程环境变量为基底--env-file指定或find_env_file从当前目录向上查找最近的.env找到的文件内容以setdefault方式补充——即进程环境变量优先于.env文件。parse_env_file 支持#注释行、KEYVALUE语法并自动剥离值的引号。API Key 缺失时脚本会直接报错Missing ELEVENLABS_API_KEY in the environment or nearest .env file.voice_id 解析优先级main 中 voice_id 的完整解析链为--voice-id命令行参数ELEVENLABS_TTS_VOICE_ID环境变量profile 中voice_id_env指向的环境变量profile 中的voice_id。当最终既无voice_id也无voice_name时脚本会提示在配置、环境变量或 CLI 中至少设置其一。若只能按名称搜索resolve_voice_id 会调用/v2/voices接口并执行精确名称匹配找不到同名语音时报错并列出接口返回的可选语音名重名时报错并列出候选 voice_id提示在配置中显式指定其一。同理model_id与output_format也遵循「CLI 参数 → 环境变量ELEVENLABS_TTS_MODEL_ID/ELEVENLABS_TTS_OUTPUT_FORMAT→ profile 值 → 内置默认值」的回落链。请求负载与输出路径合成请求由 api_audio 发出payload 包含text、model_id可选voice_settings与seed输出格式以查询参数output_format传递请求头携带xi-api-key与Accept: audio/mpeg。未指定--output时文件名由 default_output_path 生成{profile名或语音名slug化}-{YYYYmmdd-HHMMSS}.mp3写入 profile 的output_dir回落outputs/voiceovers/目录不存在时自动创建。成功后会打印写入路径与字节数网络或 HTTP 错误会被包装为带 API 详情错误码与响应体的ElevenLabsError超时阈值为 90 秒。API 端点与鉴权SKILL.md 明确要求使用当前 ElevenLabs 端点脚本中由API_BASE https://api.elevenlabs.io与路径拼接实现语音搜索GET /v2/voices支持search与page_size参数resolve_voice_id使用page_size100语音合成POST /v1/text-to-speech/:voice_id?output_format...鉴权方式为请求头xi-api-key值即ELEVENLABS_API_KEY。演示与验证从输入到交付物技能目录下的 demo 提供了一套可复现的验证样例展示了「输入脚本 → 音频交付物」的完整闭环PROMPT.md 是复刻演示的 Agent 提示词要求用$elevenlabs-tts构建一个响应式、无构建步骤、仅内联 CSS/JS 的独立 HTML 参考演示input.md 是虚构的配音脚本源数据旁白文案、指定「中性产品叙述者」语音、输出 MP3 与 WAVexpected-output.md 是验证过的交付物清单本地语音配置已解析且未暴露账号数据、MP3 与 WAV 已生成、时长与文件类型已验证、旁白文案已检查裁剪与意外停顿index.html 以深色界面将「Example input / Expected output」左右对照呈现并明确标注「Portable fictional example. No live account or customer data.」——这正是前文「输入输出交接、证据优先」工作流的可视化表达。该样例同时提示了交付质检的四个关注点账号数据不可见、多格式输出、时长与文件类型校验、语音剪辑与停顿检查可作为实际生产交付的自检清单。安全边界与最佳实践综合文档与源码落地这套 TTS 技能时应遵守以下边界密钥隔离ELEVENLABS_API_KEY只存在于环境变量或.env且.env必须被 gitignore配置文件中如需引用 voice_id优先用voice_id_env间接引用环境变量账号数据隔离voice name、voice id、邮箱、所有者等一律放本地 JSON 配置禁止写入技能本身只读账号设置所有voice_settings均为请求级覆盖通过「profile → 环境变量 → CLI」三层合并生效绝不回写账号已保存的设置先行验证生成前用--dry-run核对解析结果用--list-voices确认语音名避免对账号产生不必要的 API 调用项目本地配置若需随项目携带配置放入 gitignore 的config/local/elevenlabs-tts.json即可脚本会自动从当前目录向上查找。至此你已掌握该技能从配置组织、六步工作流、CLI 全参数到源码级调用链的完整脉络可直接在任意 AI 编码 Agent 项目中复现这套安全、可复用、请求级可覆盖的 ElevenLabs TTS 语音生成方案。赞分享【免费下载链接】SkillsAgent skills for designers and builders using Codex, Claude, Cursor, and other AI coding agents项目地址https://gitcode.com/gh_mirrors/skills48/Skills点击查看免费下载相关推荐PowerInfer 本地部署 TTS基于 OuteTTS 与 WavTokenizer 的文本转语音完整实战指南PowerInfer 本地部署 TTS基于 OuteTTS 与 WavTokenizer 的文本转语音完整实战指南 本文聚焦 PowerInfer 仓库中 s人工智能大模型推理引擎本地部署用 mistral.rs 的 SpeechModelBuilder 实现本地文本转语音TTSDia 语音模型完整实战指南用 mistral.rs 的 SpeechModelBuilder 实现本地文本转语音TTSDia 语音模型完整实战指南 导读 本文聚焦 mistral.推理引擎模型推理服务AI Agent多模态多语言TTS开发实战基于espeak-ng的本地化语音包制作多语言TTS开发实战基于espeak ng的本地化语音包制作 你是否还在为多语言文本到语音TTS应用开发中的本地化语音包问题烦恼本文将带你一步步完成基于语音音频上一篇DuckDB并行查询执行多线程如何加速复杂分析任务下一篇Llama Models 实战5 分钟跑通对话推理4 卡扛住 Llama 4 多模态创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考