@coze/api v1.0.0

Introduction

The Coze API SDK for Node or Browser is a versatile tool for integrating Coze's open APIs into your projects.

• Supports all Coze Open Platform APIs
• Supports multiple authentication methods (PAT, OAuth, JWT, OAuth PKCE)
• Supports Node.js and modern browsers
• Some interfaces support both streaming and non-streaming data (e.g., chat, workflow)
• Uses an API design similar to the OpenAI SDK
• Supports configurations such as timeout, headers, signal, and debug

Requirements

• Node.js: >=14

Install

npm install @coze/api

Usage

Examples

Initialize the coze client

Fixed Auth Token

create Personal Auth Token at 扣子 or Coze Platform

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

const client = new CozeAPI({
  token: 'your_token',
  baseURL: COZE_COM_BASE_URL, // you can change to COZE_CN_BASE_URL if you use https://use coze.cn
});

OAuth、JWT 和 Device Code

支持 OAuth 2.0 、 JWT 和 Device Code 等多种认证方式，请参考：

• auth-oauth-web
• auth-oauth-pkce
• auth-oauth-jwt
• auth-oauth-jwt-channel
• auth-oauth-device

chat (stream mode)

Call the coze.chat.stream method to create a chat. The create method is a streaming chat and will return a Chat Iterator. Developers should iterate the iterator to get chat event and handle them.

import { CozeAPI, ChatEventType,COZE_COM_BASE_URL } from '@coze/api';
import { clearLine, cursorTo } from 'node:readline';

const client = new CozeAPI({
  token: 'your_token',
  baseURL: COZE_COM_BASE_URL,
});
const query = 'Hello';

async function streamingChat() {
  const v = await client.chat.stream({
    bot_id: botId,
    auto_save_history: false,
    additional_messages: [
      {
        role: 'user',
        content: query,
        content_type: 'text',
      },
    ],
  });

  for await (const part of v) {
    if (part.event === ChatEventType.CONVERSATION_CHAT_CREATED) {
      console.log('[START]');
      callback && callback(part.data);
    } else if (part.event === ChatEventType.CONVERSATION_MESSAGE_DELTA) {
      process.stdout.write(part.data.content);
    } else if (part.event === ChatEventType.CONVERSATION_MESSAGE_COMPLETED) {
      const { role, type, content } = part.data;
      if (role === 'assistant' && type === 'answer') {
        process.stdout.write('\n');
      } else {
        console.log('[%s]:[%s]:%s', role, type, content);
      }
    } else if (part.event === ChatEventType.CONVERSATION_CHAT_COMPLETED) {
      console.log(part.data.usage);
    } else if (part.event === ChatEventType.DONE) {
      console.log(part.data);
    }
  }

  console.log('=== End of Streaming Chat ===');
}

streamingChat();

chat (non-stream mode)

To simplify the call, the SDK provides a wrapped function to complete non-streaming chat, polling, and obtaining the messages of the chat. Developers can use create_and_poll to simplify the process.

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

const client = new CozeAPI({
  token: 'your_token',
  baseURL: COZE_COM_BASE_URL,
});
const query = 'Hello';

async function nonStreamingChat() {
  console.log('=== Non-Streaming Chat ===');

  const v = await client.chat.create({
    bot_id: botId,
    user_id: '123***',
    additional_messages: [
      {
        role: 'user',
        content: query,
        content_type: 'text',
      },
    ],
  });

  const v = await client.chat.createAndPoll({
    bot_id: botId,
    user_id: '123',
    additional_messages: [
      {
        role: 'user',
        content: query,
        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);
  }
}
nonStreamingChat();

other examples

• bot
• file
• knowledge
• conversation
• workflow
• error-handle
• request-options

How to contribute

develop

pnpm install
pnpm run start

demo（node）

cd examples/node
npm install
cp config.default.js config.js
# and then edit config.js to use your PAT and other params

node chat.mjs
// or
COZE_ENV=zh node chat.mjs

demo（browser）

cd examples/web
npm install
npm run start

test

pnpm run test