Spaces:

BlueSkyXN
/

ImageMagickAPI-HFS

Running

App Files Files Community

BlueSkyXN commited on Nov 8, 2025

Commit

c8344ad

unverified ·

2 Parent(s): fc94a64 090921a

0.2.0

Browse files

Files changed (2) hide show

README.md +47 -3
main.py +418 -32

README.md CHANGED Viewed

@@ -14,7 +14,9 @@ pinned: false # 是否在你的个人资料页置顶这个 Space (可选)
 ## ✨ 功能特性
 * **🎯 动态路径 API**: 通过 URL 路径直接指定目标格式、转换模式和质量参数
 * **🎬 动画支持**: 完整支持 GIF、Animated WebP/AVIF/APNG 等动画格式
 * **🔄 多格式转换**: 支持 AVIF、WebP、JPEG、PNG、GIF、HEIF 格式互转
 * **⚙️ 灵活配置**: 支持有损/无损两种模式，质量参数可在 0-100 范围自由调节
@@ -23,7 +25,41 @@ pinned: false # 是否在你的个人资料页置顶这个 Space (可选)
 ## 📡 API 端点
-### 1. 图像转换
 **端点**: `POST /convert/{target_format}/{mode}/{setting}`
@@ -58,7 +94,7 @@ curl -X POST "https://your-api.hf.space/convert/jpeg/lossy/75" \
   -o output.jpg
 ```
-### 2. 健康检查
 **端点**: `GET /health`
@@ -147,7 +183,15 @@ docker run -p 8000:8000 magick-api
 ## 🐛 已知问题与修复
-### V3 版本修复 (当前版本)
 1. ✅ **修复 Timeout 实现**: 超时现在正确应用于进程执行而非进程创建
 2. ✅ **修复 WebP 无损质量**: 无损模式下 quality 固定为 100

 ## ✨ 功能特性
+* **🌐 图形化界面**: 访问根路径即可使用现代化 Web 上传界面，零编程门槛
 * **🎯 动态路径 API**: 通过 URL 路径直接指定目标格式、转换模式和质量参数
+* **📤 双上传模式**: 支持网页表单上传和 RESTful API 调用两种方式
 * **🎬 动画支持**: 完整支持 GIF、Animated WebP/AVIF/APNG 等动画格式
 * **🔄 多格式转换**: 支持 AVIF、WebP、JPEG、PNG、GIF、HEIF 格式互转
 * **⚙️ 灵活配置**: 支持有损/无损两种模式，质量参数可在 0-100 范围自由调节
 ## 📡 API 端点
+### 1. Web 上传界面 (新功能!)
+**端点**: `GET /`
+访问根路径即可打开用户友好的图形化上传界面，无需编程知识即可使用。
+**特点**:
+- 🎨 现代化响应式界面
+- 📱 支持移动设备
+- 🖱️ 拖拽上传支持
+- 📊 实时参数预览
+- 🔗 快速访问 API 文档
+**表单上传端点**: `POST /`
+支持通过 HTML 表单提交转换请求（与网页界面使用相同端点）。
+**表单参数**:
+- `file`: 图像文件（必需）
+- `target_format`: 目标格式（默认: `webp`）
+- `mode`: 转换模式（默认: `lossy`）
+- `setting`: 质量参数 0-100（默认: `80`）
+**示例**:
+```bash
+# 使用表单方式上传（与网页界面相同）
+curl -X POST "http://localhost:8000/" \
+  -F "file=@input.jpg" \
+  -F "target_format=avif" \
+  -F "mode=lossy" \
+  -F "setting=85" \
+  -o output.avif
+```
+### 2. API 端点（程序化调用）
 **端点**: `POST /convert/{target_format}/{mode}/{setting}`
   -o output.jpg
 ```
+### 3. 健康检查
 **端点**: `GET /health`
 ## 🐛 已知问题与修复
+### V4 版本更新 (当前版本)
+1. ✅ **新增 Web 上传界面**: 在根路径 `/` 提供现代化图形化上传界面
+2. ✅ **新增表单上传 API**: 支持通过 `POST /` 使用表单数据上传
+3. ✅ **代码架构重构**: 提取核心转换逻辑，实现代码复用
+4. ✅ **改进用户体验**: 实时参数提示、拖拽上传、响应式设计
+5. ✅ **完善 API 文档**: 在 Web 界面提供快速访问链接
+### V3 版本修复
 1. ✅ **修复 Timeout 实现**: 超时现在正确应用于进程执行而非进程创建
 2. ✅ **修复 WebP 无损质量**: 无损模式下 quality 固定为 100

