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. 视频帧提取接口

• 功能: 从视频中提取指定分辨率、帧率的图片帧，支持强制分辨率调整和填充，支持B站BV号。

• 异步接口: POST /api/video_frame/async

• 参数:

  • video_url: 视频文件 URL (或使用 video_bv 参数替代)

  • video_bv: B站视频BV号 (自动转换为URL)

  • w: 输出宽度

  • h: 输出高度

  • fps: 输出帧率 (默认: 30)

  • force_resolution: 是否强制调整分辨率 (默认: false)

  • pad_to_target: 是否填充到目标分辨率 (默认: false)

• 返回示例:
```json
{
  "task_id": "abc12345",
  "status_url": "http://localhost:5000/api/task/abc12345",
  "message": "任务已创建，请使用状态URL查询进度"
}
```

• 实时任务状态响应（处理中）:
```json
{
  "task_id": "abc12345",
  "status": "running",
  "progress": 50,
  "create_time": 1770393314.1262555,
  "start_time": 1770393314.1262555,
  "end_time": null,
  "type": "video_frame",
  "result": {
    "audio_urls": {
      "audio_dfpwm_url": "/frames/abc12345/audio.dfpwm",
      "audio_dfpwm_left_url": "/frames/abc12345/audio_left.dfpwm",
      "audio_dfpwm_right_url": "/frames/abc12345/audio_right.dfpwm"
    },
    "current_frames": 180,
    "total_frames": 6059,
    "output_resolution": {"w": 640, "h": 360},
    "frame_urls": [
      "/frames/abc12345/frame_000001.png",
      "/frames/abc12345/frame_000002.png",
      // ... 当前已生成的帧
    ]
  },
  "total_logs": 15,
  "last_index": 15,
  "new_logs": ["日志1", "日志2"]
}
```

• 任务完成时结果:
```json
{
  "task_id": "abc12345",
  "status": "completed",
  "progress": 100,
  "create_time": 1770393314.1262555,
  "start_time": 1770393314.1262555,
  "end_time": 1770393391.1024792,
  "type": "video_frame",
  "result": {
    "audio_urls": {
      "audio_dfpwm_url": "/frames/abc12345/audio.dfpwm",
      "audio_dfpwm_left_url": "/frames/abc12345/audio_left.dfpwm",
      "audio_dfpwm_right_url": "/frames/abc12345/audio_right.dfpwm"
    },
    "duration_seconds": 303.019,
    "current_frames": 6059,
    "total_frames": 6059,
    "fps": 20,
    "output_resolution": {"w": 640, "h": 360},
    "frame_urls": [
      "/frames/abc12345/frame_000001.png",
      "/frames/abc12345/frame_000002.png",
      // ... 所有生成帧
    ]
  },
  "total_logs": 164,
  "last_index": 164,
  "new_logs": ["最后日志"]
}
```

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  # 文件过期时间(秒)


🔥 视频帧实时进度功能

GMapiServer 的视频帧提取功能支持实时进度跟踪，让客户端可以在任务处理过程中实时获取已生成的帧并进行下载。

• 实时帧进度跟踪: 自动解析FFmpeg输出的进度信息，实时更新当前帧数
• 智能进度计算: 基于帧数自动计算转换进度（20-80%）
• 音频预处理: 音频在视频处理前提取，客户端可提前下载音频文件
• 实时URL返回: 在处理过程中不断返回已生成的帧URL列表

## 优势特性

1. **减少等待时间**: 客户端无需等待整个视频处理完成
2. **并行下载**: 可以在转换过程中并行下载已生成的帧
3. **实时反馈**: 用户可以看到实时处理进度和日志
4. **资源优化**: 避免了"堵车"效应，提高系统并发能力

## 使用建议

• 客户端可以轮询 `/api/task/<task_id>` 接口获取最新状态
• 通过检查 `result.frame_urls` 列表长度变化确定新生成的帧
• 音频文件可以立即下载（音频处理优先级更高）


🔧 异步任务处理流程

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                  # 项目说明文档