feat(api): simplify /inpaint response to return only filename; update docs

HTTP_API_Documentation.txt

@@ -1,49 +1,182 @@
-HTTP API Documentation
+HTTP API Documentation - Photo Object Removal Service
 
-- Base URL: https://logicgoinfotechspaces-object-remover.hf.space
-- Auth (optional): set API_TOKEN on server; send Authorization: Bearer <API_TOKEN>
+Base URL: https://logicgoinfotechspaces-object-remover.hf.space
 
-Endpoints
-- GET /health
-- POST /upload-image (form-data: image=file) -> {"id":"<image_id>","filename":"..."}
-- POST /upload-mask (form-data: mask=file) -> {"id":"<mask_id>","filename":"..."}
-- POST /inpaint (JSON: { "image_id": "...", "mask_id": "..." }) -> returns image/png directly
-- POST /inpaint-multipart (form-data: image, mask) -> {"result":"output_xxx.png"}
-- GET /download/{filename} (only needed if you have a filename)
+Authentication:
+- Optional Bearer token authentication
+- Set API_TOKEN environment variable on server to enable auth
+- Send header: Authorization: Bearer <API_TOKEN>
+- If API_TOKEN not set, all endpoints are publicly accessible
 
-Curl examples
+Available Endpoints:
 
-Health:
-curl -H "Authorization: Bearer <API_TOKEN>" https://logicgoinfotechspaces-object-remover.hf.space/health
+1. GET /health
+   - Health check endpoint
+   - Returns: {"status":"healthy"}
+   - No authentication required
 
-Upload image:
+2. POST /upload-image
+   - Upload an image file for processing
+   - Content-Type: multipart/form-data
+   - Form field: image (file)
+   - Returns: {"id":"<image_id>","filename":"original_name.png"}
+   - Supported formats: PNG, JPG, JPEG
+
+3. POST /upload-mask
+   - Upload a mask file indicating areas to remove
+   - Content-Type: multipart/form-data
+   - Form field: mask (file)
+   - Returns: {"id":"<mask_id>","filename":"mask.png"}
+   - Mask formats:
+     * RGBA PNG: pixels with alpha=0 are treated as areas to remove
+     * RGB/Grayscale: pixels with value > 0 are treated as areas to remove
+
+4. POST /inpaint
+   - Process inpainting using uploaded image and mask IDs
+   - Content-Type: application/json
+   - Body: {"image_id":"<image_id>","mask_id":"<mask_id>"}
+   - Returns: {"result":"output_xxx.png"}
+   - Simple response with just the filename
+
+5. POST /inpaint-url
+   - Same as /inpaint but returns JSON with public download URL
+   - Content-Type: application/json
+   - Body: {"image_id":"<image_id>","mask_id":"<mask_id>"}
+   - Returns: {"result":"output_xxx.png","url":"https://.../download/output_xxx.png"}
+   - Use this endpoint if you need a shareable URL
+
+6. POST /inpaint-multipart
+   - Process inpainting with direct file upload (no separate upload steps)
+   - Content-Type: multipart/form-data
+   - Form fields: image (file), mask (file)
+   - Returns: {"result":"output_xxx.png","url":"https://.../download/output_xxx.png"}
+
+7. GET /download/{filename}
+   - Download result image by filename
+   - Public endpoint (no authentication required)
+   - Returns: image/png (binary data)
+   - Can be opened directly in browser
+
+8. GET /result/{filename}
+   - View result image directly in browser
+   - Public endpoint (no authentication required)
+   - Returns: image/png with proper content-type for viewing
+   - Optimized for browser display
+
+CURL EXAMPLES:
+
+1. Health Check:
+curl -H "Authorization: Bearer <API_TOKEN>" \
+  https://logicgoinfotechspaces-object-remover.hf.space/health
+
+2. Upload Image:
 curl -H "Authorization: Bearer <API_TOKEN>" \
   -F [email protected] \
   https://logicgoinfotechspaces-object-remover.hf.space/upload-image
+# Response: {"id":"9cf61445-f83b-4c97-9272-c81647f90d68","filename":"image.png"}
 
-Upload mask (PNG recommended):
+3. Upload Mask:
 curl -H "Authorization: Bearer <API_TOKEN>" \
   -F [email protected] \
   https://logicgoinfotechspaces-object-remover.hf.space/upload-mask
+# Response: {"id":"d044a390-dde2-408a-b7cf-d508385e56ed","filename":"mask.png"}
 
-Inpaint (IDs) — returns image directly:
+4. Inpaint (returns simple JSON):
 curl -H "Authorization: Bearer <API_TOKEN>" \
   -H "Content-Type: application/json" \
