# @framers/agentos-ext-voice-synthesis 中文文档

规范地址：https://npmcn.com/package/%40framers/agentos-ext-voice-synthesis/

版本：3\.1\.2
npm 元数据更新时间：2026-11-01T21:57:57.215Z
中文译文更新时间：2026-11-15T12:09:04.658Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40framers/agentos-ext-voice-synthesis
原文对照：https://npmcn.com/package/%40framers/agentos-ext-voice-synthesis/?lang=original
项目主页：https://github.com/framerslab/agentos-extensions/tree/master/registry/curated/media/voice-synthesis#readme
源码仓库：https://github.com/framerslab/agentos-extensions

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：182 kB，24 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- peer 依赖：@framers/agentos \>=0\.13\.44
- 首次发布：2026-02-06T13:47:18.231Z
- 最新版本发布：2026-11-01T21:57:56.923Z
- 近 30 天下载量：20824（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

通过OpenAI、11Labs、Deepgram以及当地Ollama/Whisper兼容运行时间为AgentOS提供语音合成和转录工具

## 安装

```sh
npm install @framers/agentos-ext-voice-synthesis
```

也可以使用：`pnpm add @framers/agentos-ext-voice-synthesis`、`yarn add @framers/agentos-ext-voice-synthesis`、`bun add @framers/agentos-ext-voice-synthesis`

## README

# AgentOS 语音合成扩展

AgentOS 语音输入和输出工具:

-   `text_to_speech` 通过 Deepgram, OpenAI, 11Labs, 或说 OpenAI 语音 API 的服务器
-   `speech_to_text` 通过 OpenAI Whisper, Deepgram 或 Whisper 兼容本地服务器

## 安装

```bash
npm install @framers/agentos-ext-voice-synthesis
```

## 配置

设置环境变量,或将选项传递给包.

| 环境变量 | 包装选项 | 它的设定 |
| --- | --- | --- |
| `DEEPGRAM_API_KEY` | `deepgramApiKey` (非公开) `deepgram.apiKey`(中文(简体) ) | 深克,两个工具 |
| `OPENAI_API_KEY` | `openaiApiKey` (非公开) `openai.apiKey`(中文(简体) ) | 两种工具的 OpenAI |
| `ELEVENLABS_API_KEY` | `elevenLabsApiKey` (非公开) `elevenlabs.apiKey`(中文(简体) ) | 十一实验室演讲 |
| `DEEPGRAM_BASE_URL`, (中文(简体) ), `OPENAI_BASE_URL` | `deepgramBaseUrl`, (中文(简体) ), `openaiBaseUrl`, (中文(简体) ), `elevenLabsBaseUrl` | 一个API基础,例如代用. 默认 : `https://api.deepgram.com/v1`, (中文(简体) ), `https://api.openai.com/v1`, (中文(简体) ), `https://api.elevenlabs.io/v1` |
|  | `compatibleBaseUrl`, (中文(简体) ), `compatibleApiKey` | OpenAI 兼容语音服务器的 API 基础, 例如 `http://localhost:8880/v1`键,如果它想要一个 |
| `OLLAMA_BASE_URL` | `ollamaBaseUrl` | 该服务器的旧选项, 例如 : `http://localhost:11434`请求地址: `/v1/audio/speech` {\\fn华文楷体\\fs16\\1che0e0e0}在它下面 |
| `TTS_PROVIDER` | `defaultProvider` | `auto`, (中文(简体) ), `deepgram`, (中文(简体) ), `openai`, (中文(简体) ), `elevenlabs` 或者说 `openai-compatible` (单位:千美元)`ollama` 是它的旧名) |
| `AGENTOS_AUDIO_DIR` | `audioDir` | 保存语音 |
|  | `saveAudio` | 主机自己的保护程序 |
|  | `maxAudioBytes`, (中文(简体) ), `requestTimeoutMs` | 一个发言请求的限制:128个米B和5分钟 |
| `WHISPER_LOCAL_BASE_URL` | `whisperLocalBaseUrl` | 一个本地的 OpenAI 兼容的复制服务器 |
| `STT_PROVIDER` | `defaultSttProvider` | `auto`, (中文(简体) ), `openai`, (中文(简体) ), `deepgram` 或者说 `whisper-local` |

