wall-E/digital_human_backend

Fork 0

Files

wall-E 6c6b19e03e function script

2025-09-05 00:43:20 +08:00

10 KiB

Raw Permalink Blame History

数字人小程序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, 可选): 自定义文件名

响应示例：

{
  "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)

响应示例：

{
  "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

请求体：

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

响应示例：

{
  "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

请求体：

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

3. 创建数字人模板任务

POST /tasks/template/create

请求体：

{
  "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

请求体：

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

5. 创建音频提取任务

POST /tasks/audio/extract

请求体：

{
  "video_file": "视频文件名",
  "user_id": "用户ID（可选）"
}

6. 查询任务状态

GET /tasks/{task_id}/status

响应示例：

{
  "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

响应示例：

{
  "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

响应示例：

{
  "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：基础语音生成

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

创建语音生成任务

POST /api/tasks/voice/generate
{
  "text": "你好，欢迎使用数字人系统",
  "reference_audio": "uploaded_audio.wav"
}

查询任务状态
```
GET /api/tasks/{task_id}/status
```

下载生成的音频

GET /api/download/generated/audio/{uuid}

流程2：数字人视频生成

上传素材文件

POST /api/upload/video  # 上传样本视频
POST /api/upload/audio  # 上传样本音频

创建数字人生成任务

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 }

监控任务进度
```
GET /api/tasks/{task_id}/status
```

下载生成的数字人视频

GET /api/download/generated/video/{uuid}

流程3：模板化视频制作

上传图片素材

POST /api/upload/image  # 上传人物图片
POST /api/upload/image  # 上传背景图片

创建数字人模板

POST /api/tasks/template/create
{
  "person_image": "person.jpg",
  "background_image": "background.jpg",
  "title_text": "AI助手",
  "title_position": [100, 50],
  "video_length": 15.0
}

使用模板合成视频

POST /api/tasks/video/compose
{
  "template_id": "template123",
  "audio_file": "voice_content.wav"
}

⚠️ 错误处理

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

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

常见HTTP状态码：

200: 成功
400: 请求参数错误
404: 资源不存在
413: 文件过大
500: 服务器内部错误

📱 小程序集成建议

1. 文件上传组件

// 小程序文件上传示例
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. 任务状态轮询

// 任务状态查询
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. 完整的数字人生成流程

// 完整流程示例
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服务

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系统提供了完整的数字人生成能力，支持异步处理，适合小程序等前端应用集成使用。

10 KiB Raw Permalink Blame History Unescape Escape

数字人小程序API文档

概述

基础URL

认证

📁 文件上传API

1. 上传视频文件

2. 上传音频文件

3. 上传图片文件

4. 列出已上传文件

🎯 异步任务API

1. 创建语音生成任务

2. 创建数字人生成任务

3. 创建数字人模板任务

4. 创建视频合成任务

5. 创建音频提取任务

6. 查询任务状态

7. 取消任务

📥 文件下载API

1. 下载上传的文件

2. 下载生成的视频

3. 下载生成的音频

4. 下载模板文件

🎨 模板管理API

1. 列出所有模板

2. 获取模板信息

📊 系统状态API

获取系统状态

🔄 典型使用流程

流程1：基础语音生成

流程2：数字人视频生成

流程3：模板化视频制作

⚠️ 错误处理

📱 小程序集成建议

1. 文件上传组件

2. 任务状态轮询

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

🚀 部署说明

启动API服务

环境要求

配置文件

10 KiB

Raw Permalink Blame History