main.py CHANGED Viewed

@@ -20,9 +20,10 @@ from fastapi import (
     UploadFile,
     HTTPException,
     BackgroundTasks,
-    Path
 )
-from fastapi.responses import FileResponse, JSONResponse
 import subprocess
 import asyncio
 import tempfile
@@ -57,9 +58,9 @@ ConversionMode = Literal["lossless", "lossy"]
 # --- 3. FastAPI 应用初始化 ---
 app = FastAPI(
-    title="Magick 动态图像转换器 (V3)",
-    description="通过动态 API 路径实现多种格式的(无)损图像转换，支持动图。",
-    version="3.0.0"
 )
 # 启动时确保临时目录存在
@@ -102,7 +103,309 @@ def cleanup_temp_dir(temp_dir: str):
     except Exception as cleanup_error:
         logger.error(f"后台清理：删除 {temp_dir} 失败: {cleanup_error}", exc_info=True)
-# --- 5. API 端点 ---
 @app.get("/health", summary="服务健康检查")
 async def health_check():
@@ -143,35 +446,28 @@ async def health_check():
         logger.error(f"健康检查失败: {str(e)}")
         return JSONResponse(status_code=500, content={"status": "unhealthy", "error": str(e)})
-@app.post(
-    "/convert/{target_format}/{mode}/{setting}",
-    summary="动态转换图像 (支持动图)",
-    response_class=FileResponse,
-    responses={
-        200: {"description": "转换成功，返回图像文件"},
-        400: {"description": "请求无效（例如文件过大）"},
-        422: {"description": "路径参数验证失败（例如格式不支持）"},
-        500: {"description": "服务器内部转换失败"},
-        504: {"description": "转换处理超时"}
-    }
-)
-async def convert_image_dynamic(
     background_tasks: BackgroundTasks,
-    target_format: TargetFormat,
-    mode: ConversionMode,
-    setting: int = Path(..., ge=0, le=100, description="质量(有损) 或 压缩速度(无损) (0-100)"),
-    file: UploadFile = File(..., description="要转换的图像文件 (支持动图)")
-):
     """
-    通过动态 URL 路径接收图像文件，执行转换并返回结果。
-    - **target_format**: 目标格式 (avif, webp, jpeg, png, gif, heif)
-    - **mode**: 转换模式 (lossless, lossy)
-    - **setting**: 模式设置 (0-100)
-        - mode=lossy: 0=最差质量, 100=最佳质量
-        - mode=lossless: 0=最慢/最佳压缩, 100=最快/最差压缩
     """
-    logger.info(f"收到动态转换请求: {target_format}/{mode}/{setting} (文件: {file.filename})")
     # 预检查: AVIF/HEIF 格式需要 heif-enc 依赖
     if target_format in ["avif", "heif"]:
@@ -386,4 +682,94 @@ async def convert_image_dynamic(
         await file.close()
         # 备用清理：仅当未注册后台任务时立即清理
         if not cleanup_scheduled and os.path.exists(temp_dir):
-            cleanup_temp_dir(temp_dir)

     UploadFile,
     HTTPException,
     BackgroundTasks,
+    Path,
+    Form
 )
+from fastapi.responses import FileResponse, JSONResponse, HTMLResponse
 import subprocess
 import asyncio
 import tempfile
 # --- 3. FastAPI 应用初始化 ---
 app = FastAPI(
+    title="Magick 动态图像转换器 (V4)",
+    description="通过 Web 界面或 API 实现多种格式的(无)损图像转换，支持动图。提供现代化图形上传界面和灵活的 RESTful API。",
+    version="4.0.0"
 )
 # 启动时确保临时目录存在
     except Exception as cleanup_error:
         logger.error(f"后台清理：删除 {temp_dir} 失败: {cleanup_error}", exc_info=True)
