# @11labs/client 中文文档

规范地址：https://npmcn.com/package/%4011labs/client/

版本：0\.2\.0
npm 元数据更新时间：2025-08-13T17:33:07.597Z
中文译文更新时间：2026-11-05T17:34:09.762Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%4011labs/client
原文对照：https://npmcn.com/package/%4011labs/client/?lang=original
项目主页：https://github.com/elevenlabs/packages#readme
源码仓库：https://github.com/elevenlabs/packages

弃用说明：This package is no longer maintained\. Please use @elevenlabs/client for the latest version

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

- 包体积（解压后）：1 MB，58 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2024-10-12T12:49:57.857Z
- 最新版本发布：2025-08-13T10:14:16.023Z
- 近 30 天下载量：252244（2026-10-04 至 2026-11-02，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 0 个）

## 中文简介

十一Labs JavaScript 客户端库

## 安装

```sh
npm install @11labs/client
```

也可以使用：`pnpm add @11labs/client`、`yarn add @11labs/client`、`bun add @11labs/client`

## README

# 十一Labs JavaScript 客户端库

一个SDK库,用于在基于浏览器的应用程序中使用"11Lab". 如果你想找一个Node.js图书馆,请参考 [十一拉布斯节点js 图书馆](https://www.npmjs.com/package/elevenlabs)。 。 。 .

> 请注意,这个图书馆的启动主要是为了支持对话AI. 今后计划支持语音综合和其他更通用的用法案例.

![LOGO](https://github.com/elevenlabs/elevenlabs-python/assets/12028621/21267d89-5e82-4e7e-9c81-caf30b237683) [![Discord](https://badgen.net/badge/black/ElevenLabs/icon?icon=discord&label)](https://discord.gg/elevenlabs) [![Twitter](https://badgen.net/badge/black/elevenlabsio/icon?icon=twitter&label)](https://twitter.com/elevenlabsio)

## 安装

通过软件包管理器在您的工程中安装软件包 .

```shell
npm install @elevenlabs/client
# or
yarn add @elevenlabs/client
# or
pnpm install @elevenlabs/client
```

## 使用量

这个图书馆主要用于香草JavaScript项目的发展,或者作为适合特定框架的图书馆的基础. 建议检查您的特定框架是否有自己的库. 然而,您可以在任何基于JavaScript的项目中使用此库.

### 连接类型

对话可以通过两种连接类型之一开始:WebSockets(默认)或WebRTC.

### 初始化对话

首先,初始化对话实例:

```js
const conversation = await Conversation.startSession(options);
```

这将踢出websocket连接,并开始使用麦克风与"11Labs"对话AI代理通信. 考虑解释和允许麦克风进入您的应用程序 UI 在对话开始前。 麦克风也可能默认被屏蔽当前页面,导致允许的提示完全不出现. 您应当在应用程序中处理此用途, 并向用户显示适当的消息 :

```js
// call after explaning to the user why the microphone access is needed
// handle errors and show appropriate message to the user
try {
  await navigator.mediaDevices.getUserMedia();
} catch {
  // handle error
}
```

#### 会话配置

转至 `startSession` 如何确定会话 。 开始开会有三种方式:

##### 公共代理人

不需要任何认证的代理可以通过使用代理ID和连接类型开始对话. 代理ID可以通过 [十一实验室](https://elevenlabs.io/app/conversational-ai)。 。 。 .

对于公务人员,您可直接使用身份证明:

```js
const conversation = await Conversation.startSession({
  agentId: "<your-agent-id>",
  connectionType: "webrtc", // 'websocket' is also accepted
});
```

##### 私人代理人

如果对话需要授权,您需要在您的服务器上添加一个专门的端点,该端点将请求一个签名的url(如果使用WebSockets连接类型)或者一个使用WebRTC的谈话符号(如果使用WebRTC) [十一实验室 API](https://elevenlabs.io/docs/introduction) 还给客户.

以下是WebSocket连接的例子:

```js
// Node.js server

app.get("/signed-url", yourAuthMiddleware, async (req, res) => {
  const response = await fetch(
    `https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=${process.env.AGENT_ID}`,
    {
      headers: {
        // Requesting a signed url requires your ElevenLabs API key
        // Do NOT expose your API key to the client!
        "xi-api-key": process.env.ELEVENLABS_API_KEY,
      },
    }
  );

  if (!response.ok) {
    return res.status(500).send("Failed to get signed URL");
  }

  const body = await response.json();
  res.send(body.signed_url);
});
```

```js
// Client

const response = await fetch("/signed-url", yourAuthHeaders);
const signedUrl = await response.text();

const conversation = await Conversation.startSession({
  signedUrl,
  connectionType: "websocket",
});
```

以下是WebRTC的例子:

```js
// Node.js server

app.get("/conversation-token", yourAuthMiddleware, async (req, res) => {
  const response = await fetch(
    `https://api.elevenlabs.io/v1/convai/conversation/token?agent_id=${process.env.AGENT_ID}`,
    {
      headers: {
        // Requesting a conversation token requires your ElevenLabs API key
        // Do NOT expose your API key to the client!
        'xi-api-key': process.env.ELEVENLABS_API_KEY,
      }
    }
  );

  if (!response.ok) {
    return res.status(500).send("Failed to get conversation token");
  }

  const body = await response.json();
  res.send(body.token);
);
```

一旦你拿到信物,提供它给 `startSession` 将使用 WebRTC 启动对话.

```js
// Client

const response = await fetch("/conversation-token", yourAuthHeaders);
const conversationToken = await response.text();

const conversation = await Conversation.startSession({
  conversationToken,
  connectionType: "webrtc",
});
```

#### 可选回调

转至 `startSession` 也可以用于注册可选回调:

-   **连接** - 处理器在对话网口连接建立时打过电话.
-   **断开连接** - 处理器在对话结束时打过电话.
-   **新闻** - 收到新短信后,处理器打电话来。 这些可以是用户声音的暂定或最后的抄录,由LLM制作的答复. 主要用于处理谈话抄录.
-   **错误** - 遇到错误时呼叫处理器.
-   **现状变化** - 当连接状态发生变化时,处理器会呼叫。 可能会 `connected`, (中文(简体) ), `connecting` 财务报告和审定财务报表 `disconnected` (初次发言).
-   **模式变化** - 处理器在状态变化时呼叫,例如代理交换器从 `speaking` 改为 `listening`或者换个角度.
-   **在CanSendFeed Back Change上发布** - 发送反馈时呼叫的处理器可供使用或无法使用.

#### 客户端工具

客户端工具是一种使代理能够引用客户端功能的方法. 这可用于触发客户端中的动作,例如打开一个模式或者代表用户进行API呼叫.

客户工具定义是函数的对象,需要与您的配置在 [十一实验室](https://elevenlabs.io/app/conversational-ai),其中可以命名和描述不同的工具,也可以设置代理传递的参数.

```ts
const conversation = await Conversation.startSession({
  clientTools: {
    displayMessage: async (parameters: { text: string }) => {
      alert(text);

      return "Message displayed";
    },
  },
});
```

在万一函数返回一个值时,它会被传递回代理作为响应. 请注意,该工具需要被明确设定为在"十一律所UI"中阻断对话,以便代理等待并响应响应,否则代理就假定成功并继续进行对话.

#### 对话覆盖

您可以选择覆盖对话的各种设置, 并按动态设置其他用户互动 . 我们支持超越各种环境. 这些设置是可选的,可用于自定义对话体验. 以下设置可供使用:

```ts
const conversation = await Conversation.startSession({
  overrides: {
    agent: {
      prompt: {
        prompt: "My custom prompt",
      },
      firstMessage: "My custom first message",
      language: "en",
    },
    tts: {
      voiceId: "custom voice id",
    },
    conversation: {
      textOnly: true,
    },
  },
});
```

#### 用户识别

您可以选择通过用户ID来识别对话中的用户. 这可以是你自己的客户识别码. 这将包含在发送给服务器的对话启动数据中:

跟踪这个ID可以帮助过滤对话,跟踪用户层面的分析等.

```ts
const conversation = await Conversation.startSession({
  agentId: "<your-agent-id>",
  userId: "user-123", // Optional user identifier
  connectionType: "webrtc",
});
```

#### 只有文本

如果您的代理被配置为只以文本模式运行, 即它不发送或接收音频消息, 您可以使用此旗帜来使用较轻版本的对话。 在这种情况下 用户不会被请求麦克风权限,也不会创建音频上下文.

```ts
const conversation = await Conversation.startSession({
  textOnly: true,
});
```

#### IOS 设备首选耳机

虽然这个SDK将音频输入/输出设备的选择留给了浏览器/系统,但iOS Safari似乎更喜欢内置的扬声器而不是耳机,即使蓝牙设备正在被使用. 如果您想要在iOS设备可用时"强制"使用耳机,可以使用以下选项. 请记住,由于浏览器不提供这种功能,所以不能保证这一点. 系统音频应该是默认的选择.

```ts
const conversation = await Conversation.startSession({
  preferHeadphonesForIosDevices: true,
});
```

#### 连接延迟

您可以在麦克风启动到连接建立之间配置额外的延迟 . 在Android上,延迟默认被设定为3秒,以确保设备有时间切换到正确的音频模式. 没有它,你可能会遇到问题 随着第一个消息的开头被切断.

```ts
const conversation = await Conversation.startSession({
  connectionDelay: {
    android: 3_000,
    ios: 0,
    default: 0,
  },
});
```

#### 获取醒锁

默认情况下,对话将试图获得 [唤醒锁](https://developer.mozilla.org/en-US/docs/Web/API/Screen_Wake_Lock_API) 防止设备在谈话中入睡. 通过设置 `useWakeLock` 选项到 `false`数字 :

```ts
const conversation = await Conversation.startSession({
  useWakeLock: false,
});
```

#### 返回值

`startSession` 返回 a `Conversation` 实例可用于控制会话。 如果会话无法确定, 方法会出错 。 如果用户拒绝麦克风访问, 或者如果websocket连接 失败.

##### 会议结束

手动结束对话的方法. 该方法会结束与websocket的交谈和断开. 之后,对话将无法使用,可以安全地放弃.

```js
await conversation.endSession();
```

##### 发送回信

一个向代理发送二进制反馈的方法. 该方法接受布尔值,其中 `true` 表示积极的反馈 `false` 负面反馈. 反馈总是与最近的代理响应相关,每次响应只能发送一次. 你可以听从 `onCanSendFeedbackChange` 以了解在特定时刻是否可以发送反馈.

```js
conversation.sendFeedback(true);
```

##### 发送文本更新

向代理发送背景更新的方法 . 这可以用来告知代理商与对话没有直接关联的用户动作,但可能影响代理商的反应.

```js
conversation.sendContextualUpdate(
  "User navigated to another page. Consider it for next response, but don't react to this contextual update."
);
```

##### 发送用户信息

向代理人发送短信.

可用于让用户在信件中输入而不是使用麦克风. 与 `sendContextualUpdate`,这将会被当作一个用户消息,并会促使代理商在对话中自行决定.

```js
sendButton.addEventListener("click", e => {
  conversation.sendUserMessage(textInput.value);
  textInput.value = "";
});
```

##### 发送用户活动

通知代理用户活动.

该代理在检测到用户活动后至少2秒内不会尝试发言. 这可以用来防止代理在打字时打断用户.

```js
textInput.addEventListener("input", () => {
  conversation.sendUserActivity();
});
```

##### 获取文件

一种还原对话身份的方法.

```js
const id = conversation.getId();
```

##### 设置

设置对话输出量的方法 。 接受体积字段在0到1之间的对象.

```js
await conversation.setVolume({ volume: 0.5 });
```

##### 哑弹Mic

哑/解麦克风的方法.

```js
// Mute the microphone
conversation.setMicMuted(true);

// Unmute the microphone
conversation.setMicMuted(false);
```

##### 获取输出卷/ 获取输出卷

从中按比例返回当前输入/输出量的方法 `0` 改为 `1` 地点 `0` -100分贝和 `1` -30分贝.

```js
const inputVolume = await conversation.getInputVolume();
const outputVolume = await conversation.getOutputVolume();
```

##### 获取输入ByteFrequencyData / 获取输出ByteFrequencyData

返回的方法 `Uint8Array`s 包含当前输入/输出频率数据。 见 [分析器 Node.getByteFrequencyData](https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/getByteFrequencyData) 更多信息.

## 发展

请参考此寄存器根中的 README. md 文件 .

## 捐款

请先创建一个问题来讨论提议的修改。 欢迎任何贡献!

记住,如果合并,你的代码将作为麻省理工学院许可项目的一部分使用. 通过提交"拉出请求",你同意将您的代码整合到这个库中.

## 常见问题

### @11labs/client 是什么？

十一Labs JavaScript 客户端库注意：该包已被作者标记为弃用——This package is no longer maintained\. Please use @elevenlabs/client for the latest version

### 如何安装 @11labs/client？

在项目目录运行 npm install @11labs/client，或使用 pnpm add / yarn add / bun add。

### @11labs/client 支持 TypeScript 吗？

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

### @11labs/client 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @11labs/client 可以商用吗？

@11labs/client 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @11labs/client 的下载量有多少？

根据 npm 官方下载统计，@11labs/client 在 2026/10/04 – 2026/11/02 这 30 天内被下载 252,244 次，日均约 8,408 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @11labs/client 还在维护吗？

最新版本 0\.2\.0 发布于 2025/08/13（1\.2 年前）；至今共发布 27 个版本，其中过去 12 个月发布了 0 个；首次发布于 2024/10/12。作者已将其标记为弃用，新项目建议寻找替代方案。