sionrui/docs/kling-integration.md

可灵数字人功能集成报告

功能概述

基于302.ai的可灵API，我们成功集成了独立的人脸识别功能，为后续对口型服务提供基础支持。

后端开发

1. API客户端

• 文件: yudao-module-tik/src/main/java/cn/iocoder/yudao/module/tik/kling/KlingClient.java
• 功能: 调用302.ai的Identify-Face接口
• 复用: 使用现有的LatentsyncProperties配置（API密钥已配置）

2. 业务服务

• Service接口: KlingService.java
• Service实现: KlingServiceImpl.java
• Controller: KlingController.java (路径: /webApi/api/tik/kling/identify-face)

3. 数据传输对象

• 请求VO: KlingIdentifyFaceReqVO.java
• 响应VO: KlingIdentifyFaceRespVO.java
• DTO: KlingIdentifyFaceRequest.java, KlingIdentifyFaceResponse.java

API接口

POST /webApi/api/tik/kling/identify-face
Content-Type: application/json

Request:
{
  "videoUrl": "https://example.com/video.mp4"
}

Response:
{
  "code": 0,
  "data": {
    "sessionId": "session_xxxxx",
    "faceData": [
      {
        "faceId": "face_001",
        "faceImage": "https://...",
        "startTime": 1000,
        "endTime": 5000
      }
    ]
  }
}

前端开发

1. API服务

• 文件: frontend/app/web-gold/src/api/kling.js
• 功能: identifyFace() 方法

2. 页面组件

• 文件: frontend/app/web-gold/src/views/kling/IdentifyFace.vue
• 功能:
  • 视频上传（支持 .mp4/.mov）
  • 拖拽上传支持
  • 进度显示
  • 识别结果展示（人脸列表、时间段）
  • 科技极简风格UI（黑蓝紫色调）

3. 路由配置

• 文件: frontend/app/web-gold/src/router/index.js
• 路径: /digital-human/kling
• 菜单项: "可灵数字人"（位于"数字人"分组下）

技术特点

1. 配置复用

• 复用了现有的 LatentsyncProperties 配置
• API Key: sk-0IZJ2oo7VCkegFuF3JRsSRtyFUsIvLoHNK8OpulnlsStFN78
• Base URL: https://api.302.ai

2. 代码架构

• 遵循Yudao框架的分层架构
• 复用现有的客户端模式（参考LatentsyncClient）
• VO/DTO分层设计

3. 前端设计

• 采用Vue 3 Composition API
• 响应式设计（支持移动端）
• 科技极简风格（渐变背景、毛玻璃效果）

文件结构

yudao-module-tik/src/main/java/cn/iocoder/yudao/module/tik/kling/
├── KlingClient.java                  # API客户端
├── KlingService.java                 # 服务接口
├── KlingServiceImpl.java             # 服务实现
├── KlingController.java              # REST控制器
├── dto/
│   ├── KlingIdentifyFaceRequest.java
│   └── KlingIdentifyFaceResponse.java
└── vo/
    ├── KlingIdentifyFaceReqVO.java
    └── KlingIdentifyFaceRespVO.java

frontend/app/web-gold/src/
├── api/
│   └── kling.js                      # 前端API
├── views/
│   └── kling/
│       └── IdentifyFace.vue          # 识别页面
└── router/
    └── index.js                      # 路由配置（含可灵路由）

使用说明

1. 访问页面

• 登录系统后，点击左侧菜单 数字人 > 可灵数字人

2. 上传视频

• 支持格式：.mp4, .mov
• 文件大小：≤ 100MB
• 视频时长：2-60秒
• 支持拖拽上传

3. 人脸识别

• 点击"开始识别"按钮
• 系统调用302.ai API进行分析
• 显示识别结果：
  • 会话ID（用于后续操作）
  • 检测到的人脸列表
  • 每张人脸的可对口型时间段

注意事项

1. 视频URL: 目前页面使用本地URL进行测试，生产环境需要先上传到OSS获取公网URL
2. API密钥: 已使用现有的302.ai配置，无需额外配置
3. 跨域: 确保前端已配置API代理到后端

后续扩展

1. 口型同步功能: 基于sessionId进行口型同步
2. 批量处理: 支持多个视频的批量识别
3. 历史记录: 保存识别历史到数据库
4. 结果导出: 支持导出识别结果

测试建议

1. 测试不同格式的视频文件
2. 测试大文件上传（接近100MB）
3. 测试网络异常情况
4. 测试识别失败场景

---

开发完成时间: 2024-11-30
状态: 后端API完成，前端页面完成，待测试联调