-  -d '{"image_id":"<image_id>","mask_id":"<mask_id>"}' \
-  https://logicgoinfotechspaces-object-remover.hf.space/inpaint \
-  -o result.png
+  -d '{"image_id":"9cf61445-f83b-4c97-9272-c81647f90d68","mask_id":"d044a390-dde2-408a-b7cf-d508385e56ed"}' \
+  https://logicgoinfotechspaces-object-remover.hf.space/inpaint
+# Response: {"result":"output_b09568698bbd4aa591b1598c01f2f745.png"}
+
+5. Inpaint-URL (returns JSON with public URL):
+curl -H "Authorization: Bearer <API_TOKEN>" \
+  -H "Content-Type: application/json" \
+  -d '{"image_id":"9cf61445-f83b-4c97-9272-c81647f90d68","mask_id":"d044a390-dde2-408a-b7cf-d508385e56ed"}' \
+  https://logicgoinfotechspaces-object-remover.hf.space/inpaint-url
+# Response: {"result":"output_b09568698bbd4aa591b1598c01f2f745.png","url":"https://logicgoinfotechspaces-object-remover.hf.space/download/output_b09568698bbd4aa591b1598c01f2f745.png"}
 
-Inpaint (multipart) — returns filename:
+6. Inpaint Multipart (one-step processing):
 curl -H "Authorization: Bearer <API_TOKEN>" \
   -F [email protected] \
   -F [email protected] \
   https://logicgoinfotechspaces-object-remover.hf.space/inpaint-multipart
+# Response: {"result":"output_xxx.png","url":"https://logicgoinfotechspaces-object-remover.hf.space/download/output_xxx.png"}
 
-Download (only if you have a filename):
-curl -H "Authorization: Bearer <API_TOKEN>" \
-  -L https://logicgoinfotechspaces-object-remover.hf.space/download/output_xxx.png \
+7. Download Result (public, no auth):
+curl -L https://logicgoinfotechspaces-object-remover.hf.space/download/output_b09568698bbd4aa591b1598c01f2f745.png \
+  -o result.png
+
+8. View Result in Browser (public, no auth):
+curl -L https://logicgoinfotechspaces-object-remover.hf.space/result/output_b09568698bbd4aa591b1598c01f2f745.png \
   -o result.png
 
-Notes
-- For masks: RGBA with alpha=0 = remove; otherwise any pixel > 0 = remove.
-- 404 Not Found on /inpaint usually means the server restarted and IDs expired — re-upload to get fresh IDs.
+POSTMAN EXAMPLES:
+
+1. Health Check:
+   Method: GET
+   URL: https://logicgoinfotechspaces-object-remover.hf.space/health
+   Headers: Authorization: Bearer <API_TOKEN>
+
+2. Upload Image:
+   Method: POST
+   URL: https://logicgoinfotechspaces-object-remover.hf.space/upload-image
+   Headers: Authorization: Bearer <API_TOKEN>
+   Body: form-data
+   Key: image, Type: File, Value: select your image file
+
+3. Upload Mask:
+   Method: POST
+   URL: https://logicgoinfotechspaces-object-remover.hf.space/upload-mask
+   Headers: Authorization: Bearer <API_TOKEN>
+   Body: form-data
+   Key: mask, Type: File, Value: select your mask file
+
+4. Inpaint (returns simple JSON):
+   Method: POST
+   URL: https://logicgoinfotechspaces-object-remover.hf.space/inpaint
+   Headers: 
+     - Authorization: Bearer <API_TOKEN>
+     - Content-Type: application/json
+   Body: raw JSON
+   {
+     "image_id": "9cf61445-f83b-4c97-9272-c81647f90d68",
+     "mask_id": "d044a390-dde2-408a-b7cf-d508385e56ed"
+   }
+
+5. Inpaint Multipart (one-step):
+   Method: POST
+   URL: https://logicgoinfotechspaces-object-remover.hf.space/inpaint-multipart
+   Headers: Authorization: Bearer <API_TOKEN>
+   Body: form-data
+   Key: image, Type: File, Value: select your image file
+   Key: mask, Type: File, Value: select your mask file
+
+IMPORTANT NOTES:
+
+Authentication:
+- If API_TOKEN is set on the server, include Authorization header
+- If API_TOKEN is not set, omit Authorization header
+- /download/{filename} is always public (no auth required)
+
+Mask Formats:
+- RGBA PNG: pixels with alpha=0 are treated as areas to remove
+- RGB/Grayscale: pixels with value > 0 are treated as areas to remove
+- Create mask by painting white/colored areas over objects you want to remove
+
+Error Handling:
+- 404 Not Found on /inpaint: server restarted, IDs expired - re-upload files
+- 401 Unauthorized: missing or invalid API_TOKEN
+- 403 Forbidden: wrong API_TOKEN
+
+Workflow Options:
+1. Two-step: upload-image → upload-mask → inpaint (get filename)
+2. One-step: inpaint-multipart (upload and process in single request)
+3. Direct access: use /download/{filename} or /result/{filename} with returned filename
+
+Browser Access:
+- Paste any /download/{filename} or /result/{filename} URL directly in Chrome to view the result
+- No authentication required for download/view URLs
+- /result/{filename} is optimized for browser viewing
+- Examples: 
+  * https://logicgoinfotechspaces-object-remover.hf.space/download/output_b09568698bbd4aa591b1598c01f2f745.png
+  * https://logicgoinfotechspaces-object-remover.hf.space/result/output_b09568698bbd4aa591b1598c01f2f745.png

README.md

@@ -18,14 +18,17 @@ Endpoints:
 - `GET /health` → {"status":"healthy"}
 - `POST /upload-image` (form-data: image=file) → {"id":"<image_id>","filename":"name.png"}
 - `POST /upload-mask` (form-data: mask=file) → {"id":"<mask_id>","filename":"mask.png"}
-- `POST /inpaint` (JSON: {image_id, mask_id}) → returns result directly (no download step)
+- `POST /inpaint` (JSON: {image_id, mask_id}) → {"result":"output_xxx.png"}
 - `POST /inpaint-url` (JSON: {image_id, mask_id}) → {"result":"output_xxx.png","url":"https://.../download/output_xxx.png"}
 - `POST /inpaint-multipart` (form-data: image=file, mask=file) → {"result":"output_xxx.png"}
 - `GET /download/{filename}` → image file (public; optional for ID-based inpaint)
+- `GET /result/{filename}` → view result image in browser (public)
 - `GET /logs` → recent uploads/results
 
 Note:
-- `POST /inpaint` returns image bytes directly. Use `POST /inpaint-url` if you need a shareable URL in the response.
+- `POST /inpaint` returns simple JSON with just the filename.
+- `POST /inpaint-url` returns JSON with filename and shareable URL.
+- Use `/download/{filename}` or `/result/{filename}` to access the result image.
 
 Local run:
 - Install deps: `python3 -m pip install -r requirements.txt`

api/main.py

@@ -61,6 +61,7 @@ def root() -> Dict[str, object]:
             "POST /inpaint": "JSON: {image_id, mask_id}",
             "POST /inpaint-multipart": "form-data: image=file, mask=file",
             "GET /download/{filename}": "download result image",
+            "GET /result/{filename}": "view result image in browser",
             "GET /logs": "recent uploads/results",
         },
         "auth": "set API_TOKEN env var to require Authorization: Bearer <token> (except /health)",
@@ -129,7 +130,7 @@ def _load_rgba_mask_from_image(img: Image.Image) -> np.ndarray:
 
 
 @app.post("/inpaint")
-def inpaint(req: InpaintRequest, _: None = Depends(bearer_auth)):
+def inpaint(req: InpaintRequest, _: None = Depends(bearer_auth)) -> Dict[str, str]:
     if req.image_id not in file_store or file_store[req.image_id]["type"] != "image":
         raise HTTPException(status_code=404, detail="image_id not found")
     if req.mask_id not in file_store or file_store[req.mask_id]["type"] != "mask":
@@ -145,7 +146,7 @@ def inpaint(req: InpaintRequest, _: None = Depends(bearer_auth)):
     Image.fromarray(result).save(result_path)
 
     logs.append({"result": result_name, "timestamp": datetime.utcnow().isoformat()})
-    return FileResponse(result_path, media_type="image/png", filename=result_name)
+    return {"result": result_name}
 
 
 @app.post("/inpaint-url")
@@ -212,6 +213,15 @@ def download_file(filename: str):
     return FileResponse(path)
 
 
+@app.get("/result/{filename}")
+def view_result(filename: str):
+    """View result image directly in browser (same as download but with proper content-type for viewing)"""
+    path = os.path.join(OUTPUT_DIR, filename)
+    if not os.path.isfile(path):
+        raise HTTPException(status_code=404, detail="file not found")
+    return FileResponse(path, media_type="image/png")
+
+
 @app.get("/logs")
 def get_logs(_: None = Depends(bearer_auth)) -> JSONResponse:
     return JSONResponse(content=logs)