Coze 插件工具函数库

这是一个为 Coze 插件开发提供实用工具函数的 TypeScript 库。该库提供了多种实用功能，帮助开发者更轻松地构建 Coze 插件。

功能特点

全局配置管理：提供统一的配置管理机制，支持设置和获取全局配置
实用工具函数：提供常用的辅助函数，如 sleep 延时函数
MIME 类型检测：支持检测多种文件类型的 MIME 类型
图像处理：支持图像获取和 Base64 转换
音视频处理：
- 音频格式转换（支持 mp3、wav、ogg、flac 等格式）
- 视频与音频合并
- 视频字幕添加（ASS 格式）
- 多个视频文件合并
第三方 API 集成：支持与 Vidu API 集成的视频处理功能

快速使用

准备工作

在 Coze 工作流中进行文件处理后（比如处理了图像、音频、视频等），要将重新文件上传，可以通过 Coze 自身的机制实现，在使用 SDK 前，需要先做一些准备工作。

首先需要解决鉴权问题，这里我们采用服务类应用 JWT 认证。

进入 Coze 开发平台，左侧菜单切换到 API，选择"授权 > OAuth 应用 > 创建新应用”。

应用创建完成后，选择“下载示例文件”，将文件中的 private_key 和 public_key_id 保存下来。

切换到“工作空间 > 资源库 > 新资源 > 工作流”，创建一个工作流。

编辑这个工作流，直接连接开始节点和结束节点：

开始节点输入参数为 file，类型是 File<Default>
结束节点输入参数为 url，直接引用开始节点的 file 参数

发布这个工作流，记录它的 workflow_id，这样就完成了准备工作。

安装

虽然 coze-plugin-utils 在本地也可以用，但它主要是为 Coze 插件准备的。

首先在资源库创建一个插件，点左侧添加依赖包，选择 coze-plugin-utils，等待安装完成。

使用示例

配置管理

import { setGlobalConfig, getGlobalConfig } from 'coze-plugin-utils';

// 设置全局配置
setGlobalConfig({
  baseUrl: 'https://custom-api.coze.cn',
  jwt: {
    appId: 'your-app-id',
    userId: 'your-user-id',
    keyid: 'your-key-id',
    privateKey: 'your-private-key'
  }
});

// 获取配置
const config = getGlobalConfig();
console.log(`API 基础地址: ${config.baseUrl}`);

// 按键获取特定配置
const jwt = getGlobalConfig('jwt');
if (jwt) {
  console.log(`应用 ID: ${jwt.appId}`);
}

基础工具函数

import { sleep, detectMimeType } from 'coze-plugin-utils';

// 使用 sleep 函数延迟执行
async function delayedOperation() {
  console.log('开始操作');
  await sleep(1000); // 延迟 1 秒
  console.log('延迟后继续');
}

// 检测文件 MIME 类型
const buffer = Buffer.from(/* 文件数据 */);
const mimeType = detectMimeType(buffer);
console.log(`文件类型: ${mimeType}`);

图像处理

import { fetchImageAsBase64 } from 'coze-plugin-utils';

async function getImage() {
  try {
    const imageUrl = 'https://example.com/image.jpg';
    const base64Image = await fetchImageAsBase64(imageUrl);
    console.log('图像已转换为 Base64 格式');
    // 使用 base64Image 进行后续操作
  } catch (error) {
    console.error('获取图像失败:', error);
  }
}

音频处理

import { convertAudio } from 'coze-plugin-utils';

async function processAudio() {
  try {
    // 将音频从 WAV 格式转换为 MP3 格式
    const outputPath = await convertAudio('https://example.com/audio.wav', 'mp3');
    console.log(`音频已转换，输出路径: ${outputPath}`);
    
    // 自动检测源格式并转换为 OGG 格式
    const oggPath = await convertAudio('https://example.com/unknown-audio', 'ogg');
    console.log(`音频已转换为 OGG 格式: ${oggPath}`);
  } catch (error) {
    console.error('音频处理失败:', error);
  }
}

视频处理

import { mergeVideoAndAudio, burnASSSubtitleToVideo, joinVideos } from 'coze-plugin-utils';

