GMapiServer
GMapiServer 是一个基于 Python 和 Flask 构建的高性能 API 服务器，支持通过 URL 输入文件并输出下载链接，提供同步和异步两种处理模式。内置缓存自动清理机制（默认保留 2 小时），支持多种工具接口调用，包括实时任务状态查询和视频帧处理功能。
🚀 项目简介
GMapiServer 是一个轻量级、模块化的 API 服务框架，旨在为开发者提供以下核心功能：
• URL 输入与输出：支持通过 URL 提交文件，返回生成文件的下载链接。
• 异步处理：任务在后台异步执行，不阻塞主进程，提升服务器并发性能。
• 自动缓存清理：内置定时清理机制，自动删除过期的缓存文件（包括输出文件），默认保留时间 2 小时。
• 多工具接口集成：集成 FFmpeg 和 Sanjuuni 工具接口，支持在线调用。
• 实时任务状态：提供任务状态查询接口，支持日志实时推送。
• 视频帧提取：支持从视频中提取指定分辨率、帧率的图片帧，可打包为二进制格式。
🛠️ 技术栈
• 编程语言: Python
• Web 框架: Flask
• 异步处理: 基于 threading
• 缓存清理: 定时任务
• 依赖管理: pip
🧩 支持的接口
- FFmpeg 工具接口
• 功能: 在线调用 FFmpeg 工具进行视频/音频处理（如转码、裁剪、合并等）。
• 接口文档: https://www.liulikeji.cn/archives/FFmpegApi
• 同步接口: POST /api/ffmpeg
• 异步接口: POST /api/ffmpeg/async
- Sanjuuni 工具接口
• 功能: 在线调用 https://github.com/MCJack123/sanjuuni/tree/master（具体功能需参考其官方文档）。
• 接口文档: https://www.liulikeji.cn/archives/SanjuuniApi
• 同步接口: POST /api/sanjuuni
• 异步接口: POST /api/sanjuuni/async
- 视频帧提取接口
• 功能: 从视频中提取指定分辨率、帧率的图片帧，支持强制分辨率调整和填充。
• 异步接口: POST /api/video_frame/async
• 参数:
• video_url: 视频文件 URL
• w: 输出宽度
• h: 输出高度
• fps: 输出帧率
• force_resolution: 是否强制调整分辨率
• pad_to_target: 是否填充到目标分辨率
- 异步任务状态查询
• 功能: 查询异步任务状态和进度，支持日志实时推送。
• 接口: GET /api/task/<task_id>
• 返回字段:
• status: 任务状态（pending/running/completed/error）
• progress: 进度百分比
• new_logs: 新增的日志条目
• result: 完成后的结果（包含下载URL）
• error: 错误信息（如果状态为error）
- 帧打包接口
• 功能: 将多个帧图片打包为二进制格式，便于批量下载。
• 接口: POST /api/framepack
• 参数:
• urls: 帧图片URL列表，格式为 /frames/<job_id>/.png
• 返回: 二进制流，格式为帧数(4字节) + 各帧数据
- 文件下载接口
• 功能: 下载处理完成的文件。
• 接口: GET /download/<file_id>/
- 任务列表查询
• 功能: 列出所有任务状态（调试用）。
• 接口: GET /api/tasks
- 健康检查
• 功能: 服务健康检查。
• 接口: GET /health
📦 部署与使用
- 安装依赖
pip install -r requirements.txt
- 启动服务器
python main.py --port 5000
- 异步任务使用示例
创建异步FFmpeg任务
curl -X POST http://localhost:5000/api/ffmpeg/async
-H "Content-Type: application/json"
-d '{
"input_url": "http://example.com/input.mp4",
"output_format": "mp4",
"args": ["-c:v", "libx264", "-crf", "23"]
}'
查询任务状态
curl http://localhost:5000/api/task/<task_id>
- 指定公网地址
在相应工具模块中配置下载URL：
sanjuuni_utils.py
return { 'status': 'success', 'download_url': f"http://ffmpeg.liulikeji.cn/download/{output_id}/{output_filename}", # 外部访问地址 'file_id': output_id, 'temp_dir': temp_dir }
ffmpeg_utils.py
return { 'status': 'success', 'download_url': f"http://ffmpeg.liulikeji.cn/download/{output_id}/{output_filename}", # 外部访问地址 'file_id': output_id, 'temp_dir': temp_dir }
⏰ 自动缓存清理配置
• 默认保留时间: 2 小时
• 自定义配置:
在logging_config.py文件中修改缓存清理时间
CLEANUP_INTERVAL = 3600 # 清理临时文件的间隔(秒) FILE_EXPIRY = 7200 # 文件过期时间(秒)
🔧 异步任务处理流程
- 任务创建: 客户端提交任务请求，服务器返回任务ID和状态查询URL
- 后台处理: 任务在独立线程中执行，不阻塞主进程
- 状态查询: 客户端可轮询状态接口获取任务进度和实时日志
- 结果获取: 任务完成后可通过状态接口或文件下载接口获取结果
- 自动清理: 任务结果文件在指定时间后自动清理
⚠️ 注意事项
- 文件合法性: 请确保上传文件符合法律法规，不得用于非法用途。
- 缓存文件: 系统会自动清理过期文件，请及时下载生成的输出文件。
- 异步任务: 异步任务结果在服务器重启后会丢失，请及时处理完成的任务。
- 资源限制: 视频帧提取和转码操作可能消耗较多CPU和内存资源。
📝 贡献与反馈
欢迎提交 Issue 或 Pull Request！
如有问题，请联系：[xingluo01@liulikeji.cn] 或 [qq:180877430]
📁 项目结构
GMapiServer/ ├── main.py # 主程序入口 ├── shared_utils.py # 共享工具函数 ├── ffmpeg_utils.py # FFmpeg处理模块 ├── sanjuuni_utils.py # Sanjuuni处理模块 ├── video_frame_utils.py # 视频帧提取模块 ├── file_cleanup.py # 文件清理模块 ├── logging_config.py # 日志配置 ├── requirements.txt # 依赖包列表 └── README.md # 项目说明文档