digital_human_backend/function/API_DOCUMENTATION.md

# 数字人小程序API文档

## 概述

这套API系统专为数字人小程序设计，提供完整的文件上传、异步任务处理、数字人生成、模板管理等功能。

## 基础URL

```
http://aigc.yanhan.cn:5000/api
```

## 认证

目前系统支持可选的用户ID识别，后续可扩展为完整的认证系统。

---

## 📁 文件上传API

### 1. 上传视频文件

**POST** `/upload/video`

**请求格式：** `multipart/form-data`

**参数：**
- `file` (file, 必需): 视频文件 (支持mp4, avi, mov等格式，最大500MB)
- `custom_name` (string, 可选): 自定义文件名

**响应示例：**
```json
{
  "success": true,
  "message": "视频上传成功",
  "file_info": {
    "filename": "abc123.mp4",
    "file_path": "/mnt/docker/resource/uploads/video/abc123.mp4",
    "file_type": "video",
    "file_size": 15728640,
    "mime_type": "video/mp4",
    "relative_path": "uploads/video/abc123.mp4",
    "download_url": "/download/upload/video/abc123.mp4"
  }
}
```

### 2. 上传音频文件

**POST** `/upload/audio`

**请求格式：** `multipart/form-data`

**参数：**
- `file` (file, 必需): 音频文件 (支持wav, mp3, aac等格式，最大50MB)
- `custom_name` (string, 可选): 自定义文件名

### 3. 上传图片文件

**POST** `/upload/image`

**请求格式：** `multipart/form-data`

**参数：**
- `file` (file, 必需): 图片文件 (支持jpg, png, gif等格式，最大10MB)
- `custom_name` (string, 可选): 自定义文件名

### 4. 列出已上传文件

**GET** `/files/list?type={file_type}`

**参数：**
- `type` (string, 可选): 文件类型过滤 (`video`, `audio`, `image`)

**响应示例：**
```json
{
  "success": true,
  "files": [
    {
      "filename": "sample.mp4",
      "file_type": "video",
      "file_size": 15728640,
      "download_url": "/download/upload/video/sample.mp4"
    }
  ],
  "total": 1
}
```

---

## 🎯 异步任务API

### 1. 创建语音生成任务

**POST** `/tasks/voice/generate`

**请求体：**
```json
{
  "text": "要转换的文本内容",
  "reference_audio": "参考音频文件名（可选）",
  "reference_text": "参考音频对应文本（可选）",
  "uuid": "自定义UUID（可选）",
  "user_id": "用户ID（可选）"
}
```

**响应示例：**
```json
{
  "success": true,
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "语音生成任务已创建",
  "status_url": "/api/tasks/550e8400-e29b-41d4-a716-446655440000/status"
}
```

### 2. 创建数字人生成任务

**POST** `/tasks/digital-human/create`

**请求体：**
```json
{
  "speech_text": "数字人要说的文本",
  "sample_video": "样本视频文件名",
  "sample_voice": "样本音频文件名",
  "uuid": "自定义UUID（可选）",
  "user_id": "用户ID（可选）"
}
```

### 3. 创建数字人模板任务

**POST** `/tasks/template/create`

**请求体：**
```json
{
  "person_image": "人物图片文件名",
  "background_image": "背景图片文件名",
  "title_text": "标题文字（可选）",
  "title_position": [50, 50],
  "title_font_size": 48,
  "video_length": 10.0,
  "user_id": "用户ID（可选）"
}
```

### 4. 创建视频合成任务

**POST** `/tasks/video/compose`

**请求体：**
```json
{
  "template_id": "模板ID",
  "audio_file": "音频文件名",
  "text_content": "文本内容（可选）",
  "uuid": "自定义UUID（可选）",
  "user_id": "用户ID（可选）"
}
```

### 5. 创建音频提取任务

**POST** `/tasks/audio/extract`

**请求体：**
```json
{
  "video_file": "视频文件名",
  "user_id": "用户ID（可选）"
}
```

### 6. 查询任务状态

**GET** `/tasks/{task_id}/status`

**响应示例：**
```json
{
  "success": true,
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "progress": 100,
  "result": {
    "audio_path": "/path/to/generated/audio.wav",
    "audio_url": "/download/generated/audio/abc123",
    "uuid": "abc123"
  },
  "error_message": null,
  "created_at": "2025-08-04T10:30:00",
  "updated_at": "2025-08-04T10:35:00"
}
```

**任务状态说明：**
- `pending`: 等待处理
- `processing`: 正在处理
- `completed`: 已完成
- `failed`: 处理失败
- `cancelled`: 已取消

### 7. 取消任务

**POST** `/tasks/{task_id}/cancel`

---

## 📥 文件下载API

### 1. 下载上传的文件

**GET** `/download/upload/{file_type}/{filename}`

### 2. 下载生成的视频

**GET** `/download/generated/video/{uuid}`

### 3. 下载生成的音频

**GET** `/download/generated/audio/{uuid}`

### 4. 下载模板文件

**GET** `/download/template/{template_id}`

---

## 🎨 模板管理API

### 1. 列出所有模板

**GET** `/templates/list`

**响应示例：**
```json
{
  "success": true,
  "templates": [
    {
      "template_id": "template123",
      "title_text": "示例标题",
      "person_image": "person.jpg",
      "background_image": "bg.jpg",
      "created_at": "2025-08-04T10:00:00",
      "download_url": "/api/download/template/template123"
    }
  ],
  "total": 1
}
```

### 2. 获取模板信息

**GET** `/templates/{template_id}`

---

