kling-sdk/README.md

Node.js SDK for Kling AI API

# Kling AI SDK

Node.js SDK for Kling AI API，支持可灵AI平台的各种API接口调用。

## 安装

```bash
npm install kling-sdk
```

## 使用方法

### 1. 初始化客户端

```javascript
const { KlingClient } = require('kling-sdk');

const client = new KlingClient({
  accessKey: '您的Access Key', 
  secretKey: '您的Secret Key'
});
```

### 2. 查询账号资源包

```javascript
async function queryResourcePacks() {
  try {
    const now = Date.now();
    const oneMonthAgo = now - 30 * 24 * 60 * 60 * 1000;

    const result = await client.getResourcePacks({
      start_time: oneMonthAgo, // 开始时间（毫秒时间戳）
      end_time: now,           // 结束时间（毫秒时间戳）
      // resource_pack_name: '可选参数-资源包名称'
    });

    console.log('资源包列表:', result.data.resource_pack_subscribe_infos);
  } catch (error) {
    console.error('查询失败:', error);
  }
}
```

### 3. 图像生成

```javascript
async function generateImage() {
  try {
    // 文本生成图像
    const result = await client.createImageGeneration({
      model_name: 'kling-v1-5',
      prompt: '一只可爱的柴犬坐在花园里，阳光明媚',
      negative_prompt: '模糊, 扭曲, 低质量',
      n: 1, // 生成图片数量
      aspect_ratio: '1:1' // 图片宽高比
    });
    
    console.log('任务ID:', result.data.task_id);
    
    // 查询任务状态
    const taskDetail = await client.getImageGenerationTask(result.data.task_id);
    
    if (taskDetail.data.task_status === 'succeed') {
      console.log('生成的图片:', taskDetail.data.task_result.images);
    }
  } catch (error) {
    console.error('生成失败:', error);
  }
}
```

### 4. 虚拟试穿

```javascript
const fs = require('fs');

// 将本地图片转为Base64
function imageToBase64(imagePath) {
  const image = fs.readFileSync(imagePath);
  return Buffer.from(image).toString('base64');
}

async function virtualTryOn() {
  try {
    const result = await client.createVirtualTryOn({
      model_name: 'kolors-virtual-try-on-v1',
      human_image: imageToBase64('person.jpg'), // 或使用URL
      cloth_image: imageToBase64('cloth.jpg'), // 或使用URL
    });
    
    console.log('任务ID:', result.data.task_id);
    
    // 查询任务状态
    const taskDetail = await client.getVirtualTryOnTask(result.data.task_id);
    
    if (taskDetail.data.task_status === 'succeed') {
      console.log('试穿结果:', taskDetail.data.task_result.images);
    }
  } catch (error) {
    console.error('试穿失败:', error);
  }
}
```

### 5. 文生视频

```javascript
async function text2Video() {
  try {
    const result = await client.createText2Video({
      model_name: 'kling-v1-6',
      prompt: '一只可爱的柴犬在草地上奔跑，阳光灿烂',
      negative_prompt: '模糊, 扭曲, 低质量',
      mode: 'pro', // 高品质模式
      aspect_ratio: '16:9',
      duration: '5', // 5秒视频
      camera_control: {
        type: 'forward_up' // 镜头前进并上仰
      }
    });
    
    console.log('任务ID:', result.data.task_id);
    
    // 查询任务状态
    const taskDetail = await client.getText2VideoTask({ task_id: result.data.task_id });
    
    if (taskDetail.data.task_status === 'succeed') {
      console.log('生成的视频:', taskDetail.data.task_result.videos);
    }
  } catch (error) {
    console.error('生成失败:', error);
  }
}
```

### 6. 图生视频

```javascript
async function image2Video() {
  try {
    const result = await client.createImage2Video({
      model_name: 'kling-v1-6',
      image: imageToBase64('source.jpg'), // 或使用URL
      prompt: '使图片中的人物动起来',
      mode: 'pro',
      duration: '5'
    });
    
    console.log('任务ID:', result.data.task_id);
    
    // 查询任务状态
    const taskDetail = await client.getImage2VideoTask({ task_id: result.data.task_id });
    
    if (taskDetail.data.task_status === 'succeed') {
      console.log('生成的视频:', taskDetail.data.task_result.videos);
    }
  } catch (error) {
    console.error('生成失败:', error);
  }
}
```

### 7. 视频延长

```javascript
async function extendVideo() {
  try {
    // 需要一个已有的视频ID
    const videoId = '已有视频ID';
    
    const result = await client.createVideoExtend({
      video_id: videoId,
      prompt: '继续展示柴犬在草地上奔跑',
      cfg_scale: 0.7
    });
    
    console.log('任务ID:', result.data.task_id);
    
    // 查询任务状态
    const taskDetail = await client.getVideoExtendTask(result.data.task_id);
    
    if (taskDetail.data.task_status === 'succeed') {
      console.log('延长后的视频:', taskDetail.data.task_result.videos);
    }
  } catch (error) {
    console.error('延长失败:', error);
  }
}
```

### 8. 视频特效

```javascript
async function videoEffects() {
  try {
    // 单图特效
    const result = await client.createVideoEffects({
      effect_scene: 'fuzzyfuzzy', // 快来惹毛我特效
      input: {
        model_name: 'kling-v1-6',
        image: imageToBase64('person.jpg'), // 或使用URL
        duration: '5'
      }
    });
    
    console.log('任务ID:', result.data.task_id);
    
    // 查询任务状态
    const taskDetail = await client.getVideoEffectsTask({ task_id: result.data.task_id });
    
    if (taskDetail.data.task_status === 'succeed') {
      console.log('特效视频:', taskDetail.data.task_result.videos);
    }
  } catch (error) {
    console.error('特效失败:', error);
  }
}
```

### 9. 对口型

```javascript
async function lipSync() {
  try {
    // 需要一个已有的视频ID
    const videoId = '已有视频ID';
    
    const result = await client.createLipSync({
      input: {
        video_id: videoId,
        mode: 'text2video',
        text: '你好，这是一段测试文本',
        voice_id: 'zh_female_qingxin',
        voice_language: 'zh'
      }
    });
    
    console.log('任务ID:', result.data.task_id);
    
    // 查询任务状态
    const taskDetail = await client.getLipSyncTask(result.data.task_id);
    
    if (taskDetail.data.task_status === 'succeed') {
      console.log('对口型视频:', taskDetail.data.task_result.videos);
    }
  } catch (error) {
    console.error('对口型失败:', error);
  }
}
```

## 开发和使用

1. 克隆代码库并安装依赖
```bash
git clone <repository-url>
cd kling-sdk
npm install
```

2. 构建SDK
```bash
npm run build
```

3. 运行示例
```bash
# 先修改examples目录下的示例文件中的密钥
npm run start:example
```

## 支持的API

SDK支持以下可灵AI平台的API:

1. **账号信息查询**: 查询账号下资源包列表及余量
2. **图像生成**: 支持文本生成图像和图像参考生成
3. **虚拟试穿**: 上传人物图片和服饰图片，实现虚拟试穿
4. **文生视频**: 通过文本描述生成视频
5. **图生视频**: 将静态图片转换为动态视频
6. **视频延长**: 对现有视频进行延长
7. **视频特效**: 包括单图特效和双人互动特效
8. **对口型**: 使视频中的人物说出指定文本或音频内容

## 常见问题

### 1. 鉴权失败

如果遇到以下错误：
```
查询失败: Error: API错误 (401, 1002): Auth failed
```

可能的原因：
- Access Key或Secret Key不正确
- JWT Token格式或签名算法不匹配
- Token已过期

解决方法：
- 检查密钥是否正确
- 确保JWT签名算法为HS256
- 检查系统时间是否准确

### 2. 请求速率限制

API有QPS限制（QPS<=1），如果请求过快会返回错误：
```
API错误 (429, 1302): Request too fast
```

解决方法：
- 减少API调用频率
- 实现请求队列，控制调用间隔

## 更多示例

请查看 `examples` 目录中的示例代码。

## 注意事项

- API调用需要身份验证，请确保您已获取正确的Access Key和Secret Key
- 请控制请求速率(QPS<=1)，避免触发API限流策略
- 资源包余量统计可能有12小时的延迟
- 生成的图片和视频会在30天后被清理，请及时转存