尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

Puter TTSVoice 对象详解:AI 文本转语音音色元数据与实战调用指南

Puter TTSVoice 对象详解:AI 文本转语音音色元数据与实战调用指南 Puter TTSVoice 对象详解AI 文本转语音音色元数据与实战调用指南【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puterTTSVoice是 Puter AI 平台中描述某个文本转语音TTS供应商可用音色的数据对象。本文以 TTSVoice 对象文档 为骨架完整讲解其id、name、provider、language、category、labels、supported_models、supported_engines等全部字段的语义与可选性并对照 txt2speech.listVoices()、txt2speech() 两个接口文档及仓库后端源码给出可运行的调用示例。读完本文你将掌握如何在浏览器、Node.js、App 或 Worker 中枚举、过滤并挑选语音把正确的 voice id 传入语音合成调用。背景TTSVoice 在 Puter AI 语音能力中的位置Puter 将多家第三方 TTS 供应商AWS Polly、OpenAI、ElevenLabs、Gemini、xAI、Speechify抽象成统一接口puter.ai.txt2speech。当你想让应用开口说话时通常需要先回答两个问题该供应商当前提供哪些音色voice某个音色支持哪些引擎/模型、语言与附加元数据TTSVoice对象就是第 1 个问题的标准答案格式它是 listVoices 接口返回数组的元素类型。根据 后端类型定义ITTSVoice在源码中的结构为export interface ITTSVoice { id: string; name: string; language?: { name: string; code: string; }; description?: string; category?: string; provider: string; labels?: Recordstring, string; supported_models?: string[]; supported_engines?: string[]; }该接口由统一的puter-ttsdriver 的list_voices()方法调用各供应商listVoices(args)后归一化返回见 TTSDriver.ts当传入provider: all时driver 会遍历所有已注册 provider 并拼接结果。对象文档中带May be absent可缺失字样的字段在 TS 类型中恰好对应?可选标记——这说明同一数组内的对象字段并不完全同构不同供应商返回的元数据详略差异很大消费端代码应做空值防御。属性详解下文逐字段说明 TTSVoice 文档 定义的 9 个属性。idString必有传给puter.ai.txt2speech()的音色标识符。它是整个对象最关键的字段枚举音色的最终目的就是拿到一个能在合成调用中被识别的 id。典型取值如 OpenAI 的alloy、AWS Polly 的Joanna、ElevenLabs 的21m00Tcm4TlvDq8ikWAMRachel 示例音色、Gemini 的Puck、xAI 的eve等。注意 id 通常是供应商侧定义的原始值大小写、连字符、下划线都可能保留原样不要臆测规范化规则直接回传即可。nameString必有人类可读的音色名称例如Alloy、Joanna。它用于展示层下拉菜单、设置面板、列表 UI而真正传给合成接口的是id。在 listVoices 示例 中两者的配合非常典型console.log(voice.id, voice.name)就是面向机器取 id、面向用户显示 name的用法。providerString必有该音色所属的供应商例如aws-polly、openai、elevenlabs、gemini、xai。当调用listVoices({ provider: all })一次性拉取所有供应商时这个字段是你按来源分组/过滤结果的唯一依据。供应商的官方 id 常见别名全部定义在后端 providerAliases.ts 中除六个规范名外eleven、google、grok、polly、simba、aws等别名也会被normalizeTTSProvider()归一化到对应规范名传入无法识别的供应商名时接口会以bad_request错误拒绝。languageObject可选可缺失描述音色语言的嵌套对象包含两个 String 属性name人类可读语言名如English (US)code语言代码如en-US。文档强调May be absent——例如 OpenAI 等偏向中性音色的供应商通常不提供语言字段。因此当你想用语言代码展示音色时应先判断voice.language是否存在官方示例即采用这种防御式写法const lang voice.language ? (${voice.language.code}) : ; console.log(${voice.id} - ${voice.name}${lang});典型含此字段的返回项如下来自 listVoices 文档 的示例响应{ id: Joanna, name: Joanna, provider: aws-polly, language: { name: English (US), code: en-US }, supported_engines: [standard, neural] }注意AWS Polly 对同一音色的语言归属非常明确因此在与语言相关的合成参数上Polly 还有独立的language参数默认en-US二者语义要区分开。descriptionString可选可缺失音色的简短文字说明。例如 OpenAI 示例返回项中的description: A balanced, neutral voice。适合做 UI 中的悬停提示或辅助选择文案缺失时应做降级处理。categoryString可选可缺失音色类别文档给出的示例值是premade预置音色。该字段常用于筛选预置/自定义音色。labelsObject可选可缺失供应商自定义标签的键值对象。不同供应商会携带不同粒度的信息后端类型将其建模为Recordstring, string见 types.ts。由于内容是 provider 专属的跨供应商代码不应假设其中存在某个固定键。supported_modelsArray可选可缺失该音色可配合使用的模型 id 数组元素为 String。例如某个音色可能仅支持[eleven_multilingual_v2]。若该字段存在可用于在 UI 中禁用不兼容当前模型的音色缺失时通常表示不限制。supported_enginesArray可选可缺失该音色支持的引擎类型数组元素为 String。在 AWS Polly 场景下取值如[standard, neural]恰好对应 txt2speech 文档 中 Polly 的engine参数可取值standard默认、neural、long-form、generative。这个字段非常适合做选好音色后列出可用引擎供用户切换的动态联动 UI。如何获取 TTSVoice 数组listVoices() 接口TTSVoice对象只能通过puter.ai.txt2speech.listVoices()获得。该接口支持两种调用形态puter.ai.txt2speech.listVoices() puter.ai.txt2speech.listVoices(options)参数说明参数类型说明optionsObject可选支持provider、engine两个键详见下表options内可用项Option类型说明providerString要查询的 TTS 供应商。默认aws-polly。接受aws-polly、openai、elevenlabs、gemini、xai以及all一次性列出所有供应商常见别名如eleven、google、grok同样有效。无法识别的 provider 会被bad_request拒绝engineString引擎/模型过滤条件供应商相关部分供应商忽略一个便捷规则当options以普通字符串传入时会被当作默认AWS Polly供应商的engine过滤器。返回值Promiseresolve 为TTSVoice对象数组。provider: all时的示例响应含可选字段缺失的情形[ { id: alloy, name: Alloy, provider: openai, description: A balanced, neutral voice }, { id: Joanna, name: Joanna, provider: aws-polly, language: { name: English (US), code: en-US }, supported_engines: [standard, neural] } ]可以看到第一条 OpenAI 音色没有language与supported_engines第二条 Polly 音色没有description——这正是可选字段可缺失字段语义在真实数据中的体现。完整可运行示例浏览器HTML中列出某个供应商的音色html body script srchttps://js.puter.com/v2//script script (async () { const voices await puter.ai.txt2speech.listVoices({ provider: openai }); puter.print(OpenAI voices:); for (const voice of voices) { puter.print( ${voice.id} - ${voice.name}); } })(); /script /body /htmlNode.js 中列出默认AWS Polly全部音色并带语言代码const voices await puter.ai.txt2speech.listVoices(); for (const voice of voices) { const lang voice.language ? (${voice.language.code}) : ; console.log(${voice.id} - ${voice.name}${lang}); }Node.js 中列出 Gemini 音色const voices await puter.ai.txt2speech.listVoices({ provider: gemini }); for (const voice of voices) { console.log(voice.id, voice.name); }在自托管场景下该接口在服务端对应 TTSDriver.ts 的list_voices()实现单供应商模式直接转发给目标 providerall模式则遍历聚合。若需要进一步了解每个供应商侧的listVoices归一化逻辑可查阅 src/backend/drivers/ai-tts/providers 下各 provider 目录awsPolly、openai、elevenlabs、gemini、xai、speechify及其同名测试文件。实战从 TTSVoice 到实际发声拿到 TTSVoice 数组只是第一步最终要用其中某个voice.id发起合成。下表将 txt2speech() 支持的主流供应商与音色/模型默认值汇总帮助你理解不同 provider 的 TTSVoice 对象语言与引擎字段为何呈现差异Provider典型 voice 值默认 model / engine语音风格相关参数aws-pollyJoanna默认等Polly 官方音色表enginestandard默认、neural、long-form、generativelanguage 默认en-USssml布尔开关openaialloy默认、ash、ballad、coral、echo、fable、nova、onyx、sage、shimmermodelgpt-4o-mini-tts默认、tts-1、tts-1-hd输出mp3/wav/opus/aac/flac/pcminstructions风格引导elevenlabs21m00Tcm4TlvDq8ikWAM默认Rachelmodeleleven_multilingual_v2默认、eleven_flash_v2_5、eleven_turbo_v2_5、eleven_v3输出默认mp3_44100_128voice_settingsstability、similarity boost、speedgeminiKore默认另有Zephyr、Puck、Charon、Fenrir、Leda等 30 个音色modelgemini-2.5-flash-preview-tts默认、gemini-2.5-pro-preview-tts、gemini-3.1-flash-tts-previewinstructions自然语言风格指令xaieve默认、充满活力、ara温暖、rex自信、sal流畅、leo权威language 默认en支持auto自动检测与 20 语言输出mp3/wav/pcm/mulaw/alaw内联标签[pause]、[laugh]、whispertext/whisperspeechifygeffen_32默认、dominic_32、harper_32、hugh_32、imogen_32modelsimba-3.2默认、simba-english、simba-multilingual输出mp3/wav/ogg/aac—调用返回一个PromiseHTMLAudioElement其src指向包含合成音频的 blob 或远程 URL。下面是一个综合场景先在页面上枚举某个 provider 的音色再让用户选中并播放。核心是把voice.id塞回options.voicehtml body script srchttps://js.puter.com/v2//script button idplay播放所选音色/button select idvoiceSelect/select script const text 你好欢迎体验 Puter 的文本转语音能力; (async () { // 1) 拉取 TTSVoice 数组 const voices await puter.ai.txt2speech.listVoices({ provider: gemini }); const select document.getElementById(voiceSelect); // 2) 用 name 做展示用 id 做回传 for (const voice of voices) { const opt document.createElement(option); opt.value voice.id; opt.textContent ${voice.name}${voice.language ? ( voice.language.code ) : }; select.appendChild(opt); } })(); document.getElementById(play).addEventListener(click, async () { const voiceId document.getElementById(voiceSelect).value; const audio await puter.ai.txt2speech(text, { provider: gemini, voice: voiceId, model: gemini-2.5-flash-preview-tts, instructions: Speak in a friendly, upbeat tone. }); audio.play(); }); /script /body /html值得注意txt2speech()中provider 列表比 listVoices 多出speechify因此使用 Speechify 音色前不妨先listVoices({ provider: speechify })确认最新 voice id。另外合成文本长度须小于 3000 字符test_mode/testMode置为true时接口返回示例音频而不消耗配额适合先试听某个voice.id再决定正式使用。与相关对象的联系TTSEngine与 TTSVoice 并列的另一个对象类型描述可用引擎/模型及可选价格元数据pricing_per_million_chars由puter.ai.txt2speech.listEngines()返回。后端 types.ts 中ITTSEngine与ITTSVoice同为puter-ttsdriver 的公共结构。TTSVoice 的supported_engines/supported_models字段正是该音色 ↔ 引擎/模型的关联线索。同一对象族语音合成链路中还涉及Speech2TxtResult语音转文字结果对象见 Objects 目录 下的 speech2txtresult.md以及配套的 speech2txt()、speech2speech() 接口。最佳实践小结以id为准、name为辅展示层用name请求层回传id不要把两者混用。可选字段一律判空language、description、category、labels、supported_models、supported_engines都可能缺失跨 provider 迭代时务必先判断再访问如voice.language ? voice.language.code : null。多供应商场景用provider分组provider: all返回混合数组按voice.provider归组可避免同名音色混淆。用supported_engines做联动过滤展示 Polly 音色时仅当数组含neural才允许用户选 neural 引擎减少运行时bad_request。先试听再合成用test_mode获取样本音频验证 voice/engine 组合正式调用时不带该参数。供应商别名统一由后端解析即使 SDK 版本较旧eleven、google、grok等别名也能在后端被正确归一化见 providerAliases.ts 的normalizeTTSProvider()因此客户端不必重复维护别名映射。通过本文介绍的对象字段与调用链路你已经可以把枚举音色 → 展示选择 → 语音合成 → 播放整条 TTS 流程接入 Puter 应用如需在自托管环境中进一步调试可从 src/backend/drivers/ai-tts 的驱动与 provider 实现入手追踪完整数据流。【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表