mirror of
https://github.com/snapotter-hq/SnapOtter.git
synced 2026-08-03 07:46:42 +02:00
docs: add transparency-fixer endpoint documentation
This commit is contained in:
SnapOtter
@@ -3,7 +3,7 @@ info:
|
||||
title: SnapOtter API
|
||||
version: 1.15.9
|
||||
description: |
|
||||
REST API for SnapOtter, a self-hosted image processing platform with 47 tools.
|
||||
REST API for SnapOtter, a self-hosted image processing platform with 48 tools.
|
||||
|
||||
## Authentication
|
||||
|
||||
@@ -3225,6 +3225,81 @@ paths:
|
||||
schema:
|
||||
$ref: "#/components/schemas/UnauthorizedError"
|
||||
|
||||
/api/v1/tools/transparency-fixer:
|
||||
post:
|
||||
tags: [Tools]
|
||||
summary: Fix fake transparency
|
||||
description: |
|
||||
Fix "fake transparent" PNGs that have fringing, halos, or semi-transparent
|
||||
artifacts from a previous background removal. Uses BiRefNet HR-matting
|
||||
(2048x2048) to produce a clean alpha channel with configurable defringe
|
||||
processing. Falls back to birefnet-general, then u2net on OOM. Requires
|
||||
the background-removal feature bundle to be installed.
|
||||
security:
|
||||
- bearerAuth: []
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
multipart/form-data:
|
||||
schema:
|
||||
type: object
|
||||
required: [file]
|
||||
properties:
|
||||
file:
|
||||
type: string
|
||||
format: binary
|
||||
description: PNG image with fake or damaged transparency
|
||||
settings:
|
||||
type: string
|
||||
description: |
|
||||
JSON string with options:
|
||||
- `defringe` (number 0-100, default 30) — Edge defringe strength to remove color contamination
|
||||
- `outputFormat` (string, default "png") — One of: png, webp
|
||||
clientJobId:
|
||||
type: string
|
||||
description: Client-provided job ID for SSE progress tracking
|
||||
responses:
|
||||
"200":
|
||||
description: Image with corrected transparency
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: "#/components/schemas/ToolResponse"
|
||||
- type: object
|
||||
properties:
|
||||
width:
|
||||
type: integer
|
||||
height:
|
||||
type: integer
|
||||
model:
|
||||
type: string
|
||||
description: AI model that was used (may differ from default due to OOM fallback)
|
||||
"400":
|
||||
description: Invalid input
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
"401":
|
||||
description: Authentication required
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/UnauthorizedError"
|
||||
"422":
|
||||
description: Processing failed
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
"501":
|
||||
description: Feature not installed
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/FeatureNotInstalledError"
|
||||
|
||||
/api/v1/tools/upscale:
|
||||
post:
|
||||
tags: [Tools]
|
||||
|
||||
@@ -39,7 +39,7 @@ function generateLlmsTxt(spec: OpenAPISpec): string {
|
||||
lines.push(`# ${spec.info.title}`);
|
||||
lines.push("");
|
||||
lines.push(
|
||||
"> Self-hosted image processing API with 47 tools. Resize, compress, convert, remove backgrounds, upscale, run OCR, and more.",
|
||||
"> Self-hosted image processing API with 48 tools. Resize, compress, convert, remove backgrounds, upscale, run OCR, and more.",
|
||||
);
|
||||
lines.push("");
|
||||
lines.push("## Docs");
|
||||
|
||||
@@ -4,7 +4,7 @@ import llmstxt from "vitepress-plugin-llms";
|
||||
export default defineConfig({
|
||||
title: "SnapOtter",
|
||||
description:
|
||||
"Documentation for SnapOtter - A Self Hosted Image Manipulator. 47 tools, local AI, pipelines, REST API.",
|
||||
"Documentation for SnapOtter - A Self Hosted Image Manipulator. 48 tools, local AI, pipelines, REST API.",
|
||||
base: "/",
|
||||
appearance: { initialValue: "light" },
|
||||
srcDir: ".",
|
||||
@@ -48,7 +48,7 @@ export default defineConfig({
|
||||
`,
|
||||
customTemplateVariables: {
|
||||
description:
|
||||
"SnapOtter is a self-hosted, open-source image processing platform with 47 tools including AI/ML. Runs in a single Docker container with GPU auto-detection.",
|
||||
"SnapOtter is a self-hosted, open-source image processing platform with 48 tools including AI/ML. Runs in a single Docker container with GPU auto-detection.",
|
||||
details:
|
||||
"Resize, compress, convert, remove backgrounds, upscale, run OCR, and more - without sending images to external services.",
|
||||
},
|
||||
|
||||
+26
-1
@@ -2,7 +2,7 @@
|
||||
|
||||
The `@snapotter/ai` package bridges Node.js to a **persistent Python sidecar** for all ML operations. The dispatcher process stays alive between requests for fast warm-start performance. GPU is auto-detected at startup and used when available.
|
||||
|
||||
14 AI tool routes. All models run locally - no internet required after initial model download.
|
||||
15 AI tool routes. All models run locally - no internet required after initial model download.
|
||||
|
||||
## Architecture
|
||||
|
||||
@@ -26,6 +26,7 @@ Node.js Tool Route
|
||||
├─ noise_removal.py (tiered denoising)
|
||||
├─ red_eye_removal.py (landmark + color analysis)
|
||||
├─ restore.py (scratch repair + enhancement + denoising)
|
||||
├─ transparency_fix.py (BiRefNet HR-matting + defringe)
|
||||
└─ seam_carving (Go caire binary - not Python)
|
||||
```
|
||||
|
||||
@@ -255,3 +256,27 @@ Intelligently resizes images by removing or adding low-energy seams, preserving
|
||||
| `square` | boolean | false | Force square output |
|
||||
|
||||
Max input edge before auto-downscaling: **1200 px**.
|
||||
|
||||
## Transparency Fixer
|
||||
|
||||
**Function:** `fixTransparency`
|
||||
**Tool route:** `transparency-fixer`
|
||||
**Model:** BiRefNet HR-matting (2048x2048 resolution)
|
||||
|
||||
Fixes "fake transparent" PNGs where the background was removed but left behind fringing, halos, or semi-transparent artifacts. Uses BiRefNet's high-resolution matting model to produce a clean alpha channel, then applies configurable defringe processing to remove color contamination along edges.
|
||||
|
||||
**OOM fallback chain:** If BiRefNet HR-matting exceeds available memory, the tool automatically falls back to `birefnet-general`, then to `u2net`.
|
||||
|
||||
**Feature bundle:** Background Removal (shared with Remove Background and Passport Photo).
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `defringe` | number (0-100) | 30 | Edge defringe strength to remove color contamination |
|
||||
| `outputFormat` | `"png"` \| `"webp"` | `"png"` | Output image format |
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:1349/api/v1/tools/transparency-fixer \
|
||||
-H "Authorization: Bearer <token>" \
|
||||
-F "file=@fake-transparent.png" \
|
||||
-F 'settings={"defringe":30,"outputFormat":"png"}'
|
||||
```
|
||||
|
||||
@@ -152,6 +152,7 @@ All AI tools run on your hardware (CPU or NVIDIA GPU). No internet required.
|
||||
| `restore-photo` | Photo Restoration | Multi-step pipeline | `mode` (auto/light/heavy), `scratchRemoval`, `faceEnhancement`, `fidelity`, `denoise`, `denoiseStrength`, `colorize` |
|
||||
| `passport-photo` | Passport Photo | MediaPipe landmarks | `country` (37 countries), `printLayout` (4x6/A4/none), `backgroundColor` |
|
||||
| `content-aware-resize` | Content-Aware Resize | Seam carving (caire) | `width`, `height`, `protectFaces`, `blurRadius`, `sobelThreshold`, `square` |
|
||||
| `transparency-fixer` | Transparency Fixer | BiRefNet HR-matting | `defringe` (0-100), `outputFormat` (png/webp) |
|
||||
|
||||
### Watermark & Overlay
|
||||
|
||||
|
||||
@@ -31,7 +31,7 @@ A bridge layer that calls Python scripts for ML operations. On first use, the br
|
||||
|
||||
**Models are not pre-loaded.** Each tool script loads its model weights from disk at request time and discards them when the request finishes. See [Resource footprint](#resource-footprint) for the full memory profile.
|
||||
|
||||
Supported operations: background removal (rembg/BiRefNet), upscaling (RealESRGAN), face blur (MediaPipe), face enhancement (GFPGAN/CodeFormer), object erasing (LaMa ONNX), OCR (PaddleOCR/Tesseract), colorization (DDColor), noise removal, red eye removal, photo restoration, passport photo generation, and content-aware resize (Go caire binary).
|
||||
Supported operations: background removal (rembg/BiRefNet), upscaling (RealESRGAN), face blur (MediaPipe), face enhancement (GFPGAN/CodeFormer), object erasing (LaMa ONNX), OCR (PaddleOCR/Tesseract), colorization (DDColor), noise removal, red eye removal, photo restoration, passport photo generation, transparency fixing (BiRefNet HR-matting), and content-aware resize (Go caire binary).
|
||||
|
||||
Python scripts live in `packages/ai/python/`. The Docker image pre-downloads all model weights during the build so the container works fully offline.
|
||||
|
||||
@@ -43,7 +43,7 @@ Shared TypeScript types, constants (like `APP_VERSION` and tool definitions), an
|
||||
|
||||
### API (`apps/api`)
|
||||
|
||||
A Fastify v5 server exposing 47 tool routes (33 standard image operations + 14 AI-powered) that handles:
|
||||
A Fastify v5 server exposing 48 tool routes (33 standard image operations + 15 AI-powered) that handles:
|
||||
- File uploads, temporary workspace management, and persistent file storage
|
||||
- User file library with version chains (`user_files` table) -- each processed result links back to its source file and records which tool was applied, with auto-generated thumbnails for the Files page
|
||||
- Tool execution (routes each tool request to the image engine or AI bridge)
|
||||
|
||||
@@ -64,14 +64,14 @@ pnpm dev
|
||||
|
||||
## What You Can Do
|
||||
|
||||
### Image Processing (47 Tools)
|
||||
### Image Processing (48 Tools)
|
||||
|
||||
| Category | Tools |
|
||||
|----------|-------|
|
||||
| **Essentials** | Resize, Crop, Rotate & Flip, Convert, Compress |
|
||||
| **Optimization** | Optimize for Web, Strip Metadata, Edit Metadata, Bulk Rename, Image to PDF, Favicon Generator |
|
||||
| **Adjustments** | Adjust Colors, Sharpening, Replace Color |
|
||||
| **AI Tools** | Remove Background, Upscale, Erase Object, OCR, Blur Faces, Smart Crop, Image Enhancement, Enhance Faces, Colorize, Noise Removal, Red Eye Removal, Restore Photo, Passport Photo, Content-Aware Resize |
|
||||
| **AI Tools** | Remove Background, Upscale, Erase Object, OCR, Blur Faces, Smart Crop, Image Enhancement, Enhance Faces, Colorize, Noise Removal, Red Eye Removal, Restore Photo, Passport Photo, Content-Aware Resize, Transparency Fixer |
|
||||
| **Watermark & Overlay** | Text Watermark, Image Watermark, Text Overlay, Image Composition |
|
||||
| **Utilities** | Image Info, Compare, Find Duplicates, Color Palette, QR Code Generator, Barcode Reader, Image to Base64 |
|
||||
| **Layout** | Collage, Stitch, Split, Border & Frame |
|
||||
|
||||
+3
-3
@@ -4,7 +4,7 @@ layout: home
|
||||
hero:
|
||||
name: "SnapOtter"
|
||||
text: "A Self Hosted Image Manipulator"
|
||||
tagline: 47 tools. Local AI. No cloud. Your images never leave your home.
|
||||
tagline: 48 tools. Local AI. No cloud. Your images never leave your home.
|
||||
actions:
|
||||
- theme: brand
|
||||
text: Get started
|
||||
@@ -14,10 +14,10 @@ hero:
|
||||
link: /api/rest
|
||||
|
||||
features:
|
||||
- title: 47 Image Tools
|
||||
- title: 48 Image Tools
|
||||
details: Resize, crop, compress, convert, watermark, color adjust, vectorize, create GIFs, build collages, generate passport photos, find duplicates, and more.
|
||||
- title: Local AI
|
||||
details: 14 AI-powered tools - remove backgrounds, upscale, enhance images, restore and colorize old photos, erase objects, blur faces, enhance faces, extract text (OCR). All on your hardware, no internet required.
|
||||
details: 15 AI-powered tools - remove backgrounds, upscale, enhance images, restore and colorize old photos, erase objects, blur faces, enhance faces, extract text (OCR), fix fake transparency. All on your hardware, no internet required.
|
||||
- title: Pipelines
|
||||
details: Chain tools into reusable workflows with unlimited steps. Batch process unlimited images at once with a single request.
|
||||
- title: REST API
|
||||
|
||||
@@ -8,12 +8,12 @@ const nunito = Nunito({ subsets: ["latin"], variable: "--font-nunito" });
|
||||
export const metadata: Metadata = {
|
||||
title: "SnapOtter | Self-Hosted Image Processing",
|
||||
description:
|
||||
"47 image processing tools with local AI. Runs 100% offline. No data leaves your network. Open source and free forever.",
|
||||
"48 image processing tools with local AI. Runs 100% offline. No data leaves your network. Open source and free forever.",
|
||||
metadataBase: new URL("https://snapotter.com"),
|
||||
openGraph: {
|
||||
title: "SnapOtter | Self-Hosted Image Processing",
|
||||
description:
|
||||
"47 image processing tools with local AI. Runs 100% offline. No data leaves your network.",
|
||||
"48 image processing tools with local AI. Runs 100% offline. No data leaves your network.",
|
||||
url: "https://snapotter.com",
|
||||
siteName: "SnapOtter",
|
||||
type: "website",
|
||||
@@ -30,7 +30,7 @@ export const metadata: Metadata = {
|
||||
card: "summary_large_image",
|
||||
title: "SnapOtter | Self-Hosted Image Processing",
|
||||
description:
|
||||
"47 image processing tools with local AI. Runs 100% offline. No data leaves your network.",
|
||||
"48 image processing tools with local AI. Runs 100% offline. No data leaves your network.",
|
||||
images: ["/og-image.svg"],
|
||||
},
|
||||
};
|
||||
|
||||
@@ -9,6 +9,7 @@ import {
|
||||
Columns2,
|
||||
Copy,
|
||||
Crop,
|
||||
Droplets,
|
||||
Eraser,
|
||||
Eye,
|
||||
EyeOff,
|
||||
@@ -237,6 +238,12 @@ const tools: { name: string; description: string; category: string; icon: Lucide
|
||||
category: "ai",
|
||||
icon: Scaling,
|
||||
},
|
||||
{
|
||||
name: "Transparency Fixer",
|
||||
description: "Fix fake transparent PNGs with AI matting",
|
||||
category: "ai",
|
||||
icon: Droplets,
|
||||
},
|
||||
// Watermark & Overlay
|
||||
{
|
||||
name: "Text Watermark",
|
||||
@@ -389,7 +396,7 @@ export function BentoGrid() {
|
||||
<div className="mx-auto max-w-6xl">
|
||||
<FadeIn>
|
||||
<h2 className="font-[family-name:var(--font-nunito)] text-center text-3xl font-bold tracking-tight md:text-4xl">
|
||||
47 tools. Zero cloud dependency.
|
||||
48 tools. Zero cloud dependency.
|
||||
</h2>
|
||||
<p className="mx-auto mt-4 max-w-xl text-center text-lg text-muted">
|
||||
Search to find exactly what you need. Every tool runs 100% locally.
|
||||
|
||||
@@ -7,12 +7,12 @@ const freePlan = {
|
||||
price: "Free",
|
||||
subtitle: "For everyone. Forever.",
|
||||
features: [
|
||||
"All 47 image processing tools",
|
||||
"All 48 image processing tools",
|
||||
"Unlimited usage, no hidden caps",
|
||||
"Full REST API with OpenAPI docs",
|
||||
"Pipeline automation",
|
||||
"Batch processing (unlimited files)",
|
||||
"14 local AI models included",
|
||||
"15 local AI models included",
|
||||
"Self-host on any infrastructure",
|
||||
"Docker, Kubernetes, bare metal",
|
||||
"ARM and x86 support",
|
||||
|
||||
@@ -11,8 +11,8 @@ const phrases = [
|
||||
"No limits. No hidden caps.",
|
||||
"Works fully offline.",
|
||||
"Unlimited batch processing.",
|
||||
"47 image tools.",
|
||||
"14 AI models. Your hardware.",
|
||||
"48 image tools.",
|
||||
"15 AI models. Your hardware.",
|
||||
"Lightning fast. Built on Sharp.",
|
||||
"Air-gapped ready.",
|
||||
"One Docker container.",
|
||||
|
||||
@@ -2535,7 +2535,7 @@ function AboutSection() {
|
||||
</div>
|
||||
</div>
|
||||
<p className="text-sm text-muted-foreground">
|
||||
A self-hosted, privacy-first image processing suite with 47 tools. Resize, compress,
|
||||
A self-hosted, privacy-first image processing suite with 48 tools. Resize, compress,
|
||||
convert, watermark, and automate your image workflows without sending data to the cloud.
|
||||
</p>
|
||||
<div className="flex items-center gap-4 text-sm">
|
||||
|
||||
Reference in New Issue
Block a user