> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coze.cn/llms.txt
> Use this file to discover all available pages before exploring further.

扣子 Node.js SDK 是扣子官方提供的开发工具包，旨在帮助开发者轻松将扣子的 AI 能力集成到应用程序中。Node.js SDK 适合各类开发者使用，无论是初学者还是专业开发人员，都能快速上手并实现所需功能。
## 核心特性 {#a03b6638}
以下是 Node.js SDK 的一些核心特性，帮助你更好地了解其功能和优势：

* 全面的 API 支持：完整支持扣子开放平台的所有 API。
* 多样化的认证方式：支持 PAT、和授权码、JWT、Device、PKCE OAuth 等多种认证方式。
* 流式响应优化：针对聊天和工作流提供实时数据流支持。
* 跨平台兼容：同时支持 Node.js（≥14）和主流浏览器环境。
* 灵活配置选项：提供超时、自定义请求头、中断等配置项。

## 技术优势 {#4d4ade3a}
Node.js SDK 具备以下技术优势：

* 简单易用：提供直观的 API 接口设计，降低使用门槛。
* 类型安全：完整的 TypeScript 类型定义，提供更好的开发体验。
* 错误处理：统一的错误处理机制，便于调试和问题排查。
* 实时响应：针对流式 API 优化，支持实时数据处理。

