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