## 工具:文本 to speech

制作文本的音频文件并返回其URL。 音频本身从未出现在出品中: AgentOS将一个工具的输出作为文本提供给了模型,而Base64音频在下一份请求中有上百千字节.

**输入 :**

-   `text` (字符串,需要):要发言的文本. 文本超过提供者的长度被拒绝, 而不是切: OpenAI 4,096个字符, Deepgram 2000, 11Labs 5000(`eleven_v3`页:1`eleven_multilingual_v2`),30,000 () (中文(简体) )`eleven_flash_v2`)或40,000个(`eleven_flash_v2_5`) (中文(简体) ).
-   `provider` (字符串): `auto` (违约), `deepgram`, (中文(简体) ), `openai`, (中文(简体) ), `elevenlabs` 或者说 `openai-compatible`。 。 。 .
-   `voice` (字符串):OpenAI: `alloy`, (中文(简体) ), `ash`, (中文(简体) ), `ballad`, (中文(简体) ), `coral`, (中文(简体) ), `echo`, (中文(简体) ), `fable`, (中文(简体) ), `onyx`, (中文(简体) ), `nova` (违约), `sage`, (中文(简体) ), `shimmer`, (中文(简体) ), `verse`, (中文(简体) ), `marin`, (中文(简体) ), `cedar`,或自定义语音标识。 十一律仪: `rachel` (违约), `domi`, (中文(简体) ), `bella`, (中文(简体) ), `antoni`, (中文(简体) ), `josh`, (中文(简体) ), `arnold`, (中文(简体) ), `adam`, (中文(简体) ), `sam`或者是语音识别码 Deepgram:一个Aura模型的代号,例如: `aura-2-thalia-en` (默认),或语音名,例如 `thalia`,变成 `aura-2-thalia-en`。 。 。 .
-   `model` (字符串):深格拉姆:一个Aura模型. 打开AI : `gpt-4o-mini-tts` (违约), `tts-1-hd`11个实验室: `eleven_multilingual_v2` (违约), `eleven_v3`, (中文(简体) ), `eleven_flash_v2_5`, (中文(简体) ), `eleven_flash_v2`。 。 。 . `eleven_v4` 财务报告和审定财务报表 `eleven_v4_turbo` 拒绝 : 11Labs 通过其文本为对话API服务.
-   `format` (字符串): `mp3` (违约), `opus`, (中文(简体) ), `aac`, (中文(简体) ), `flac` 或者说 `wav`11个实验室不能 `aac` 或者说 `flac`。 。 。 .
-   `speed` (数量):OpenAI 0.25至4,深克0.7至1.5,11Labs 0.7至1.2.
-   `stability`, (中文(简体) ), `similarity_boost` (数字为0:1):仅11个Lab.
-   `instructions` (字符串):OpenAI的 `gpt-4o-mini-tts` 只有: 如何说话.

未发送用于提供者的设置, 输出名称为 `notSent`对于Deepgram来说,声音是模型,所以 `model` 给另一个 `voice` 是一个说话 `voice` 被命名为这里.

**输出 :** `audioUrl`, (中文(简体) ), `bytes`, (中文(简体) ), `contentType`, (中文(简体) ), `format`, (中文(简体) ), `provider`, (中文(简体) ), `model`, (中文(简体) ), `voice`, (中文(简体) ), `characters` (案文的长度), `durationEstimateMs` (每分钟150个字)和 `notSent` 当一个设置没有被发送的时候.

### 哪个提供者运行

一个被命名为运行的提供者,或呼叫失败,并说它需要哪个键:没有其他提供者在它的位置被尝试. 与 `auto`数字 :