## 源码地址 {#e099f5f5}
访问 [GitHub](https://github.com/coze-dev/coze-js/tree/main/packages/coze-js) 获取 Node.js SDK 源码。
:::notice 注意
从扣子 GitHub 仓库获取的源码和示例代码中，`base_url` 默认设置为域名 `COZE_COM_BASE_URL`，使用源码前应手动将其修改为域名 `COZE_CN_BASE_URL`。
:::
## 示例代码 {#a71dbda8}
Node.js SDK 提供各种授权方式、各种使用方式的示例代码，便于开发者直接参考使用。
:::tip 说明
* Coze Node.js SDK 支持扣子所有 OpenAPI，对应的 API 文档可参考 [API 介绍](/developer_guides/coze_api_overview)。
* 示例代码将持续更新和补充，各种场景的 Coze Node.js SDK **最新版本**示例代码可参考 [GitHub](https://github.com/coze-dev/coze-js/tree/main/packages/coze-js)。
:::
常见场景的示例代码及说明如下：
<!-- @cols-width: 121,279,384 -->
| | | | \
|**模块** |**示例文件** |**说明** |
|---|---|---|
| | | | \
|授权 |[auth/auth-pat.ts](https://github.com/coze-dev/coze-js/blob/main/examples/coze-js-node/src/auth/auth-pat.ts) |通过个人访问密钥实现 OpenAPI 鉴权。 |
|^^| | | \
| |[auth/auth-oauth-web.ts](https://github.com/coze-dev/coze-js/blob/main/examples/coze-js-node/src/auth/auth-oauth-web.ts) |通过 OAuth 授权码方式实现 OpenAPI 鉴权。 |
|^^| | | \
| |[auth/auth-oauth-jwt.ts](https://github.com/coze-dev/coze-js/blob/main/examples/coze-js-node/src/auth/auth-oauth-jwt.ts) |通过 OAuth JWT 方式实现 OpenAPI 鉴权。 |
|^^| | | \
| |[auth/auth-oauth-jwt-channel.ts](https://github.com/coze-dev/coze-js/blob/main/examples/coze-js-node/src/auth/auth-oauth-jwt-channel.ts) |通过 OAuth JWT 渠道方式实现 OpenAPI 鉴权 |
|^^| | | \
| |[auth/auth-oauth-pkce.ts](https://github.com/coze-dev/coze-js/blob/main/examples/coze-js-node/src/auth/auth-oauth-pkce.ts) |通过 OAuth PKCE 方式实现 OpenAPI 鉴权。 |
|^^| | | \
| |[auth/auth-oauth-device.ts](https://github.com/coze-dev/coze-js/blob/main/examples/coze-js-node/src/auth/auth-oauth-device.ts) |通过 OAuth 设备码方式实现 OpenAPI 鉴权。 |
| | | | \
|对话 |[chat.ts](https://github.com/coze-dev/coze-js/blob/main/examples/coze-js-node/src/chat.ts) |\
| | |发起对话，包含： |\
| | | |\
| | |* 流式对话响应。 |\
| | |* 非流式对话响应。 |\
| | |* 取消对话。 |
|^^| | | \
| |[chat-with-file.ts](https://github.com/coze-dev/coze-js/blob/main/examples/coze-js-node/src/chat-with-file.ts) |发起对话，对话中上传文件，并发送多模态内容。 |
|^^| | | \
| |[chat-local-plugin.ts](https://github.com/coze-dev/coze-js/blob/main/examples/coze-js-node/src/chat-local-plugin.ts) |端插件。 |
| | | | \
|工作流 |\
| |[workflow.ts](https://github.com/coze-dev/coze-js/blob/main/examples/coze-js-node/src/workflow.ts) |执行工作流，包含： |\
| | | |\
| | |* 流式工作流响应。 |\
| | |* 非流式工作流响应。 |
| | | | \
|智能体管理 |[bot.ts](https://github.com/coze-dev/coze-js/blob/main/examples/coze-js-node/src/bot.ts) |\
| | |智能体操作，包含： |\
| | | |\
| | |* 创建智能体。 |\
| | |* 更新智能体。 |\
| | |* 发布智能体为 API 服务。 |\
| | |* 获取智能体列表。 |\
| | |* 获取单个智能体详情。 |
| | | | \
|工作空间 |[workspace.ts](https://github.com/coze-dev/coze-js/blob/main/examples/coze-js-node/src/workspace.ts) |查询工作空间列表。 |
| | | | \
|文件上传 |[file.ts](https://github.com/coze-dev/coze-js/blob/main/examples/coze-js-node/src/file.ts) |文件上传，包含： |\
| | | |\
| | |* 文件上传。 |\
| | |* 获取文件详情。 |
| | | | \
|会话与消息管理 |[conversation.ts](https://github.com/coze-dev/coze-js/blob/main/examples/coze-js-node/src/conversation.ts) |会话与消息管理，包含： |\
| | | |\
| | |* 创建会话。 |\
| | |* 创建、更新、删除消息。 |\
| | |* 获取会话下的消息列表。 |
| | | | \
|知识库管理 |[datasets.ts](https://github.com/coze-dev/coze-js/blob/main/examples/coze-js-node/src/datasets.ts) |知识库管理，包含： |\
| | | |\
| | |* 创建、查询、更新和删除知识库。 |\
| | |* 上传文本和图片类型的知识库文件。 |\
| | |* 更新图片知识库的描述。 |
| | | | \
|变量 |[variables.ts](https://github.com/coze-dev/coze-js/blob/main/examples/coze-js-node/src/variables.ts) |变量管理，包含： |\
| | | |\
| | |* 获取用户变量的值。 |\
| | |* 设置用户变量的值。 |
| | | | \
|语音 |[voice.ts](https://github.com/coze-dev/coze-js/blob/main/examples/coze-js-node/src/voice.ts) |ASR、TTS 与音色相关功能，包含： |\
| | | |\
| | |* 音色克隆。 |\
| | |* 语音合成，将文本转为语音，并将生成的语音保存为音频文件。 |\
| | |* 查询音色列表。 |\
| | |* 语音识别，将指定音频文件转录为文本。 |
| | | | \
|WebSocket语音 |[chat.ts](https://github.com/coze-dev/coze-js/blob/main/examples/coze-js-node/src/websockets/chat.ts) |WebSocket 语音通话。 |
|^^| | | \
| |[speech.ts](https://github.com/coze-dev/coze-js/blob/main/examples/coze-js-node/src/websockets/speech.ts) |语音合成，将文本转为语音，并将生成的语音保存为音频文件。 |
|^^| | | \
| |[transcriptions.ts](https://github.com/coze-dev/coze-js/blob/main/examples/coze-js-node/src/websockets/transcriptions.ts) |语音识别，将指定音频文件转录为文本。 |
| | | | \
|声纹识别 |[voiceprint.ts](https://github.com/coze-dev/coze-js/blob/main/examples/coze-js-node/src/voiceprint.ts) |声纹识别，包含 |\
| | | |\
| | |* 创建、查询和修改声纹组。 |\
| | |* 创建、查询、更新、删除声纹特征。 |\
| | |* 声纹特征比对。 |
| | | | \
|复制模板 |[templates.ts](https://github.com/coze-dev/coze-js/blob/main/examples/coze-js-node/src/templates.ts) |复制商店中的模板到指定工作空间。 |
| | | | \
|用户 |[users-me.ts](https://github.com/coze-dev/coze-js/blob/main/examples/coze-js-node/src/users-me.ts) |获取当前用户信息，如用户 ID、用户名等。 |
| | | | \
|代理 |[proxy/proxy-example.ts](https://github.com/coze-dev/coze-js/blob/main/examples/coze-js-node/src/proxy/proxy-example.ts) |通过代理服务器访问扣子 API。 |
| | | | \
|异常处理 |[error-handle.ts](https://github.com/coze-dev/coze-js/blob/main/examples/coze-js-node/src/error-handle.ts) |处理 API 异常。 |
| | | | \
|网络请求配置 |[request-options.ts](https://github.com/coze-dev/coze-js/blob/main/examples/coze-js-node/src/request-options.ts) |支持大部分 axios 配置。 |

## 异常处理 {#94d655af}
Node.js SDK 提供了完善的异常处理机制，所有异常类都继承自 CozeError 基类。当 API 调用失败时，Node.js SDK 会抛出相应的异常类型，便于开发者进行错误处理和调试。Node.js SDK 封装了以下常见的异常类型：
<!-- @cols-width: 220,134,450 -->
| | | | \
|**异常类** |**HTTP 状态码** |**说明** |
|---|---|---|
| | | | \
|BadRequestError |400 |请求参数错误。通常是参数格式、类型或值域不符合要求。 |
| | | | \
|AuthenticationError |401 |身份认证失败，可能是 token 无效或已过期。 |
| | | | \
|PermissionDeniedError |403 |权限不足，当前身份无权访问目标资源。 |
| | | | \
|NotFoundError |404 |资源不存在，请求的 API 接口或资源未找到。 |
| | | | \
|RateLimitError |429 |请求频率超限，需要降低 API 调用频率。 |
| | | | \
|TimeoutError |408 |请求超时，服务器在预期时间内未收到完整请求。 |
| | | | \
|GatewayError |502 |网关错误，上游服务暂时不可用。 |
| | | | \
|InternalServerError |500 |服务器内部错误，平台服务出现异常。 |