Coze Coding Dev SDK - TypeScript

优雅、模块化的多功能 AI SDK，支持图片生成、视频生成、语音合成、语音识别、大语言模型和联网搜索

✨ 特性

• 🎨 图片生成 - 基于豆包 SeeDream 模型的高质量图片生成
• 🎬 视频生成 - 文本/图片生成视频，支持多种模型和配置
• 🤖 大语言模型 - 支持流式对话、思考链、缓存机制
• 🔍 联网搜索 - Web 搜索、AI 总结、图片搜索
• 🎙️ 语音合成 (TTS) - 多音色、高质量的文本转语音
• 🎧 语音识别 (ASR) - 快速准确的语音转文字
• 🖥️ CLI 工具 - 强大的命令行工具，支持所有功能
• 🏗️ 模块化设计 - 清晰的模块划分，易于扩展
• 🔒 类型安全 - 完整的 TypeScript 类型定义
• 🔄 自动重试 - 内置重试机制
• 📊 Promise/Async - 现代异步编程支持

📦 安装

作为 SDK 使用

npm install coze-coding-dev-sdk
# 或
yarn add coze-coding-dev-sdk
# 或
pnpm add coze-coding-dev-sdk

作为 CLI 工具使用

npm install -g coze-coding-dev-sdk

安装后可以使用 coze-coding-ai 命令：

coze-coding-ai --version
coze-coding-ai --help

🚀 快速开始

环境配置

export COZE_WORKLOAD_IDENTITY_API_KEY="your_api_key"
export COZE_INTEGRATION_BASE_URL="https://api.coze.com"
export COZE_INTEGRATION_MODEL_BASE_URL="https://model.coze.com"

图片生成

import { ImageGenerationClient, Config } from 'coze-coding-dev-sdk';

const config = new Config({
  apiKey: process.env.COZE_WORKLOAD_IDENTITY_API_KEY,
  baseUrl: process.env.COZE_INTEGRATION_BASE_URL,
});

const client = new ImageGenerationClient(config);

const response = await client.generate({
  prompt: 'A beautiful sunset over mountains',
  size: '2K',
});

const helper = client.getResponseHelper(response);
console.log('Image URLs:', helper.imageUrls);

🎯 核心模块

1. 图片生成 (Image)

import { ImageGenerationClient } from 'coze-coding-dev-sdk';

const client = new ImageGenerationClient();

const response = await client.generate({
  prompt: 'A cute cat sitting on a windowsill',
  size: '4K',
  watermark: false,
});

const helper = client.getResponseHelper(response);
console.log('Success:', helper.success);
console.log('Image URLs:', helper.imageUrls);

功能特性：

• 支持 2K/4K 或自定义尺寸 (WIDTHxHEIGHT)
• 文生图 (text-to-image)
• 图生图 (image-to-image)
• 批量生成
• 返回 URL 或 Base64 格式
• 组图生成功能
• 提示词优化

参数说明：

interface ImageGenerationRequest {
  prompt: string; // 提示词（必需）
  size?: string; // 尺寸：'2K' | '4K' | 'WIDTHxHEIGHT'
  watermark?: boolean; // 是否添加水印
  image?: string | string[]; // 参考图片（单个或多个）
  responseFormat?: 'url' | 'b64_json'; // 返回格式
  optimizePromptMode?: string; // 提示词优化模式
  sequentialImageGeneration?: 'auto' | 'disabled'; // 组图功能
  sequentialImageGenerationMaxImages?: number; // 最大图片数量 (1-15)
}

批量生成：

const responses = await client.batchGenerate([
  { prompt: 'A spring cherry blossom', size: '2K' },
  { prompt: 'A summer beach scene', size: '4K' },
  { prompt: 'An autumn forest', size: '2K' },
]);

responses.forEach((response, index) => {
  const helper = client.getResponseHelper(response);
  console.log(`Image ${index + 1}:`, helper.imageUrls);
});

图生图：

const response = await client.generate({
  prompt: 'Transform into watercolor painting style',
  image: 'https://example.com/reference-image.jpg',
  size: '4K',
});