async function processVideos() {
  try {
    // 合并视频和音频
    const mergedPath = await mergeVideoAndAudio(
      'https://example.com/video.mp4',
      'https://example.com/audio.mp3'
    );
    console.log(`视频和音频已合并: ${mergedPath}`);
    
    // 添加字幕到视频
    const subtitledPath = await burnASSSubtitleToVideo(
      'https://example.com/video.mp4',
      [{ text: '这是一个示例字幕', effect: '{\\pos(960,1000)}', start: '0:00:01.00', end: '0:00:05.00' }]
    );
    console.log(`字幕已添加到视频: ${subtitledPath}`);
    
    // 合并多个视频文件
    const joinedPath = await joinVideos([
      'https://example.com/video1.mp4',
      'https://example.com/video2.mp4',
      'https://example.com/video3.mp4'
    ]);
    console.log(`多个视频已合并: ${joinedPath}`);
  } catch (error) {
    console.error('视频处理失败:', error);
  }
}

第三方 API 集成

import { setGlobalConfig, vidu, getViduResult } from 'coze-plugin-utils';

// 设置全局配置
setGlobalConfig('vidu', {
  apiKey: 'your_vidu_api_key'
});

async function generateVideo() {
  try {
    // 根据文本生成视频
    const textVideoResult = await vidu.textToVideo({
      model: 'vidu1.5',
      prompt: '一朵花开在山崖上',
      bgm: true,
    });
    console.log('文本生成视频结果:', textVideoResult);
    
    // 根据图片生成视频
    const imageVideoResult = await vidu.imageToVideo({
      model: 'vidu1.5',
      prompt: '花朵绽放',
      image: 'https://example.com/flower.jpg',
      bgm: true,
    });
    console.log('图片生成视频结果:', imageVideoResult);
    
    // 根据起始和结束图片生成视频
    const startEndVideoResult = await vidu.startEndToVideo({
      model: 'vidu1.5',
      prompt: '花朵从含苞到绽放',
      start_image: 'https://example.com/flower_bud.jpg',
      end_image: 'https://example.com/flower_bloom.jpg',
      bgm: true,
    });
    console.log('起始结束图片生成视频结果:', startEndVideoResult);
    
    // 根据参考视频生成新视频
    const referenceVideoResult = await vidu.referenceToVideo({
      model: 'vidu1.5',
      prompt: '花朵在风中摇曳',
      reference_video: 'https://example.com/flower_video.mp4',
      bgm: true,
    });
    console.log('参考视频生成结果:', referenceVideoResult);
    
    // 生成音频
    const audioResult = await vidu.textToAudio({
      model: 'vidu_audio',
      prompt: '轻柔的钢琴曲',
      duration: 30, // 30秒
    });
    console.log('文本生成音频结果:', audioResult);
  } catch (error) {
    console.error('生成失败:', error);
  }
}

async function checkVideoTask() {
  const taskId = 'your_task_id';
  
  try {
    // 方法1：使用全局配置获取视频处理结果
    const result = await getViduResult(taskId);
    
    // 方法2：直接传入apiKey
    const apiKey = 'your_vidu_api_key';
    const result2 = await getViduResult(apiKey, taskId);
    
    if (result.state === 'success') {
      console.log('视频处理成功:', result.creations);
    } else {
      console.log('视频处理状态:', result.state);
      if (result.errorMsg) {
        console.error('错误信息:', result.errorMsg);
      }
    }
  } catch (error) {
    console.error('获取视频结果失败:', error);
  }
}

API 文档

配置管理 (config.ts)

配置管理模块提供了统一的全局配置管理功能，允许设置和获取全局配置，所有工具依赖的配置都可以通过该模块获取。

配置结构

interface IGlobalConfig {
  baseUrl: string; // 默认值 https://api.coze.cn
  workflows?: IWorkflows;
  jwt?: IJWTConfig;
}

interface IJWTConfig {
  appId: string;
  userId: string;
  keyid: string;
  privateKey: string;
}

interface IWorkflows {
  [key: string]: string;
  fileUploader?: string; // 用来上传临时文件
}

API

setGlobalConfig(config: Partial<IGlobalConfig>): IGlobalConfig - 设置全局配置，将传入的配置与现有配置合并
setGlobalConfig<K extends keyof IGlobalConfig>(key: K, config: ...): IGlobalConfig - 设置特定配置项
getGlobalConfig(): IGlobalConfig - 获取完整的全局配置
getGlobalConfig<K extends keyof IGlobalConfig>(key: K): IGlobalConfig[K] - 获取特定配置项
resetGlobalConfig(): IGlobalConfig - 重置全局配置到默认值

特性

支持深度合并嵌套对象（如 workflows 和 jwt）
返回配置副本，防止直接修改
类型安全，提供完整的 TypeScript 类型支持
支持按键设置和获取特定配置项

使用示例

import { setGlobalConfig, getGlobalConfig } from 'coze-plugin-utils';

