扣子

扣子扣子编程扣子罗盘资源

文档反馈

低代码项目

快速开始

智能体

工作流

应用

资源

发布

模型

多人协作

开发工具

Coze CLI

API 参考

SDK 参考

Chat SDK

Python SDK

Node.js SDK

Java SDK

Go SDK

Web SDK（AI 编程）

Web SDK（低代码）

Card SDK

音视频

推广与变现

常见问题

Node.js SDK 概述

更新于: 2026-06-25 19:29:14

扣子 Node.js SDK 是扣子官方提供的开发工具包，旨在帮助开发者轻松将扣子的 AI 能力集成到应用程序中。Node.js SDK 适合各类开发者使用，无论是初学者还是专业开发人员，都能快速上手并实现所需功能。

核心特性

以下是 Node.js SDK 的一些核心特性，帮助你更好地了解其功能和优势：

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

技术优势

Node.js SDK 具备以下技术优势：

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

源码地址

访问 GitHub 获取 Node.js SDK 源码。

注意

从扣子 GitHub 仓库获取的源码和示例代码中，base_url 默认设置为域名 COZE_COM_BASE_URL，使用源码前应手动将其修改为域名 COZE_CN_BASE_URL。

示例代码

Node.js SDK 提供各种授权方式、各种使用方式的示例代码，便于开发者直接参考使用。

说明

Coze Node.js SDK 支持扣子所有 OpenAPI，对应的 API 文档可参考 API 介绍。
示例代码将持续更新和补充，各种场景的 Coze Node.js SDK 最新版本示例代码可参考 GitHub。

常见场景的示例代码及说明如下：

模块	示例文件	说明
授权	auth/auth-pat.ts	通过个人访问密钥实现 OpenAPI 鉴权。
	auth/auth-oauth-web.ts	通过 OAuth 授权码方式实现 OpenAPI 鉴权。
	auth/auth-oauth-jwt.ts	通过 OAuth JWT 方式实现 OpenAPI 鉴权。
	auth/auth-oauth-jwt-channel.ts	通过 OAuth JWT 渠道方式实现 OpenAPI 鉴权
	auth/auth-oauth-pkce.ts	通过 OAuth PKCE 方式实现 OpenAPI 鉴权。
	auth/auth-oauth-device.ts	通过 OAuth 设备码方式实现 OpenAPI 鉴权。
对话	chat.ts	发起对话，包含：流式对话响应。非流式对话响应。取消对话。
	chat-with-file.ts	发起对话，对话中上传文件，并发送多模态内容。
	chat-local-plugin.ts	端插件。
工作流	workflow.ts	执行工作流，包含：流式工作流响应。非流式工作流响应。
智能体管理	bot.ts	智能体操作，包含：创建智能体。更新智能体。发布智能体为 API 服务。获取智能体列表。获取单个智能体详情。
工作空间	workspace.ts	查询工作空间列表。
文件上传	file.ts	文件上传，包含：文件上传。获取文件详情。
会话与消息管理	conversation.ts	会话与消息管理，包含：创建会话。创建、更新、删除消息。获取会话下的消息列表。
知识库管理	datasets.ts	知识库管理，包含：创建、查询、更新和删除知识库。上传文本和图片类型的知识库文件。更新图片知识库的描述。
变量	variables.ts	变量管理，包含：获取用户变量的值。设置用户变量的值。
语音	voice.ts	ASR、TTS 与音色相关功能，包含：音色克隆。语音合成，将文本转为语音，并将生成的语音保存为音频文件。查询音色列表。语音识别，将指定音频文件转录为文本。
WebSocket语音	chat.ts	WebSocket 语音通话。
	speech.ts	语音合成，将文本转为语音，并将生成的语音保存为音频文件。
	transcriptions.ts	语音识别，将指定音频文件转录为文本。
声纹识别	voiceprint.ts	声纹识别，包含创建、查询和修改声纹组。创建、查询、更新、删除声纹特征。声纹特征比对。
复制模板	templates.ts	复制商店中的模板到指定工作空间。
用户	users-me.ts	获取当前用户信息，如用户 ID、用户名等。
代理	proxy/proxy-example.ts	通过代理服务器访问扣子 API。
异常处理	error-handle.ts	处理 API 异常。
网络请求配置	request-options.ts	支持大部分 axios 配置。

异常处理

Node.js SDK 提供了完善的异常处理机制，所有异常类都继承自 CozeError 基类。当 API 调用失败时，Node.js SDK 会抛出相应的异常类型，便于开发者进行错误处理和调试。Node.js SDK 封装了以下常见的异常类型：

异常类	HTTP 状态码	说明
BadRequestError	400	请求参数错误。通常是参数格式、类型或值域不符合要求。
AuthenticationError	401	身份认证失败，可能是 token 无效或已过期。
PermissionDeniedError	403	权限不足，当前身份无权访问目标资源。
NotFoundError	404	资源不存在，请求的 API 接口或资源未找到。
RateLimitError	429	请求频率超限，需要降低 API 调用频率。
TimeoutError	408	请求超时，服务器在预期时间内未收到完整请求。
GatewayError	502	网关错误，上游服务暂时不可用。
InternalServerError	500	服务器内部错误，平台服务出现异常。