+# --- 5. HTML 模板 ---
+HTML_UPLOAD_PAGE = """
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Magick 图像转换器</title>
+    <style>
+        * { box-sizing: border-box; margin: 0; padding: 0; }
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            min-height: 100vh;
+            padding: 20px;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+        }
+        .container {
+            background: white;
+            border-radius: 20px;
+            box-shadow: 0 20px 60px rgba(0,0,0,0.3);
+            max-width: 600px;
+            width: 100%;
+            padding: 40px;
+        }
+        h1 {
+            color: #333;
+            margin-bottom: 10px;
+            font-size: 28px;
+            text-align: center;
+        }
+        .subtitle {
+            color: #666;
+            text-align: center;
+            margin-bottom: 30px;
+            font-size: 14px;
+        }
+        .form-group {
+            margin-bottom: 25px;
+        }
+        label {
+            display: block;
+            color: #333;
+            font-weight: 600;
+            margin-bottom: 8px;
+            font-size: 14px;
+        }
+        .file-input-wrapper {
+            position: relative;
+            border: 2px dashed #667eea;
+            border-radius: 10px;
+            padding: 30px;
+            text-align: center;
+            background: #f8f9ff;
+            cursor: pointer;
+            transition: all 0.3s;
+        }
+        .file-input-wrapper:hover {
+            border-color: #764ba2;
+            background: #f0f2ff;
+        }
+        .file-input-wrapper input[type="file"] {
+            position: absolute;
+            width: 100%;
+            height: 100%;
+            top: 0;
+            left: 0;
+            opacity: 0;
+            cursor: pointer;
+        }
+        .file-label {
+            color: #667eea;
+            font-weight: 600;
+        }
+        select, input[type="range"] {
+            width: 100%;
+            padding: 12px;
+            border: 2px solid #e0e0e0;
+            border-radius: 8px;
+            font-size: 14px;
+            transition: border-color 0.3s;
+        }
+        select:focus {
+            outline: none;
+            border-color: #667eea;
+        }
+        .radio-group {
+            display: flex;
+            gap: 20px;
+        }
+        .radio-label {
+            display: flex;
+            align-items: center;
+            cursor: pointer;
+            font-weight: normal;
+        }
+        .radio-label input[type="radio"] {
+            margin-right: 8px;
+            cursor: pointer;
+        }
+        .slider-container {
+            display: flex;
+            align-items: center;
+            gap: 15px;
+        }
+        input[type="range"] {
+            flex: 1;
+        }
+        .slider-value {
+            min-width: 45px;
+            text-align: center;
+            font-weight: 600;
+            color: #667eea;
+            font-size: 18px;
+        }
+        .param-hint {
+            background: #f0f2ff;
+            padding: 12px;
+            border-radius: 8px;
+            font-size: 13px;
+            color: #555;
+            margin-top: 10px;
+            border-left: 4px solid #667eea;
+        }
+        .submit-btn {
+            width: 100%;
+            padding: 15px;
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            color: white;
+            border: none;
+            border-radius: 10px;
+            font-size: 16px;
+            font-weight: 600;
+            cursor: pointer;
+            transition: transform 0.2s, box-shadow 0.2s;
+        }
+        .submit-btn:hover {
+            transform: translateY(-2px);
+            box-shadow: 0 10px 20px rgba(102, 126, 234, 0.3);
+        }
+        .submit-btn:active {
+            transform: translateY(0);
+        }
+        .links {
+            margin-top: 25px;
+            text-align: center;
+            padding-top: 25px;
+            border-top: 1px solid #e0e0e0;
+        }
+        .links a {
+            color: #667eea;
+            text-decoration: none;
+            margin: 0 15px;
+            font-size: 14px;
+            font-weight: 500;
+        }
+        .links a:hover {
+            text-decoration: underline;
+        }
+        .selected-file {
+            margin-top: 10px;
+            color: #28a745;
+            font-size: 13px;
+            font-weight: 500;
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>🧙‍♂️ Magick 图像转换器</h1>
+        <p class="subtitle">支持多格式转换 | 有损/无损模式 | 支持动画图像</p>
+        <form id="uploadForm" action="/" method="POST" enctype="multipart/form-data">
+            <div class="form-group">
+                <label>选择图像文件</label>
+                <div class="file-input-wrapper">
+                    <input type="file" name="file" id="fileInput" accept="image/*" required>
+                    <div class="file-label">
+                        📁 点击选择或拖拽文件到此处
+                        <div style="font-size: 12px; color: #999; margin-top: 8px;">
+                            支持 JPG, PNG, GIF, WebP, AVIF, HEIF 等格式
+                        </div>
+                    </div>
+                </div>
+                <div id="selectedFile" class="selected-file"></div>
+            </div>
+            <div class="form-group">
+                <label for="target_format">目标格式</label>
+                <select name="target_format" id="target_format" required>
+                    <option value="webp" selected>WebP - 现代高效格式</option>
+                    <option value="avif">AVIF - 最新一代格式</option>
+                    <option value="jpeg">JPEG - 经典有损格式</option>
+                    <option value="png">PNG - 无损格式</option>
+                    <option value="gif">GIF - 动画格式</option>
+                    <option value="heif">HEIF - 高效图像格式</option>
+                </select>
+            </div>
+            <div class="form-group">
+                <label>转换模式</label>
+                <div class="radio-group">
+                    <label class="radio-label">
+                        <input type="radio" name="mode" value="lossy" checked>
+                        有损压缩 (更小体积)
+                    </label>
+                    <label class="radio-label">
+                        <input type="radio" name="mode" value="lossless">
+                        无损压缩 (保持质量)
+                    </label>
+                </div>
+            </div>
+            <div class="form-group">
+                <label for="setting">质量参数</label>
+                <div class="slider-container">
+                    <input type="range" name="setting" id="setting" min="0" max="100" value="80">
+                    <span class="slider-value" id="settingValue">80</span>
+                </div>
+                <div class="param-hint" id="paramHint">
+                    质量: 80 - 高质量 (0=最低质量，100=最高质量)
+                </div>
+            </div>
+            <button type="submit" class="submit-btn">🚀 开始转换</button>
+        </form>
+        <div class="links">
+            <a href="/docs" target="_blank">📖 API 文档</a>
+            <a href="/health" target="_blank">🏥 健康检查</a>
+        </div>
+    </div>
+    <script>
+        // 文件选择提示
+        const fileInput = document.getElementById('fileInput');
+        const selectedFile = document.getElementById('selectedFile');
+        fileInput.addEventListener('change', function() {
+            if (this.files.length > 0) {
+                selectedFile.textContent = '✓ 已选择: ' + this.files[0].name;
+            }
+        });
+        // 滑块实时更新
+        const slider = document.getElementById('setting');
+        const sliderValue = document.getElementById('settingValue');
+        const paramHint = document.getElementById('paramHint');
+        const modeRadios = document.querySelectorAll('input[name="mode"]');
+        function updateHint() {
+            const mode = document.querySelector('input[name="mode"]:checked').value;
+            const value = slider.value;
+            sliderValue.textContent = value;
+            if (mode === 'lossy') {
+                let quality = '中等';
+                if (value >= 90) quality = '极高';
+                else if (value >= 80) quality = '高';
+                else if (value >= 60) quality = '中等';
+                else if (value >= 40) quality = '中低';
+                else quality = '低';
+                paramHint.textContent = `质量: ${value} - ${quality}质量 (0=最低质量，100=最高质量)`;
+            } else {
+                let speed = '平衡';
+                if (value <= 20) speed = '最慢/最佳压缩';
+                else if (value <= 40) speed = '较慢/较好压缩';
+                else if (value <= 60) speed = '平衡';
+                else if (value <= 80) speed = '较快/较差压缩';
+                else speed = '最快/最差压缩';
+                paramHint.textContent = `压缩速度: ${value} - ${speed} (0=最慢/最佳，100=最快/最差)`;
+            }
+        }
+        slider.addEventListener('input', updateHint);
+        modeRadios.forEach(radio => radio.addEventListener('change', updateHint));
+        // 表单提交处理
+        const form = document.getElementById('uploadForm');
+        const submitBtn = form.querySelector('.submit-btn');
+        const originalBtnText = submitBtn.textContent;
+        form.addEventListener('submit', function() {
+            submitBtn.textContent = '⏳ 转换中...';
+            submitBtn.disabled = true;
+        });
+    </script>
+</body>
+</html>
+"""
+# --- 6. API 端点 ---
+@app.get("/", response_class=HTMLResponse, summary="上传界面")
+async def root():
+    """
+    返回用户友好的HTML上传表单页面。
+    提供图形化界面进行图像转换，无需编程知识。
+    """
+    return HTML_UPLOAD_PAGE
 @app.get("/health", summary="服务健康检查")
 async def health_check():
         logger.error(f"健康检查失败: {str(e)}")
         return JSONResponse(status_code=500, content={"status": "unhealthy", "error": str(e)})