// 设置整个配置对象
setGlobalConfig({
  baseUrl: 'https://custom-api.coze.cn',
  jwt: {
    appId: 'your-app-id',
    keyid: 'your-key-id',
    privateKey: 'your-private-key'
  }
});

// 设置特定配置项
setGlobalConfig('baseUrl', 'https://another-api.coze.cn');

// 获取完整配置
const config = getGlobalConfig();
console.log(config.baseUrl);

// 获取特定配置项
const jwt = getGlobalConfig('jwt');
if (jwt) {
  // 使用 JWT 配置进行认证
}

工具函数 (utils.ts)

sleep(ms: number): Promise<void> - 延迟指定的毫秒数
detectMimeType(buffer: Buffer): string | null - 通过文件头检测 MIME 类型，支持常见的图像、音频和视频格式

图像处理 (vendor/vidu.ts)

fetchImageAsBase64(url: string): Promise<string> - 获取图像并转换为 Base64 格式

音频处理 (media/ffmpeg.ts)

convertAudio(url: string, desType: string, srcType?: string): Promise<string> - 将音频从一种格式转换为另一种格式
- url: 输入音频文件网址
- desType: 目标音频格式 (例如: 'mp3', 'wav', 'ogg', 'flac')
- srcType: 可选，源音频格式。如果未提供，将通过检测文件头来确定

视频处理 (media/ffmpeg.ts)

mergeVideoAndAudio(videoUrl: string, audioUrl: string, audioType?: string): Promise<string> - 将视频和音频合并为一个文件
- videoUrl: 视频文件网址
- audioUrl: 音频文件网址
- audioType: 可选，音频类型 ('wav', 'mp3', 'ogg', 'm4a', 'aac')
burnASSSubtitleToVideo(videoUrl: string, contents: IAssEvents[]): Promise<string> - 将 ASS 格式字幕烧录到视频中
- videoUrl: 视频文件网址
- contents: 字幕内容数组，包含文本、效果、时间等信息
joinVideos(urls: string[], outputFormat?: string): Promise<string> - 将多个视频文件按顺序合并成一个视频
- urls: 视频文件URL数组，按照需要合并的顺序排列
- outputFormat: 可选，输出视频格式，默认为 'mp4'

第三方 API 集成 (vendor/vidu.ts)

配置 Vidu API

import { setGlobalConfig } from 'coze-plugin-tools';

// 设置 Vidu API 密钥
setGlobalConfig('vidu', {
  apiKey: 'your_vidu_api_key'
});

视频生成 API

textToVideo(options: IViduCreationOptions): Promise<IViduResult | { errorMsg: unknown }> - 根据文本提示生成视频
- options.model: 模型名称，如 'vidu1.5'
- options.prompt: 文本提示
- options.bgm: 是否添加背景音乐
- options.seed: 可选，随机种子
- options.callback_url: 可选，回调 URL
imageToVideo(options: IViduCreationOptions): Promise<IViduResult | { errorMsg: unknown }> - 根据图片生成视频
- options.model: 模型名称
- options.prompt: 文本提示
- options.image: 图片 URL 或 Base64 字符串
- options.bgm: 可选，是否添加背景音乐
- options.seed: 可选，随机种子
- options.callback_url: 可选，回调 URL
startEndToVideo(options: IViduCreationOptions): Promise<IViduResult | { errorMsg: unknown }> - 根据起始和结束图片生成视频
- options.model: 模型名称
- options.prompt: 文本提示
- options.start_image: 起始图片 URL 或 Base64 字符串
- options.end_image: 结束图片 URL 或 Base64 字符串
- options.bgm: 可选，是否添加背景音乐
- options.seed: 可选，随机种子
- options.callback_url: 可选，回调 URL
referenceToVideo(options: IViduCreationOptions): Promise<IViduResult | { errorMsg: unknown }> - 根据参考视频生成新视频
- options.model: 模型名称
- options.prompt: 文本提示
- options.reference_video: 参考视频 URL
- options.bgm: 可选，是否添加背景音乐
- options.seed: 可选，随机种子
- options.callback_url: 可选，回调 URL

音频生成 API

textToAudio(options: IAudioTextOptions): Promise<IViduResult | { errorMsg: unknown }> - 根据文本生成音频
- options.model: 模型名称
- options.prompt: 文本提示
- options.duration: 可选，音频时长
- options.seed: 可选，随机种子
- options.callback_url: 可选，回调 URL
timingToAudio(options: IAudioTimingOptions): Promise<IViduResult | { errorMsg: unknown }> - 根据时间点提示生成音频
- options.model: 模型名称
- options.timing_prompts: 时间点提示数组
- options.duration: 可选，音频时长
- options.seed: 可选，随机种子
- options.callback_url: 可选，回调 URL