Base64 响应：

const response = await client.generate({
  prompt: 'A professional portrait',
  size: '2K',
  responseFormat: 'b64_json',
});

const helper = client.getResponseHelper(response);
console.log('Base64 data:', helper.imageB64List);

2. 联网搜索 (Search)

import { SearchClient } from 'coze-coding-dev-sdk';

const client = new SearchClient();

const response = await client.webSearch('AI 最新进展', 10);

console.log(`Found ${response.web_items.length} results`);
response.web_items.forEach(item => {
  console.log(`${item.title}: ${item.url}`);
});

功能特性：

• Web 搜索
• Web 搜索 + AI 智能摘要
• 图片搜索
• 高级过滤（站点、时间范围、内容要求）
• 结构化结果返回

搜索类型：

const response1 = await client.webSearch('Python 教程', 10);

const response2 = await client.webSearchWithSummary('量子计算原理', 10);

const response3 = await client.imageSearch('可爱的猫咪', 20);

高级搜索：

const response = await client.advancedSearch('Python 教程', {
  searchType: 'web',
  count: 20,
  needContent: true,
  needUrl: true,
  sites: 'python.org,github.com',
  blockHosts: 'example.com',
  timeRange: '1m',
  needSummary: true,
});

console.log('Summary:', response.summary);
response.web_items.forEach(item => {
  console.log(`${item.title}`);
  console.log(`  Site: ${item.site_name}`);
  console.log(`  Authority: ${item.auth_info_level}`);
});

自定义搜索请求：

const response = await client.search({
  query: '最新科技新闻',
  search_type: 'web_summary',
  count: 10,
  filter: {
    need_content: true,
    need_url: true,
    sites: 'techcrunch.com,wired.com',
    block_hosts: 'spam.com',
  },
  need_summary: true,
  time_range: '1d',
});

搜索结果结构：

interface SearchResponse {
  web_items: WebItem[];
  image_items: ImageItem[];
  summary?: string;
}

interface WebItem {
  id: string;
  sort_id: number;
  title: string;
  site_name?: string;
  url?: string;
  snippet: string;
  summary?: string;
  content?: string;
  publish_time?: string;
  logo_url?: string;
  rank_score?: number;
  auth_info_des: string;
  auth_info_level: number;
}

interface ImageItem {
  id: string;
  sort_id: number;
  title?: string;
  site_name?: string;
  url?: string;
  publish_time?: string;
  image: {
    url: string;
    width?: number;
    height?: number;
    shape: string;
  };
}

3. 语音功能 (Voice)

语音合成 (TTS)

import { TTSClient } from 'coze-coding-dev-sdk';

const client = new TTSClient();

const response = await client.synthesize({
  uid: 'user123',
  text: '你好，欢迎使用 Coze SDK！',
  speaker: 'zh_female_xiaohe_uranus_bigtts',
  audioFormat: 'mp3',
  sampleRate: 24000,
});

console.log('Audio URI:', response.audioUri);
console.log('Audio Size:', response.audioSize, 'bytes');

功能特性：

• 文本转语音 (TTS)
• 支持 SSML 格式
• 30+ 音色选择
• 可调节语速和音量
• 多种音频格式（MP3/PCM/OGG）
• 流式返回

TTS 参数：

interface TTSRequest {
  uid: string; // 用户 ID（必需）
  text?: string; // 文本内容
  ssml?: string; // SSML 格式文本
  speaker?: string; // 音色
  audioFormat?: 'pcm' | 'mp3' | 'ogg_opus'; // 音频格式
  sampleRate?: number; // 采样率
  speechRate?: number; // 语速 (-5 到 5)
  loudnessRate?: number; // 音量 (-5 到 5)
}

SSML 示例：

const ssmlText = `
  <speak>
    <prosody rate="slow">慢速说话</prosody>
    <break time="500ms"/>
    <prosody rate="fast">快速说话</prosody>
  </speak>
`;

const response = await client.synthesize({
  uid: 'user123',
  ssml: ssmlText,
  speaker: 'zh_female_xiaohe_uranus_bigtts',
});

自定义参数：