+async def _perform_conversion(
     background_tasks: BackgroundTasks,
+    file: UploadFile,
+    target_format: str,
+    mode: str,
+    setting: int
+) -> FileResponse:
     """
+    核心图像转换逻辑（内部函数）。
+    被多个端点复用以避免代码重复。
+    Args:
+        background_tasks: FastAPI后台任务对象
+        file: 上传的图像文件
+        target_format: 目标格式 (avif, webp, jpeg, png, gif, heif)
+        mode: 转换模式 (lossy, lossless)
+        setting: 质量/压缩参数 (0-100)
+    Returns:
+        FileResponse: 转换后的图像文件
     """
+    logger.info(f"开始转换: {target_format}/{mode}/{setting} (文件: {file.filename})")
     # 预检查: AVIF/HEIF 格式需要 heif-enc 依赖
     if target_format in ["avif", "heif"]:
         await file.close()
         # 备用清理：仅当未注册后台任务时立即清理
         if not cleanup_scheduled and os.path.exists(temp_dir):
+            cleanup_temp_dir(temp_dir)
+@app.post("/", response_class=FileResponse, summary="简化上传转换")
+async def upload_convert(
+    background_tasks: BackgroundTasks,
+    file: UploadFile = File(..., description="要转换的图像文件"),
+    target_format: str = Form("webp", description="目标格式"),
+    mode: str = Form("lossy", description="转换模式"),
+    setting: int = Form(80, ge=0, le=100, description="质量参数")
+):
+    """
+    通过HTML表单上传并转换图像。
+    这个端点接收表单数据（而非URL路径参数），适合从网页表单调用。
+    内部调用与 /convert/{format}/{mode}/{setting} 相同的转换逻辑。
+    - **file**: 图像文件
+    - **target_format**: 目标格式 (avif, webp, jpeg, png, gif, heif)，默认 webp
+    - **mode**: 转换模式 (lossy, lossless)，默认 lossy
+    - **setting**: 质量/压缩参数 (0-100)，默认 80
+    """
+    # 验证参数
+    valid_formats = ["avif", "webp", "jpeg", "png", "gif", "heif"]
+    if target_format not in valid_formats:
+        raise HTTPException(
+            status_code=422,
+            detail=f"Invalid target_format: {target_format}. Must be one of {valid_formats}"
+        )
+    valid_modes = ["lossy", "lossless"]
+    if mode not in valid_modes:
+        raise HTTPException(
+            status_code=422,
+            detail=f"Invalid mode: {mode}. Must be one of {valid_modes}"
+        )
+    if not (0 <= setting <= 100):
+        raise HTTPException(
+            status_code=422,
+            detail=f"Invalid setting: {setting}. Must be between 0 and 100"
+        )
+    logger.info(f"收到表单上传请求: {target_format}/{mode}/{setting} (文件: {file.filename})")
+    # 调用核心转换逻辑
+    return await _perform_conversion(
+        background_tasks=background_tasks,
+        file=file,
+        target_format=target_format,
+        mode=mode,
+        setting=setting
+    )
+@app.post(
+    "/convert/{target_format}/{mode}/{setting}",
+    summary="动态转换图像 (支持动图)",
+    response_class=FileResponse,
+    responses={
+        200: {"description": "转换成功，返回图像文件"},
+        400: {"description": "请求无效（例如文件过大）"},
+        422: {"description": "路径参数验证失败（例如格式不支持）"},
+        500: {"description": "服务器内部转换失败"},
+        504: {"description": "转换处理超时"}
+    }
+)
+async def convert_image_dynamic(
+    background_tasks: BackgroundTasks,
+    target_format: TargetFormat,
+    mode: ConversionMode,
+    setting: int = Path(..., ge=0, le=100, description="质量(有损) 或 压缩速度(无损) (0-100)"),
+    file: UploadFile = File(..., description="要转换的图像文件 (支持动图)")
+):
+    """
+    通过动态 URL 路径接收图像文件，执行转换并返回结果。
+    - **target_format**: 目标格式 (avif, webp, jpeg, png, gif, heif)
+    - **mode**: 转换模式 (lossless, lossy)
+    - **setting**: 模式设置 (0-100)
+        - mode=lossy: 0=最差质量, 100=最佳质量
+        - mode=lossless: 0=最慢/最佳压缩, 100=最快/最差压缩
+    """
+    logger.info(f"收到API转换请求: {target_format}/{mode}/{setting} (文件: {file.filename})")
+    # 调用核心转换逻辑
+    return await _perform_conversion(
+        background_tasks=background_tasks,
+        file=file,
+        target_format=target_format,
+        mode=mode,
+        setting=setting
+    )