1.  一个属于一个提供者的声音选取它:一个OpenAI语音名,上面一个11Labs名,一个Deepgram模型 id (`aura-...`(三);
2.  否则第一个有钥匙的:Deepgram, OpenAI, 11Labs.

`openai-compatible` 仅当它被命名或设置为 `defaultProvider`. Ollama 没有任何语音端点;带有名称的选项会保留通过它设置的服务器.

### 声音去的地方

默认情况下,音频被保存为新文件,以及 `audioUrl` 这是它的 `file:` URL (中文(简体) ). 目录是 `audioDir`,则 `AGENTOS_AUDIO_DIR`,则 `agentos-audio-<uid>` 在临时目录中(关于 Windows, `AppData\Local\Temp\agentos-audio` ))),在用户配置文件中. 每位打电话者(`userContext.userId`)拥有自己的子目录. 包删除了任何内容:主机清除目录,操作系统清除默认的目录.

-   目录,以及其中每个呼叫者的目录,必须属于服务用户,没有其他人能够写出. 上面的每一个目录都必须属于该用户或根并被其他人写作,除非它粘着,因为 `/tmp` 即:一个可以在其中之一重新命名条目的用户可以在支票和写作之间互换树名,并接收另一个呼叫者的演讲. 所有这些都是在调用提供者之前制作和检查的,所以一个被拒绝的目录不花费合成;错误命名目录,其所有者和模式.
-   在Kubernetes,一个磁盘备份 `emptyDir` 是0777,没有粘点, 和一卷在舱下 `fsGroup` 属于组- writtable , 因此拒绝在其中任意一个音频目录 。 使山上粘上(`chmod 1777` 装入内容器,或 `emptyDir.mode: 01777` 在带有α的集群上 `EmptyDirVolumeMode` 特性门, Kubernetes 1. 37 及后, 交给服务用户, 或通过 `saveAudio`。 。 。 .
-   在视窗上, 节点没有读取 ACL : 只有目录的种类被检查, 和一个 `audioDir` 您的设置必须是私人的 ACL .
-   A 类 `file:` URL在运行工具的机器上命名一个文件. 客户在别处的宿主通过 `saveAudio`: 获得函数 `{ bytes, contentType, tool, context }`,存储音频,并返回 http(s) URL 客户端加载,最多2 048个字符。 用它,没有写到磁盘.

### 限制和错误

一项请求有五分钟时间(`requestTimeoutMs`),最多可回答128个米B(`maxAudioBytes`两个数字都必须是正整数。 未按要求的格式启动的答案, 如带有状态 200 发送的错误页面, 被拒绝而不保存 。 提供者的错误会随着它的状态及其身体的前300个字符而回来,任何配置的密钥都会被替换为 `[redacted]`。 。 。 .

保存的文件是供主机播放或服务,以及 `speech_to_text` 拿着 `file:` URL 为 `audioUrl` 是为召唤者而保存的.

## 工具: 语句 to text

**供应商:**

-   `openai` ——主持华声通过 `OPENAI_API_KEY`
-   `deepgram` – 托管的 Deepgram STT 通过 `DEEPGRAM_API_KEY`
-   `whisper-local` 本地 OpenAI 兼容的复制端点 `WHISPER_LOCAL_BASE_URL`
-   `auto` ——偏好OpenAI,然后是Deepgram,然后是明确配置本地 STT

**输入 :**

-   `audioBase64` (字符串)- Base64 音频有效载荷,可选作为 `data:` 網址
-   `audioUrl` (字符串)——公共主机上音频的http(s)URL,最多为25个MiB. 它通过AgentOS读取 `guardedFetch` (包裹需要 `@framers/agentos` 0.13.44 或后:主机决定的每个地址必须公开,每个方向被检查的方式相同,只有端口80和443被读取,被读取的停止时间为30秒. 此机或私人网络上的地址被拒绝,其中一条信息是拒绝还是不解决. 服务器必须使用工具列表( 包括其中) 的音频或视频类型回答 `audio/mpeg`, (中文(简体) ), `audio/mp4`, (中文(简体) ), `audio/wav`, (中文(简体) ), `audio/webm`, (中文(简体) ), `audio/ogg`, (中文(简体) ), `application/ogg`, (中文(简体) ), `audio/flac`, (中文(简体) ), `audio/aac`, (中文(简体) ), `audio/x-aac`, (中文(简体) ), `audio/aiff`, (中文(简体) ), `video/mp4`, (中文(简体) ), `video/mpeg`, (中文(简体) ), `video/webm`, (中文(简体) ), `video/quicktime`或与 `application/octet-stream`; 提供者是否读取格式是提供者的答案. 有个特工系统没有 `guardedFetch` 一个 https `audioUrl` 被拒绝; `audioBase64` 还行. `audioUrl` 也可能是 `file:` 音频的 URL `text_to_speech` 曾为召唤者而保存它`userContext.userId`),读自同文 `audioDir`。文件必须有保存者的名字,并坐落在呼叫者的子目录中,对服务用户保密,目录下没有其他用户可以更改. 它必须是有一条链接的正则文件,最多为25个MiB,其字节仍然是其名称所显示的格式. 它打开一次,没有跟随链接。 任何其他 `file:` URL以一个信件被拒绝, 它不表示存在哪些文件; 其他本地文件从不读取 。 这些是图像包保存图像的规则.
-   `provider` (弦,可选) -- `auto`, (中文(简体) ), `openai`, (中文(简体) ), `deepgram`,或 `whisper-local`
-   `mimeType` (弦,可选)——例如: `audio/wav`
-   `fileName` (字符串,可选) — 发送给提供者的文件名
-   `format` (字符串,可选) — 音频格式提示等 `wav`, (中文(简体) ), `mp3`, (中文(简体) ), `m4a`, (中文(简体) ), `webm`
-   `language` (字符串,可选) — ISO 语言提示
-   `prompt` (字符串,可选)——背景提示为有偏见的转录
-   `model` (字符串,可选) — 提供商模型覆盖, 如 `whisper-1`, (中文(简体) ), `nova-2`,或 `base`
-   `temperature` (数字,可选)——华声温度超标
-   `responseFormat` (弦,可选) -- `json`, (中文(简体) ), `text`, (中文(简体) ), `srt`, (中文(简体) ), `verbose_json`,或 `vtt`
-   `diarize` (boolean,可选) — 在支持时启用扬声器对号
-   `utterances` (boolean,可选)——在支持的情况下请求语音分区
-   `smartFormat` (boolean,可选)——在支持的地方启用提供者侧格式
-   `detectLanguage` (boolean,可选) — 在支持的地方启用提供者侧语言检测

**输出 :** 译出文本、提供者/模型元数据、语言、可选信心、持续时间和可选部分.

`whisper-local` 目标 OpenAI 兼容本地复制服务器。 那个 保持工具合同的稳定 即使你在主机Whisper之间交换, Deepgram),以及同一API形状后方的本地运行时间.

## 许可证

Apache-2.0 - 帧.dev

## 常见问题

### @framers/agentos-ext-voice-synthesis 是什么？

通过OpenAI、11Labs、Deepgram以及当地Ollama/Whisper兼容运行时间为AgentOS提供语音合成和转录工具

### 如何安装 @framers/agentos-ext-voice-synthesis？

在项目目录运行 npm install @framers/agentos-ext-voice-synthesis，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@framers/agentos（\>=0\.13\.44）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @framers/agentos-ext-voice-synthesis 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @framers/agentos-ext-voice-synthesis 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @framers/agentos-ext-voice-synthesis 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @framers/agentos-ext-voice-synthesis 可以商用吗？

@framers/agentos-ext-voice-synthesis 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @framers/agentos-ext-voice-synthesis 的下载量有多少？

根据 npm 官方下载统计，@framers/agentos-ext-voice-synthesis 在 2026/10/16 – 2026/11/14 这 30 天内被下载 20,824 次，日均约 694 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @framers/agentos-ext-voice-synthesis 还在维护吗？

最新版本 3\.1\.2 发布于 2026/11/02（14 天前）；至今共发布 10 个版本，其中过去 12 个月发布了 10 个；首次发布于 2026/02/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。