const response = await client.synthesize({
  uid: 'user123',
  text: '这是一段测试语音',
  speaker: 'zh_female_xiaohe_uranus_bigtts',
  audioFormat: 'mp3',
  sampleRate: 24000,
  speechRate: 1, // 加快语速
  loudnessRate: 2, // 增大音量
});

语音识别 (ASR)

import { ASRClient } from 'coze-coding-dev-sdk';

const client = new ASRClient();

const response = await client.recognize({
  uid: 'user123',
  url: 'https://example.com/audio.mp3',
});

console.log('Recognized Text:', response.text);
console.log('Duration:', response.duration, 'seconds');

功能特性：

• 语音转文字 (ASR)
• 支持 URL 和 Base64 输入
• 多种音频格式
• 详细的时间戳信息
• 最长 2 小时音频

音频要求：

• 音频时长 ≤ 2小时
• 音频大小 ≤ 100MB
• 支持编码: PCM/WAV/MP3/OGG OPUS

ASR 参数：

interface ASRRequest {
  uid?: string; // 用户 ID
  url?: string; // 音频 URL
  base64Data?: string; // Base64 编码的音频数据
}

从 URL 识别：

const response = await client.recognize({
  uid: 'user123',
  url: 'https://example.com/audio.mp3',
});

从 Base64 识别：

const response = await client.recognize({
  uid: 'user123',
  base64Data: 'base64_encoded_audio_data',
});

TTS + ASR 完整流程：

const ttsClient = new TTSClient();
const asrClient = new ASRClient();

const originalText = '这是一段测试文本';

const ttsResponse = await ttsClient.synthesize({
  uid: 'user123',
  text: originalText,
});

const asrResponse = await asrClient.recognize({
  uid: 'user123',
  url: ttsResponse.audioUri,
});

console.log('Original:', originalText);
console.log('Recognized:', asrResponse.text);

4. 视频生成 (Video)

import { VideoGenerationClient } from 'coze-coding-dev-sdk';

const client = new VideoGenerationClient();

const task = await client.textToVideo('一只可爱的小猫在草地上玩耍', {
  config: {
    resolution: '720p',
    ratio: '16:9',
    duration: 5,
  },
});

console.log('Video URL:', task.video_url);

功能特性：

• 文本生成视频 (text-to-video)
• 图片生成视频 (image-to-video)
• 支持首帧、尾帧、参考图片
• 异步任务轮询
• 多种分辨率和比例
• 可配置时长、水印等

视频配置：

interface VideoGenerationConfig {
  resolution?: '720p' | '1080p'; // 分辨率
  ratio?: '16:9' | '9:16' | '1:1'; // 宽高比
  duration?: number; // 时长 (5-10秒)
  watermark?: boolean; // 水印
  seed?: number; // 随机种子
  camerafixed?: boolean; // 固定镜头
}

文生视频：

const task = await client.textToVideo('一只可爱的小猫在草地上玩耍', {
  config: {
    resolution: '1080p',
    ratio: '16:9',
    duration: 5,
  },
  pollInterval: 5,
  maxWaitTime: 300,
});

图生视频（首帧）：

const task = await client.imageToVideo('小猫从坐着到站起来', {
  firstFrameUrl: 'https://example.com/cat_sitting.jpg',
  config: {
    resolution: '720p',
    ratio: '16:9',
    duration: 5,
  },
});

图生视频（首帧+尾帧）：

const task = await client.imageToVideo('小猫的动作变化', {
  firstFrameUrl: 'https://example.com/cat_sitting.jpg',
  lastFrameUrl: 'https://example.com/cat_standing.jpg',
  config: {
    resolution: '720p',
    ratio: '16:9',
    duration: 5,
  },
});

参考图片生成：

const task = await client.imageToVideo('根据参考图片生成视频', {
  referenceImages: ['https://example.com/reference1.jpg', 'https://example.com/reference2.jpg'],
  config: {
    resolution: '720p',
    ratio: '9:16',
    duration: 5,
  },
});

检查任务状态：

const task = await client.checkTask('task_id');