任务结果查询

getViduResult(taskId: string, timeout?: number): Promise<IViduResult> - 获取 Vidu 视频处理任务的结果（使用全局配置中的apiKey）
- taskId: 任务 ID
- timeout: 可选，超时时间（毫秒），默认为 180000
getViduResult(apiKey: string, taskId: string, timeout?: number): Promise<IViduResult> - 获取 Vidu 视频处理任务的结果（直接传入apiKey）
- apiKey: Vidu API 密钥
- taskId: 任务 ID
- timeout: 可选，超时时间（毫秒），默认为 180000

Browser 模块 (browser.ts)

Browser 模块提供基于 Puppeteer 的浏览器自动化功能，支持 HTML 转视频和截图等功能。

配置

import { setGlobalConfig } from 'coze-plugin-tools';

// 设置 Browser API 密钥（Browserless Token）
setGlobalConfig('browser', {
  apiKey: 'your_browserless_token'
});

API

htmlToVideo(options: ConvertOptions): Promise<string> - 将 HTML 代码转换为视频
- options.code: HTML 代码字符串
- options.duration: 视频时长（秒）
- options.width: 可选，视频宽度
- options.height: 可选，视频高度
- options.deviceScaleFactor: 可选，设备缩放因子，默认为 1
- options.sample_ratio: 可选，采样比率，默认为 10
- 返回：视频文件的临时路径
htmlToScreenshot(options: ScreenshotOptions): Promise<string> - 将 HTML 代码转换为截图
- options.code: HTML 代码字符串
- options.width: 可选，截图宽度
- options.height: 可选，截图高度
- options.deviceScaleFactor: 可选，设备缩放因子，默认为 1
- options.delay: 可选，延迟毫秒数，默认为 500
- 返回：图片文件的临时路径

使用示例

import { browser, setGlobalConfig } from 'coze-plugin-utils';

// 配置 Browser API Key
setGlobalConfig('browser', {
  apiKey: 'your-browserless-token'
});

async function generateVideo() {
  const htmlCode = `
    <!DOCTYPE html>
    <html>
    <head>
      <style>
        body { font-family: Arial; background: linear-gradient(45deg, #ff6b6b, #4ecdc4); }
        .container { text-align: center; padding: 50px; color: white; }
      </style>
    </head>
    <body>
      <div class="container">
        <h1>Hello World!</h1>
        <p>这是一个动态视频演示</p>
      </div>
    </body>
    </html>
  `;

  // 生成视频
  const videoPath = await browser.htmlToVideo({
    code: htmlCode,
    duration: 5, // 5秒视频
    width: 1200,
    height: 800
  });
  
  console.log('视频已生成:', videoPath);
}

async function takeScreenshot() {
  const htmlCode = `
    <div style="padding: 20px; background: #f0f0f0;">
      <h1>截图测试</h1>
      <p>这是一个截图示例</p>
    </div>
  `;

  // 截图
  const screenshotPath = await browser.htmlToScreenshot({
    code: htmlCode,
    width: 800,
    height: 600,
    delay: 1000 // 延迟1秒后截图
  });
  
  console.log('截图已保存:', screenshotPath);
}

许可证

本项目采用 MIT 许可证。查看 LICENSE 文件了解更多详情。

贡献指南

欢迎提交 Issues 和 Pull Requests 来帮助改进这个库。请确保遵循项目的代码风格和提交规范。

Fork 这个仓库
创建您的特性分支 (git checkout -b feature/amazing-feature)
提交您的更改 (git commit -m 'Add some amazing feature')
推送到分支 (git push origin feature/amazing-feature)
打开一个 Pull Request

coze-plugin-utils

Coze 插件工具函数库

功能特点

快速使用

准备工作

安装

使用示例

配置管理

基础工具函数

图像处理

音频处理

视频处理

第三方 API 集成

API 文档

配置管理 (config.ts)

配置结构

API

特性

使用示例

工具函数 (utils.ts)

图像处理 (vendor/vidu.ts)

音频处理 (media/ffmpeg.ts)

视频处理 (media/ffmpeg.ts)

第三方 API 集成 (vendor/vidu.ts)

配置 Vidu API

视频生成 API

音频生成 API

任务结果查询

Browser 模块 (browser.ts)

配置

API

使用示例

许可证

贡献指南

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads