README.zh-CN.md

Coze API SDK

English | 简体中文

Coze（或扣子）API 平台的官方 Node.js 和浏览器 SDK。

快速开始

1. 安装

npm install @coze/api
# 或
pnpm install @coze/api

2. 基本用法

import { CozeAPI, COZE_CN_BASE_URL, ChatStatus, RoleType } from '@coze/api';

// 使用个人访问令牌初始化客户端
const client = new CozeAPI({
  token: 'your_pat_token', // 从 https://www.coze.cn/open/oauth/pats 获取你的 PAT
  // 或者
  // token: async () => {
  //   // 如果令牌过期则刷新
  //   return 'your_oauth_token';
  // },
  baseURL: COZE_CN_BASE_URL,
});

// 简单对话示例
async function quickChat() {
  const v = await client.chat.createAndPoll({
    bot_id: 'your_bot_id',
    additional_messages: [{
      role: RoleType.User,
      content: 'Hello!',
      content_type: 'text',
    }],
  });

  if (v.chat.status === ChatStatus.COMPLETED) {
    for (const item of v.messages) {
      console.log('[%s]:[%s]:%s', item.role, item.type, item.content);
    }
    console.log('usage', v.chat.usage);
  }
}

主要特性

• 🌐 完整 API 支持：覆盖所有 Coze 开放平台 API
• 🔐 多种认证方式：PAT、OAuth、JWT、OAuth PKCE
• 🔄 流式响应支持：聊天和工作流的实时响应
• 🌍 跨平台：支持 Node.js（≥14）和现代浏览器
• ⚙️ 可配置：超时、请求头、信号、调试选项

认证选项

1. 个人访问令牌（最简单）

const client = new CozeAPI({
  token: 'your_pat_token',
  baseURL: COZE_CN_BASE_URL,
});

2. 其他认证方式

• OAuth Web 应用
• OAuth PKCE
• JWT
• 设备码流程

查看认证示例 →

高级用法

流式对话

import { CozeAPI, ChatEventType, RoleType } from '@coze/api';

async function streamChat() {
  const stream = await client.chat.stream({
    bot_id: 'your_bot_id',
    additional_messages: [{
      role: RoleType.User,
      content: 'Hello!',
      content_type: 'text',
    }],
  });

  for await (const part of stream) {
    if (part.event === ChatEventType.CONVERSATION_MESSAGE_DELTA) {
      process.stdout.write(part.data.content); // 实时响应
    }
  }
}

更多示例

功能	描述	示例
对话	文本对话	chat.ts
Bot管理	创建和管理Bot	bot.ts
数据集	文档管理	datasets.ts
工作流	执行工作流	workflow.ts
语音	语音合成	voice.ts

查看所有示例 →

开发

# 安装依赖
rush update  # 如果未安装 `rush` 命令，请参见 ../../README.md

# 运行测试
npm run test

尝试示例

Node.js

cd examples/coze-js-node
rush build
npx tsx ./src/chat.ts

浏览器

cd examples/coze-js-web
rush build
npm run start

文档

详细的 API 文档和指南，请访问：

• API 概览
• 认证指南