ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

OpenMontage 实战:使用 ElevenLabs Conversation Widget 将语音 AI 代理嵌入任意网站

OpenMontage 实战:使用 ElevenLabs Conversation Widget 将语音 AI 代理嵌入任意网站 OpenMontage 实战使用 ElevenLabs Conversation Widget 将语音 AI 代理嵌入任意网站【免费下载链接】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 项目中 agents 技能体系 的落地一环通过 ElevenLabs 官方elevenlabs-convaiWeb Componentconversation widget把语音 AI 代理以一段 HTML 的形式嵌入任何网页为站点提供可点击、可对话的实时语音交互能力。读完本文你将掌握从基础嵌入、外观与行为定制、CSS 样式覆盖到 JavaScript 程序化控制、signed URL 认证、移动端适配与主流前端框架React / Vue / Next.js集成的完整方案并能结合仓库中的 ElevenLabs 工具与 provider 配置完成端到端落地。一、Widget 是什么从 Agent 到网页的一步在 OpenMontage 的 agents 技能 中ElevenLabs Agents 平台负责构建具备自然对话能力的语音 AI 代理——支持多 LLM 提供商、自定义工具与网页嵌入。而 conversation widget 正是网页嵌入这最后一公里的官方实现它是一个浏览器端的自定义元素custom element加载后会在页面右下角渲染一个悬浮按钮用户点击即可开启一段语音对话整个过程不需要你编写任何 WebRTC 或音频流代码。它的工作方式很简单elevenlabs-convai agent-idyour-agent-id/elevenlabs-convai script srchttps://unpkg.com/elevenlabs/convai-widget-embed async typetext/javascript/script第一行声明 widget 并指定要绑定的 agent第二行异步加载官方打包脚本。脚本就绪后elevenlabs-convai元素会自动升级为可交互的悬浮语音按钮。重要前提Widget 目前要求 agent 是公开的且关闭认证authentication disabled。如果你的 agent 启用了认证请改用 SDKPython / JS方式或使用下文签名 URL 认证一节中的方案。二、Widget 属性总览widget 的全部定制能力都通过 HTML 属性attribute暴露分为四类。2.1 必需属性属性说明agent-id你的 ElevenLabs agent ID在 ElevenLabs 平台创建 agent 后获得signed-url使用签名 URL 时替代agent-id传入的认证链接2.2 外观属性属性说明默认值avatar-image-urlagent 头像图片 URLElevenLabs 官方 logoavatar-orb-color-1头像光球渐变主色#2792dcavatar-orb-color-2头像光球渐变副色#9ce6e62.3 文本标签属性属性说明默认值action-text悬浮提示tooltip文案Talk to AIstart-call-text开始通话按钮文案Start callend-call-text结束通话按钮文案End callexpand-text展开聊天面板按钮文案Opencollapse-text收起聊天面板按钮文案Closelistening-text聆听中状态文案Listening...speaking-text说话中状态文案Assistant speaking2.4 行为属性属性说明默认值variantWidget 形态compact悬浮按钮或expanded展开面板compactserver-location服务区域us、eu-residency、in-residency、globalusdismissible是否允许用户最小化 widgetfalsedisable-banner是否隐藏 Powered by ElevenLabs 标识falseserver-location用于选择语音流处理所在区域欧盟/印度等有数据驻留要求的场景应选用对应区域disable-banner与平台合规相关开启前请确认你的使用场景允许隐藏品牌标识。三、五种开箱即用的嵌入示例原文档提供了从简单到完整的五组示例直接复制即可运行自定义头像——把默认 logo 换成你自己的形象elevenlabs-convai agent-idyour-agent-id avatar-image-urlhttps://example.com/your-avatar.png /elevenlabs-convai自定义配色——让光球与站点主题色一致elevenlabs-convai agent-idyour-agent-id avatar-orb-color-1#ff6b6b avatar-orb-color-2#ffd93d /elevenlabs-convai自定义文案——覆盖关键交互按钮文本elevenlabs-convai agent-idyour-agent-id action-textChat with our AI assistant start-call-textBegin conversation end-call-textHang up /elevenlabs-convai展开式变体——默认直接渲染为展开的对话面板而非悬浮球elevenlabs-convai agent-idyour-agent-id variantexpanded /elevenlabs-convai完整定制——把头像、配色、全部文案一次性配齐适合品牌化客服场景elevenlabs-convai agent-idyour-agent-id avatar-image-urlhttps://example.com/support-agent.png avatar-orb-color-1#4f46e5 avatar-orb-color-2#818cf8 action-textTalk to Support start-call-textStart voice chat end-call-textEnd conversation expand-textOpen assistant collapse-textMinimize /elevenlabs-convai四、CSS 定制穿透 Shadow DOM 的样式方案widget 使用 Shadow DOM 封装内部结构常规选择器无法直接命中内部节点但它暴露了一组 CSS 自定义属性custom properties可以通过宿主元素覆盖尺寸elevenlabs-convai { --elevenlabs-convai-widget-width: 400px; --elevenlabs-convai-widget-height: 600px; }4.1 定位widget 默认出现在右下角可以通过定位属性覆盖到任意位置elevenlabs-convai { position: fixed; bottom: 20px; right: 20px; /* 或者换个角落 */ left: 20px; right: auto; }4.2 层级当页面存在弹窗、侧边栏等高优先级元素时显式提高 z-index 避免被遮挡elevenlabs-convai { z-index: 9999; }五、JavaScript 程序化控制给元素加id后即可用标准 DOM API 驱动它。核心方法有两个startConversation()——开始对话endConversation()——结束对话。同时 widget 会派发conversationStarted与conversationEnded两个自定义事件可用于埋点、切换 UI 状态等elevenlabs-convai idmy-widget agent-idyour-agent-id/elevenlabs-convai script const widget document.getElementById(my-widget); // 开始对话 widget.startConversation(); // 结束对话 widget.endConversation(); // 监听事件 widget.addEventListener(conversationStarted, () { console.log(Conversation started); }); widget.addEventListener(conversationEnded, () { console.log(Conversation ended); }); /script5.1 自定义触发按钮想完全掌控入口交互可以隐藏默认悬浮球改用你自己的按钮触发style elevenlabs-convai { display: none; } /style button onclickdocument.getElementById(widget).startConversation() Talk to AI /button elevenlabs-convai idwidget agent-idyour-agent-id/elevenlabs-convai六、认证流程signed URL 方案当 agent 启用了认证widget 不再直接可用agent-id而必须使用后端签发的一次性签名 URL。整体流程是前端先向你的后端请求签名 URL后端调用 ElevenLabs SDK 的get_signed_url获取临时链接并返回前端把signed-url属性设置为该链接再调用startConversation()。前端elevenlabs-convai idwidget agent-idyour-agent-id/elevenlabs-convai script async function startAuthenticatedConversation() { // 从你的后端获取签名 URL const response await fetch(/api/get-signed-url); const { signedUrl } await response.json(); const widget document.getElementById(widget); widget.setAttribute(signed-url, signedUrl); widget.startConversation(); } /script后端Python / FastAPI 风格app.get(/api/get-signed-url) def get_signed_url(): signed_url client.conversational_ai.conversations.get_signed_url( agent_idyour-agent-id ) return {signedUrl: signed_url.signed_url}同时agent 的platform_settings需要把允许调用的域名加入白名单allowlist否则签名 URL 校验会因跨域失败platform_settings{ auth: { enable_auth: True, allowlist: [https://yourdomain.com] } }七、移动端适配7.1 响应式定位桌面端悬浮右下角、移动端改为底部通栏是常见的交互模式/* 桌面右下角 */ elevenlabs-convai { position: fixed; bottom: 20px; right: 20px; } /* 移动端底部通栏 */ media (max-width: 768px) { elevenlabs-convai { bottom: 0; right: 0; left: 0; --elevenlabs-convai-widget-width: 100%; } }7.2 触控友好widget 本身已针对触屏优化。如需更大的点按热区可以在移动端放大整体比例media (max-width: 768px) { elevenlabs-convai { /* 更大的触控目标 */ transform: scale(1.1); transform-origin: bottom right; } }八、多 Widget一页接入多个 Agent同一页面可以挂载多个 widget分别绑定不同的 agent例如售前咨询与售后支持并通过行内样式错开位置elevenlabs-convai agent-idsupport-agent-id action-textSupport styleright: 20px /elevenlabs-convai elevenlabs-convai agent-idsales-agent-id action-textSales styleright: 100px /elevenlabs-convai九、主流框架集成widget 本质是 Web Component因此框架集成统一遵循动态加载脚本 渲染自定义元素的模式。下面三种是官方推荐的写法。9.1 React用useEffect动态注入脚本并在卸载时清理function App() { useEffect(() { // 加载 widget 脚本 const script document.createElement(script); script.src https://unpkg.com/elevenlabs/convai-widget-embed; script.async true; document.body.appendChild(script); return () document.body.removeChild(script); }, []); return ( div elevenlabs-convai agent-idyour-agent-id/elevenlabs-convai /div ); }9.2 Vue在onMounted中注入脚本模板中直接使用自定义元素template div elevenlabs-convai agent-idyour-agent-id/elevenlabs-convai /div /template script setup import { onMounted } from vue; onMounted(() { const script document.createElement(script); script.src https://unpkg.com/elevenlabs/convai-widget-embed; script.async true; document.body.appendChild(script); }); /script9.3 Next.js使用next/script并采用lazyOnload策略避免阻塞首屏渲染import Script from next/script; export default function Page() { return ( Script srchttps://unpkg.com/elevenlabs/convai-widget-embed strategylazyOnload / elevenlabs-convai agent-idyour-agent-id/elevenlabs-convai / ); }十、故障排查10.1 Widget 不出现按顺序排查确认agent-id正确打开浏览器 Network 面板确认convai-widget-embed脚本已加载查看 Console 是否有 JavaScript 报错确认没有 CSS如display: none隐藏了 widget。10.2 音频问题确保页面运行在HTTPS下——麦克风采集要求安全上下文secure contextHTTP 页面无法使用检查浏览器是否授予了麦克风权限使用受支持的浏览器测试Chrome、Firefox、Safari、Edge。10.3 CORS 错误如果使用了认证流程检查你的域名是否已加入 agent 的 allowlist见第六节。platform_settings.auth.allowlist中必须显式列出实际部署域名。十一、在 OpenMontage 中落地从 Agent 到页面的完整链路widget 只是展示层一个可用的语音代理需要前后端完整闭环。在 OpenMontage 仓库中可以找到这条链路的全部材料Agent 的创建与配置见 agents 技能支持 CLIelevenlabs agents init/agents add/agents push、Python SDK 与 cURL 三种方式agent 内部可配置 LLM 提供商OpenAI / Anthropic / Google / ElevenLabs / 自定义端点、first_message、language、prompt、tts.voice_id以及 webhook / client 工具。创建完成后在平台获取agent-id即上文所有示例中agent-id的取值来源。后端凭证仓库要求以ELEVENLABS_API_KEY环境变量接入 ElevenLabs。在 docs/PROVIDERS.md 的 provider 指南中ELEVENLABS_API_KEY对应 TTS、音乐与音效能力免费额度 1 万字符/月配置方式是在.env中写入该变量与仓库其他 provider 密钥的管理方式一致。服务端语音能力仓库的 elevenlabs_tts 工具 展示了 SDK 之外另一种调用路径——直接以 HTTP 方式请求https://api.elevenlabs.io/v1/text-to-speech/{voice_id}并透传stability、similarity_boost、style、speed、use_speaker_boost等 voice settings其参数默认值stability 0.5、similarity_boost 0.75、speed 1.0与 agents 平台的会话配置保持一致。若没有独立的 ElevenLabs 凭证还可以通过 fal_elevenlabs_tts 工具 用FAL_KEY间接调用 ElevenLabs 语音模型eleven-v3/multilingual-v2/turbo-v2.5异步队列轮询最长等待 300 秒。语音表演质量agent 的回复并非只有说出文本这一个维度。仓库的 voice-performance-director 技能 强调用结构化的voice_performance计划pacing_profile、energy_curve、pause_policy指导 TTS 生成并对 ElevenLabs 给出明确调参建议——较低的stability换取更多表现力变化、适中的style提升表达性、speed保持在0.7..1.2区间、similarity_boost保持较高以保真音色。为语音 agent 设计 persona 提示词时这套调参经验同样适用。综上一条可落地的完整链路是在 ElevenLabs 平台或通过 agents CLI/SDK创建 agent 并取得agent-id→ 在.env中配置ELEVENLABS_API_KEY→ 后端通过 SDK 的get_signed_url提供签名 URL 接口若启用认证→ 前端按本文任意一种嵌入方式挂载elevenlabs-convai→ 依据站点设计定制属性、CSS 与移动端表现即可在任何网站上获得一个随时可对话的语音 AI 入口。【免费下载链接】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),仅供参考
返回列表