console.log('Status:', task.status);
if (task.status === 'completed') {
  console.log('Video URL:', task.video_url);
} else if (task.status === 'failed') {
  console.log('Error:', task.error_message);
}

配置 (Config)

import { Config } from 'coze-coding-dev-sdk';

const config = new Config({
  apiKey: process.env.COZE_WORKLOAD_IDENTITY_API_KEY,
  baseUrl: process.env.COZE_INTEGRATION_BASE_URL,
  modelBaseUrl: process.env.COZE_INTEGRATION_MODEL_BASE_URL,
  retryTimes: 5,
  retryDelay: 2,
  timeout: 120000,
});

异常处理

import {
  CozeSDKError,
  APIError,
  NetworkError,
  ValidationError,
  ConfigurationError,
} from 'coze-coding-dev-sdk';

try {
  // SDK 调用
} catch (error) {
  if (error instanceof ValidationError) {
    console.error(`参数错误: ${error.field} = ${error.value}`);
  } else if (error instanceof APIError) {
    console.error(`API 错误: ${error.message}, 状态码: ${error.statusCode}`);
  } else if (error instanceof NetworkError) {
    console.error(`网络错误: ${error.message}`);
  } else if (error instanceof ConfigurationError) {
    console.error(`配置错误: ${error.missingKey}`);
  }
}

📁 项目结构

typescript/
├── src/
│   ├── core/           # 核心层
│   │   ├── config.ts   # 配置管理
│   │   ├── client.ts   # 基础客户端
│   │   └── exceptions.ts # 异常定义
│   ├── image/          # 图片生成模块 ✅
│   │   ├── client.ts   # ImageGenerationClient
│   │   ├── models.ts   # 数据模型
│   │   └── index.ts    # 导出
│   ├── search/         # 搜索模块 ✅
│   │   ├── client.ts   # SearchClient
│   │   ├── models.ts   # 数据模型
│   │   └── index.ts    # 导出
│   ├── voice/          # 语音模块 ✅
│   │   ├── tts.ts      # TTSClient
│   │   ├── asr.ts      # ASRClient
│   │   ├── models.ts   # 数据模型
│   │   └── index.ts    # 导出
│   ├── video/          # 视频生成模块 ✅
│   │   ├── client.ts   # VideoGenerationClient
│   │   ├── models.ts   # 数据模型
│   │   └── index.ts    # 导出
│   ├── llm/            # 大语言模型模块 ✅
│   │   ├── client.ts   # LLMClient
│   │   ├── models.ts   # 数据模型
│   │   └── index.ts    # 导出
│   ├── cli/            # CLI 工具 ✅
│   │   ├── index.ts    # CLI 入口
│   │   └── commands/   # 命令实现
│   │       ├── image.ts
│   │       ├── video.ts
│   │       ├── search.ts
│   │       ├── voice.ts
│   │       └── chat.ts
│   └── index.ts        # 主入口
├── bin/
│   └── coze-coding-ai.js # CLI 可执行文件
├── examples/           # 使用示例
│   ├── image-generation-example.ts
│   ├── search-example.ts
│   ├── voice-example.ts
│   ├── video-example.ts
│   └── llm-example.ts
├── dist/               # 编译输出
├── package.json        # npm 配置
├── tsconfig.json       # TypeScript 配置
├── CLI.md              # CLI 使用指南
└── PUBLISHING.md       # 发布指南

5. 大语言模型 (LLM)

import { LLMClient } from 'coze-coding-dev-sdk';

const client = new LLMClient();

const response = await client.invoke(
  [
    { role: 'system', content: '你是一个有帮助的AI助手。' },
    { role: 'user', content: '介绍一下Python编程语言的特点' },
  ],
  { temperature: 0.7 }
);

console.log(response.content);

功能特性：

• 流式对话 (stream)
• 非流式对话 (invoke)
• 支持 thinking 模式
• 支持 caching 机制
• 可配置温度、模型等参数
• 多轮对话支持

流式对话：

const stream = client.stream([{ role: 'user', content: '介绍一下TypeScript' }], {
  temperature: 0.7,
});

