OpenMontage 中的 ElevenLabs Agents 安装与配置实战CLI、多语言 SDK 与密钥管理全指南【免费下载链接】OpenMontageWorlds first open-source, agentic video production system. 12 production pipelines, 100 tools, 700 agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage本篇指南以 OpenMontage 仓库中的 ElevenLabs Agents 安装文档 为骨架系统讲解在语音 AI Agent 与音视频生产场景中接入 ElevenLabs 的完整路径CLI 工具安装与认证、JavaScript / TypeScript 与 Python SDK 的初始化、cURL 直连 REST API 的方式以及 API Key 的获取、存储与环境变量约定。文章同时结合仓库内的 agents 技能、elevenlabs 音频技能 与 elevenlabs_tts 工具实现 等源码证据说明这些安装配置在实际项目语音配音、对话式 Agent、TTS 工具注册中如何落地。读完本文你将能独立完成 ElevenLabs 环境的搭建、身份认证与首次 Agent 创建/语音合成调用。一、总览为什么先解决安装与密钥ElevenLabs 提供语音合成TTS、对话式 AI AgentConversational AI、语音克隆、音效与音乐生成等能力。无论使用哪种能力接入流程都收敛为三件事安装官方客户端CLI / SDK→ 配置ELEVENLABS_API_KEY→ 发起首次调用。原安装文档正是围绕这三件事组织的下面的各节将逐项展开并补充仓库源码中的落地细节。在 OpenMontage 中ELEVENLABS_API_KEY是解锁多个语音类工具的硬前提文档 docs/PROVIDERS.md 明确列出该环境变量对应解锁elevenlabs_tts、music_gen两个工具elevenlabs_tts 工具 的get_status()方法也直接检查os.environ.get(ELEVENLABS_API_KEY)来决定工具是否可用。也就是说配置好密钥后Agent 才能在视频生产流程中自动选用 ElevenLabs 完成配音。二、CLI 安装官方推荐ElevenLabs CLI 是创建和管理 Agent 的推荐方式适用于agents init、agents add、agents push等声明式管理操作。2.1 三种安装方式npm install -g elevenlabs/cli # 或 pnpm add -g elevenlabs/cli # 或 yarn global add elevenlabs/cli安装前提Node.js 16.0.0 或更高版本。npm、pnpm、yarn 三种包管理器任选其一即可全局安装后elevenlabs命令进入 PATH。2.2 认证AuthenticationCLI 安装完成后首先完成身份认证elevenlabs auth login # 使用 API Key 进行认证 elevenlabs auth whoami # 校验当前登录状态 elevenlabs auth logout # 移除已存储的凭据密钥的存储位置为~/.agents/api_keys.json。从安全实践看该文件即本机的凭据锚点auth login将密钥写入此文件whoami读取并校验其有效性logout则删除它。如果涉及团队协作或多环境切换建议仅在个人开发机上执行loginCI/生产环境优先使用环境变量方式见第六节。2.3 快速开始Quick Start# 初始化一个新项目 elevenlabs agents init # 从模板创建一个 Agent elevenlabs agents add My Assistant --template complete # 推送到 ElevenLabs 平台 elevenlabs agents pushagents init会在当前目录生成一套可管理的项目结构agents add基于模板创建 Agent 定义agents push将本地配置上传到 ElevenLabs 云端使其可被对话会话使用。注意push之前必须已经通过auth login完成认证否则会因缺少凭据而失败。--template支持的模板在 agents 技能 中列出包括模板定位complete完整配置的 Agent适合作为新项目起点minimal最小可用配置voice-only纯语音交互text-only纯文本交互customer-service客服场景预设assistant通用助手预设创建后可用elevenlabs agents list查看、elevenlabs agents status检查状态用elevenlabs agents pull可加--agent agent-id拉取单个从平台回导配置用elevenlabs agents push --dry-run预览待上传的变更。2.4 CLI 管理的项目结构agents init之后CLI 生成如下目录结构来自 agents 技能your_project/ ├── agents.json # Agent 定义 ├── tools.json # 工具配置 ├── tests.json # 测试配置 ├── agent_configs/ # 单个 Agent 配置 ├── tool_configs/ # 单个工具配置 └── test_configs/ # 单个测试配置这种总清单 分目录的结构让 Agent、工具、测试可以分别版本化管理改单个 Agent 只需编辑agent_configs/下对应文件再push同步到平台。三、JavaScript / TypeScript SDK对于编程式访问与客户端集成使用官方 JS SDKnpm install elevenlabs/elevenlabs-js重要务必使用elevenlabs/elevenlabs-js。旧的elevenlabsnpm 包v1.x已废弃不应继续使用。初始化客户端有两种方式import { ElevenLabsClient } from elevenlabs/elevenlabs-js; // 方式一环境变量推荐 // 在环境中设置 ELEVENLABS_API_KEY const client new ElevenLabsClient(); // 方式二直接传入 const client new ElevenLabsClient({ apiKey: your-api-key });3.1 从废弃包迁移如果机器上装有旧包先卸载再安装新包# 移除废弃包 npm uninstall elevenlabs # 安装当前包 npm install elevenlabs/elevenlabs-js # 浏览器端/客户端使用另需安装 npm install elevenlabs/client # 浏览器客户端 npm install elevenlabs/react # React Hooks导入语句随之变化import { ElevenLabsClient } from elevenlabs/elevenlabs-js; import { Conversation } from elevenlabs/client; import { useConversation } from elevenlabs/react;3.2 在对话场景中使用初始化后即可创建 Conversational AI Agent示例来自 agents 技能const agent await client.conversationalAi.agents.create({ name: My Assistant, enableVersioning: true, conversationConfig: { agent: { firstMessage: Hello! How can I help?, language: en, prompt: { prompt: You are a helpful assistant., llm: gemini-2.0-flash, temperature: 0.7 } }, tts: { voiceId: JBFqnCBsd6RMkjVDRZzb } } });客户端侧启动会话时服务端先通过conversational_ai.conversations.get_signed_url()换取签名 URL客户端再用Conversation.startSession({ agentId, environment: staging, onMessage, onUserTranscript, onError })连接React 场景则用useConversationHook详见 agents 技能 的 Starting Conversations 一节。四、Python SDKpip install elevenlabsfrom elevenlabs import ElevenLabs # 方式一环境变量推荐 # 在环境中设置 ELEVENLABS_API_KEY client ElevenLabs() # 方式二直接传入 client ElevenLabs(api_keyyour-api-key)Python 客户端在 OpenMontage 中与 TTS 工具链深度绑定仓库的 elevenlabs 音频技能 展示的调用方式是from elevenlabs.client import ElevenLabs并配合client.text_to_speech.convert(...)生成配音、client.voices.ivc.create(...)做即时语音克隆、client.text_to_sound_effects.convert(...)生成音效、client.music.compose(...)生成音乐。Python 侧创建 Agent 的完整示例来自 agents 技能from elevenlabs import ElevenLabs client ElevenLabs() agent client.conversational_ai.agents.create( nameMy Assistant, enable_versioningTrue, conversation_config{ agent: { first_message: Hello! How can I help?, language: en, prompt: { prompt: You are a helpful assistant. Be concise and friendly., llm: gemini-2.0-flash, temperature: 0.7 } }, tts: {voice_id: JBFqnCBsd6RMkjVDRZzb} } )对话开始前服务端换取签名 URLsigned_url client.conversational_ai.conversations.get_signed_url( agent_idyour-agent-id, environmentstaging, )五、cURL / REST API不引入 SDK 时可直接用 REST API。先把 API Key 写入环境变量export ELEVENLABS_API_KEYyour-api-key请求通过xi-api-key请求头携带密钥curl -X POST https://api.elevenlabs.io/v1/convai/agents/create \ -H xi-api-key: $ELEVENLABS_API_KEY \ -H Content-Type: application/json \ -d {name: My Agent, conversation_config: {agent: {prompt: {prompt: You are helpful., llm: gemini-2.0-flash}}, tts: {voice_id: JBFqnCBsd6RMkjVDRZzb}}}要点说明xi-api-key是所有 ElevenLabs REST 请求的统一认证头cURL、SDK 底层都走这一机制。上面的请求体创建了一个名为 My Agent 的 Agentconversation_config.agent.prompt配置 LLM 系统提示词与模型此处为gemini-2.0-flashconversation_config.tts.voice_id指定发音声音。仓库内的 elevenlabs_tts 工具 也是以同样的方式调用 REST 端点https://api.elevenlabs.io/v1/text-to-speech/{voice_id}请求头同样为xi-api-key可作对照参考。六、获取 API Key 与密钥管理在 ElevenLabs 官网注册账号进入API Keys设置页Profile 底部 API Keys点击Create API Key生成新密钥复制并妥善保管密钥只在创建时完整展示一次。文档同时提到可使用setup-api-key技能完成引导式配置在 OpenMontage 中这也与 docs/PROVIDERS.md 描述的供应商密钥管理流程一致——将密钥写入环境变量后工具注册表即可自动识别该供应商并解锁对应工具。环境变量一览变量说明ELEVENLABS_API_KEY你的 ElevenLabs API Key必需仓库实现中对该变量的依赖体现在多处elevenlabs_tts 工具 的execute()开头即检查os.environ.get(ELEVENLABS_API_KEY)缺失时返回失败并附上install_instructions提示设置export ELEVENLABS_API_KEYyour_key_herefal_elevenlabs_tts 工具 则提供了替代路径通过FAL_KEY使用 fal.ai 托管的 ElevenLabs 模型eleven-v3、multilingual-v2、turbo-v2.5无需独立的 ElevenLabs 密钥适合已有 fal.ai 连接、不想单独申请密钥的场景全局配置文件 config.yaml 不存储密钥本身密钥一律走环境变量这符合配置与凭据分离的安全实践。推荐的密钥配置流程# 1. 设置密钥可写入 shell 配置文件或 CI 的 secrets 管理 export ELEVENLABS_API_KEYyour-api-key # 2. 验证工具是否就绪OpenMontage 中 # elevenlabs_tts 的 get_status() 会因该变量存在而返回 AVAILABLE # 3. CLI 场景下也可用 auth login 将密钥持久化到 ~/.agents/api_keys.json elevenlabs auth login七、环境变量与选择器在 OpenMontage 中的落地7.1 TTS 工具注册OpenMontage 采用能力驱动的工具注册机制。tts_selector 工具 会自动从注册表发现所有capability tts的供应商工具——这意味着只要安装了 SDK 并设置好密钥elevenlabs_tts就会进入候选项。该选择器支持preferred_provider: elevenlabs强制优先 ElevenLabsallowed_providers: [elevenlabs, ...]限定候选集合operation: rank只返回供应商评分排序而不实际生成。7.2 可用参数范围与安装后首次调用强相关安装完成后首次调用 TTS 前建议先了解 elevenlabs_tts 工具 的参数约束这些约束来自其input_schema参数默认值取值范围/枚举说明voice_id21m00Tcm4TlvDq8ikWAMRachel—发音声音 IDmodel_ideleven_multilingual_v2—TTS 模型stability0.50–1稳定性越低越有表现力similarity_boost0.750–1声音相似度style0.00–1风格夸张程度speed1.00.7–1.2语速use_speaker_boosttrue—说话人增强output_formatmp3_44100_128mp3_44100_128/mp3_44100_192/pcm_16000/pcm_24000输出编码与采样率该工具的成本估算为每字符约 0.0003 美元estimate_cost()并带 2 次重试策略针对rate_limit、timeout可帮助在批量配音前预估费用。7.3 模型与声音速查在 agents 技能 中Conversational AI 的 LLM 提供商覆盖 OpenAIgpt-5、gpt-4o等、Anthropicclaude-sonnet-4等、Googlegemini-2.5-flash、gemini-2.0-flash等、ElevenLabs 自有模型glm-45-air-fp8、qwen3-30b-a3b、gpt-oss-120b以及custom-llm自带端点。常用声音 ID 包括George温暖旁白JBFqnCBsd6RMkjVDRZzbRachel清晰女声21m00Tcm4TlvDq8ikWAMDanielonwK4e9ZLuTAKqWW03F9CharlotteXB0fDUnXU5powFXDhCwa对话响应时机turn eagerness可配置为patient等待用户说完、normal、eager快速响应。八、常见错误与排障认证与调用环节常见的 HTTP 状态码来自 agents 技能 的 Error Handling 一节状态码含义排查方向401无效的 API Key用elevenlabs auth whoami或直接调用一个轻量接口验证密钥确认环境变量名拼写为ELEVENLABS_API_KEY404资源不存在检查agent_id、voice_id是否正确422配置无效对照conversation_config结构检查请求体429触发限流降低调用频率仓库工具已内置针对rate_limit的重试此外若 CLI 命令报未认证请先执行elevenlabs auth login并确认~/.agents/api_keys.json已生成若 SDK 调用报缺 Key确认环境变量在当前 shell 中已导出新开的终端需要重新export或写入 shell 配置。九、总结一条从安装到首次调用的完整链路将上述内容串联起来ElevenLabs 接入的推荐链路是选通道管理型操作用 CLInpm i -g elevenlabs/cli程序化调用用 JSelevenlabs/elevenlabs-js或 Pythonpip install elevenlabsSDK临时调试用 cURL配密钥export ELEVENLABS_API_KEY...或 CLI 下elevenlabs auth login持久化到~/.agents/api_keys.json验证elevenlabs auth whoami或在 OpenMontage 中确认elevenlabs_tts状态变为可用首次调用CLI 用agents init→agents add→agents pushSDK 用ElevenLabs()客户端创建 Agent 或合成语音在 OpenMontage 中则直接交给tts_selector按能力路由到 ElevenLabs。仓库内可供进一步研读的相关文件安装文档本文主体ElevenLabs Agents 技能总览模板、配置项、工具、Widget 嵌入、外呼电话ElevenLabs 音频生成技能TTS、语音克隆、音效、音乐、Remotion 集成elevenlabs_tts 工具实现REST 调用与参数约束fal_elevenlabs_tts 工具实现经 fal.ai 使用 ElevenLabs 模型的替代方案TTS 能力选择器供应商自动发现与路由供应商与密钥文档各供应商环境变量与解锁工具清单【免费下载链接】OpenMontageWorlds first open-source, agentic video production system. 12 production pipelines, 100 tools, 700 agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考