## 📊 系统状态API

### 获取系统状态

**GET** `/system/status`

**响应示例：**
```json
{
  "success": true,
  "system_status": "running",
  "task_stats": {
    "pending": 2,
    "processing": 1,
    "completed": 15,
    "failed": 1
  },
  "file_stats": {
    "video": 10,
    "audio": 8,
    "image": 12
  },
  "total_tasks": 19,
  "worker_running": true
}
```

---

## 🔄 典型使用流程

### 流程1：基础语音生成

1. **上传音频文件**（作为声音模板）
   ```bash
   POST /api/upload/audio
   ```

2. **创建语音生成任务**
   ```bash
   POST /api/tasks/voice/generate
   {
     "text": "你好，欢迎使用数字人系统",
     "reference_audio": "uploaded_audio.wav"
   }
   ```

3. **查询任务状态**
   ```bash
   GET /api/tasks/{task_id}/status
   ```

4. **下载生成的音频**
   ```bash
   GET /api/download/generated/audio/{uuid}
   ```

### 流程2：数字人视频生成

1. **上传素材文件**
   ```bash
   POST /api/upload/video  # 上传样本视频
   POST /api/upload/audio  # 上传样本音频
   ```

2. **创建数字人生成任务**
   ```bash
   POST /api/tasks/digital-human/create
   {
     "speech_text": "大家好，我是数字人小助手",
     "sample_video": "sample_video.mp4",
     "sample_voice": "sample_audio.wav"
   }
   ```




进行任务
POST /api/task/process
{
  "task_id": 任务ID
}




3. **监控任务进度**
   ```bash
   GET /api/tasks/{task_id}/status
   ```

4. **下载生成的数字人视频**
   ```bash
   GET /api/download/generated/video/{uuid}
   ```

### 流程3：模板化视频制作

1. **上传图片素材**
   ```bash
   POST /api/upload/image  # 上传人物图片
   POST /api/upload/image  # 上传背景图片
   ```

2. **创建数字人模板**
   ```bash
   POST /api/tasks/template/create
   {
     "person_image": "person.jpg",
     "background_image": "background.jpg",
     "title_text": "AI助手",
     "title_position": [100, 50],
     "video_length": 15.0
   }
   ```

3. **使用模板合成视频**
   ```bash
   POST /api/tasks/video/compose
   {
     "template_id": "template123",
     "audio_file": "voice_content.wav"
   }
   ```

---

## ⚠️ 错误处理

所有API都遵循统一的错误响应格式：

```json
{
  "error": "错误描述信息"
}
```

**常见HTTP状态码：**
- `200`: 成功
- `400`: 请求参数错误
- `404`: 资源不存在
- `413`: 文件过大
- `500`: 服务器内部错误

---

## 📱 小程序集成建议

### 1. 文件上传组件

```javascript
// 小程序文件上传示例
wx.chooseMedia({
  count: 1,
  mediaType: ['video'],
  success(res) {
    const tempFilePath = res.tempFiles[0].tempFilePath;
    
    wx.uploadFile({
      url: 'https://your-api.com/api/upload/video',
      filePath: tempFilePath,
      name: 'file',
      success(uploadRes) {
        const data = JSON.parse(uploadRes.data);
        console.log('上传成功', data.file_info);
      }
    });
  }
});
```

### 2. 任务状态轮询

```javascript
// 任务状态查询
function checkTaskStatus(taskId) {
  return new Promise((resolve, reject) => {
    const timer = setInterval(() => {
      wx.request({
        url: `https://your-api.com/api/tasks/${taskId}/status`,
        success(res) {
          const { status, progress, result } = res.data;
          
          if (status === 'completed') {
            clearInterval(timer);
            resolve(result);
          } else if (status === 'failed') {
            clearInterval(timer);
            reject(new Error('任务失败'));
          }
          
          // 更新进度条
          console.log(`任务进度: ${progress}%`);
        }
      });
    }, 2000); // 每2秒查询一次
  });
}
```

### 3. 完整的数字人生成流程

```javascript
// 完整流程示例
async function createDigitalHuman(speechText, videoFile, audioFile) {
  try {
    // 1. 上传文件
    const videoInfo = await uploadFile(videoFile, 'video');
    const audioInfo = await uploadFile(audioFile, 'audio');
    
    // 2. 创建任务
    const taskResponse = await wx.request({
      url: 'https://your-api.com/api/tasks/digital-human/create',
      method: 'POST',
      data: {
        speech_text: speechText,
        sample_video: videoInfo.filename,
        sample_voice: audioInfo.filename
      }
    });
    
    // 3. 等待完成
    const result = await checkTaskStatus(taskResponse.data.task_id);
    
    // 4. 下载结果
    const downloadUrl = result.video_url;
    console.log('数字人视频生成完成:', downloadUrl);
    
    return result;
  } catch (error) {
    console.error('生成失败:', error);
    throw error;
  }
}
```

---

## 🚀 部署说明

### 启动API服务

```bash
cd /mnt/docker/code
python miniprogram_api.py
```

服务将在 `http://aigc.yanhan.cn:5000` 启动

### 环境要求

- Python 3.8+
- Flask
- 相关依赖包（详见requirements.txt）
- 足够的磁盘空间存储上传文件和生成结果

### 配置文件

可在各模块中修改配置：
- 文件上传限制：`file_upload.py` 中的 `MAX_FILE_SIZES`
- 存储路径：各模块中的路径常量
- 服务端口：API配置中的端口设置

这套API系统提供了完整的数字人生成能力，支持异步处理，适合小程序等前端应用集成使用。