for await (const chunk of stream) {
  if (chunk.content) {
    process.stdout.write(chunk.content.toString());
  }
}

LLM 配置：

interface LLMConfig {
  model?: string; // 模型名称
  thinking?: 'enabled' | 'disabled'; // 思考链
  caching?: 'enabled' | 'disabled'; // 缓存
  temperature?: number; // 温度 (0-2)
  streaming?: boolean; // 是否流式
}

🖥️ CLI 工具

除了作为 SDK 使用，本包还提供了强大的命令行工具。

全局安装

npm install -g coze-coding-dev-sdk

环境配置

export COZE_CODING_API_KEY="your-api-key-here"
export COZE_CODING_BASE_URL="https://api.coze.cn"  # 可选
export COZE_CODING_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"  # 可选

CLI 命令

所有命令都支持 --verbose 参数，用于打印详细的 HTTP 请求信息（敏感的认证信息会自动脱敏）：

# 启用 verbose 模式查看请求详情
coze-coding-ai image -p "a cat" --verbose

1. 图片生成

# 基本用法
coze-coding-ai image -p "a beautiful sunset over the ocean"

# 指定尺寸并保存
coze-coding-ai image -p "a cat" --size 4K -o output.jpg

# 启用 verbose 模式查看请求详情
coze-coding-ai image -p "a cat" --verbose

2. 视频生成

# 生成视频
coze-coding-ai video -p "a cat playing with a ball" --duration 5

# 查询状态
coze-coding-ai video-status --task-id <task-id>

3. 联网搜索

# 网页搜索
coze-coding-ai search -q "TypeScript 最新特性" --count 10

# 图片搜索
coze-coding-ai search -q "sunset" --type image

# 使用 verbose 模式调试请求
coze-coding-ai search -q "AI" --verbose

4. 语音合成

coze-coding-ai tts -t "你好，世界" --speaker zh_female_xiaohe_uranus_bigtts

5. 语音识别

# 使用 URL
coze-coding-ai asr -u "https://example.com/audio.mp3"

# 使用本地文件
coze-coding-ai asr -f ./audio.mp3

6. AI 对话

# 基本对话
coze-coding-ai chat -p "什么是人工智能？"

# 流式输出
coze-coding-ai chat -p "写一首诗" --stream

# 带系统提示
coze-coding-ai chat -p "解释量子计算" -s "你是一个物理学教授"

CLI 使用场景

场景 1: 快速生成产品图片

coze-coding-ai image \
  -p "A modern smartphone with sleek design" \
  --size 4K \
  -o product.jpg

场景 2: 内容研究

# 搜索信息
coze-coding-ai search -q "AI trends 2024" --count 20

# AI 总结
coze-coding-ai chat \
  -p "总结一下 AI 在 2024 年的主要趋势" \
  -s "你是一个 AI 研究专家"

场景 3: 自动化工作流

#!/bin/bash
# 生成图片
coze-coding-ai image -p "logo design" -o logo.jpg

# 生成描述
coze-coding-ai chat -p "为这个 logo 写一段营销文案" -o description.txt

# 转语音
coze-coding-ai tts -t "$(cat description.txt)"

查看完整的 CLI 文档：CLI.md

🛠️ 开发

安装依赖

npm install

构建

npm run build

开发模式

npm run dev

本地测试 CLI

# 构建并链接
npm run build
npm link

# 测试命令
coze-coding-ai --version
coze-coding-ai --help

# 取消链接
npm unlink -g coze-coding-dev-sdk

代码检查

npm run lint

格式化

npm run format

测试

npm test

📊 版本历史

查看 ../../CHANGELOG.md 了解详细的版本变更记录。

🤝 贡献

欢迎提交 Issue 和 Pull Request！

查看 ../../CONTRIBUTING.md 了解如何参与贡献。

📄 许可证

本项目采用 MIT License 开源协议。

🙏 致谢

基于 Coze AI Integrations 和豆包大模型构建。

📞 联系方式

• 项目主页: https://github.com/coze/coze-sdk
• 问题反馈: https://github.com/coze/coze-sdk/issues
• 邮箱: [email protected]