215 lines
5.9 KiB
Markdown
215 lines
5.9 KiB
Markdown
GMapiServer
|
||
|
||
GMapiServer 是一个基于 Python 和 Flask 构建的高性能 API 服务器，支持通过 URL 输入文件并输出下载链接，提供同步和异步两种处理模式。内置缓存自动清理机制（默认保留 2 小时），支持多种工具接口调用，包括实时任务状态查询和视频帧处理功能。
|
||
|
||
🚀 项目简介
|
||
|
||
GMapiServer 是一个轻量级、模块化的 API 服务框架，旨在为开发者提供以下核心功能：
|
||
|
||
• URL 输入与输出：支持通过 URL 提交文件，返回生成文件的下载链接。
|
||
|
||
• 异步处理：任务在后台异步执行，不阻塞主进程，提升服务器并发性能。
|
||
|
||
• 自动缓存清理：内置定时清理机制，自动删除过期的缓存文件（包括输出文件），默认保留时间 2 小时。
|
||
|
||
• 多工具接口集成：集成 FFmpeg 和 Sanjuuni 工具接口，支持在线调用。
|
||
|
||
• 实时任务状态：提供任务状态查询接口，支持日志实时推送。
|
||
|
||
• 视频帧提取：支持从视频中提取指定分辨率、帧率的图片帧，可打包为二进制格式。
|
||
|
||
🛠️ 技术栈
|
||
|
||
• 编程语言: Python
|
||
|
||
• Web 框架: Flask
|
||
|
||
• 异步处理: 基于 threading
|
||
|
||
• 缓存清理: 定时任务
|
||
|
||
• 依赖管理: pip
|
||
|
||
🧩 支持的接口
|
||
|
||
1. FFmpeg 工具接口
|
||
|
||
• 功能: 在线调用 FFmpeg 工具进行视频/音频处理（如转码、裁剪、合并等）。
|
||
|
||
• 接口文档: https://www.liulikeji.cn/archives/FFmpegApi
|
||
|
||
• 同步接口: POST /api/ffmpeg
|
||
|
||
• 异步接口: POST /api/ffmpeg/async
|
||
|
||
2. Sanjuuni 工具接口
|
||
|
||
• 功能: 在线调用 https://github.com/MCJack123/sanjuuni/tree/master（具体功能需参考其官方文档）。
|
||
|
||
• 接口文档: https://www.liulikeji.cn/archives/SanjuuniApi
|
||
|
||
• 同步接口: POST /api/sanjuuni
|
||
|
||
• 异步接口: POST /api/sanjuuni/async
|
||
|
||
3. 视频帧提取接口
|
||
|
||
• 功能: 从视频中提取指定分辨率、帧率的图片帧，支持强制分辨率调整和填充。
|
||
|
||
• 异步接口: POST /api/video_frame/async
|
||
|
||
• 参数:
|
||
|
||
• video_url: 视频文件 URL
|
||
|
||
• w: 输出宽度
|
||
|
||
• h: 输出高度
|
||
|
||
• fps: 输出帧率
|
||
|
||
• force_resolution: 是否强制调整分辨率
|
||
|
||
• pad_to_target: 是否填充到目标分辨率
|
||
|
||
4. 异步任务状态查询
|
||
|
||
• 功能: 查询异步任务状态和进度，支持日志实时推送。
|
||
|
||
• 接口: GET /api/task/<task_id>
|
||
|
||
• 返回字段:
|
||
|
||
• status: 任务状态（pending/running/completed/error）
|
||
|
||
• progress: 进度百分比
|
||
|
||
• new_logs: 新增的日志条目
|
||
|
||
• result: 完成后的结果（包含下载URL）
|
||
|
||
• error: 错误信息（如果状态为error）
|
||
|
||
5. 帧打包接口
|
||
|
||
• 功能: 将多个帧图片打包为二进制格式，便于批量下载。
|
||
|
||
• 接口: POST /api/framepack
|
||
|
||
• 参数:
|
||
|
||
• urls: 帧图片URL列表，格式为 /frames/<job_id>/<filename>.png
|
||
|
||
• 返回: 二进制流，格式为帧数(4字节) + 各帧数据
|
||
|
||
6. 文件下载接口
|
||
|
||
• 功能: 下载处理完成的文件。
|
||
|
||
• 接口: GET /download/<file_id>/<filename>
|
||
|
||
7. 任务列表查询
|
||
|
||
• 功能: 列出所有任务状态（调试用）。
|
||
|
||
• 接口: GET /api/tasks
|
||
|
||
8. 健康检查
|
||
|
||
• 功能: 服务健康检查。
|
||
|
||
• 接口: GET /health
|
||
|
||
📦 部署与使用
|
||
|
||
1. 安装依赖
|
||
|
||
pip install -r requirements.txt
|
||
|
||
|
||
2. 启动服务器
|
||
|
||
python main.py --port 5000
|
||
|
||
|
||
3. 异步任务使用示例
|
||
|
||
创建异步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>
|
||
|
||
|
||
4. 指定公网地址
|
||
|
||
在相应工具模块中配置下载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 # 文件过期时间(秒)
|
||
|
||
|
||
🔧 异步任务处理流程
|
||
|
||
1. 任务创建: 客户端提交任务请求，服务器返回任务ID和状态查询URL
|
||
2. 后台处理: 任务在独立线程中执行，不阻塞主进程
|
||
3. 状态查询: 客户端可轮询状态接口获取任务进度和实时日志
|
||
4. 结果获取: 任务完成后可通过状态接口或文件下载接口获取结果
|
||
5. 自动清理: 任务结果文件在指定时间后自动清理
|
||
|
||
⚠️ 注意事项
|
||
|
||
1. 文件合法性: 请确保上传文件符合法律法规，不得用于非法用途。
|
||
2. 缓存文件: 系统会自动清理过期文件，请及时下载生成的输出文件。
|
||
3. 异步任务: 异步任务结果在服务器重启后会丢失，请及时处理完成的任务。
|
||
4. 资源限制: 视频帧提取和转码操作可能消耗较多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 # 项目说明文档 |