From 466ef1efb14032b486658fe35fa3443cc892b98a Mon Sep 17 00:00:00 2001 From: SnapOtter Date: Fri, 8 May 2026 16:31:43 +0800 Subject: [PATCH] docs(beautify): add API docs, OpenAPI spec, LLM docs, update README Add beautify tool endpoint to OpenAPI spec with full parameter documentation. Add tool to REST API docs Layout & Composition table. Update tool count from 49 to 50 across README, docs homepage, architecture docs, VitePress config, OpenAPI spec, and LLM docs generator. --- README.md | 2 +- apps/api/src/openapi.yaml | 73 ++++++++++++++++++++++++++++++++- apps/api/src/routes/docs.ts | 2 +- apps/docs/.vitepress/config.mts | 4 +- apps/docs/api/rest.md | 1 + apps/docs/guide/architecture.md | 2 +- apps/docs/index.md | 4 +- 7 files changed, 80 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 88605445..de0b3e09 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ ## Key Features -- **49 image tools** - Resize, crop, compress, convert, watermark, color adjust, vectorize, create GIFs, find duplicates, generate passport photos, and more +- **50 image tools** - Resize, crop, compress, convert, watermark, color adjust, beautify screenshots, vectorize, create GIFs, find duplicates, generate passport photos, and more - **Local AI** - Remove backgrounds, upscale images, restore and colorize old photos, erase objects, blur faces, enhance faces, extract text (OCR). All on your hardware - no internet required - **Pipelines** - Chain tools into reusable workflows with unlimited steps. Batch process unlimited images at once - **REST API** - Every tool available via API with API key auth. Interactive docs at `/api/docs` diff --git a/apps/api/src/openapi.yaml b/apps/api/src/openapi.yaml index 6d2f0cca..bd856bdc 100644 --- a/apps/api/src/openapi.yaml +++ b/apps/api/src/openapi.yaml @@ -3,7 +3,7 @@ info: title: SnapOtter API version: 1.15.9 description: | - REST API for SnapOtter, a self-hosted image processing platform with 48 tools. + REST API for SnapOtter, a self-hosted image processing platform with 50 tools. ## Authentication @@ -610,6 +610,77 @@ paths: schema: $ref: "#/components/schemas/UnauthorizedError" + /api/v1/tools/beautify: + post: + tags: [Tools] + summary: Beautify screenshot + description: | + Add gradient backgrounds, device frames, shadows, watermarks, and social + media sizing to screenshots. Supports solid, linear-gradient, radial-gradient, + image, and transparent backgrounds. Includes macOS, Windows, browser, iPhone, + MacBook, and iPad device frames. Social media presets for Twitter, LinkedIn, + Instagram, Facebook, and Product Hunt. + security: + - bearerAuth: [] + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + required: [file] + properties: + file: + type: string + format: binary + description: Screenshot or image file to beautify + backgroundImage: + type: string + format: binary + description: Optional image for image backgrounds (used when backgroundType is "image") + settings: + type: string + description: | + JSON string with options: + - `backgroundType` (string, default "linear-gradient") -- One of: solid, linear-gradient, radial-gradient, image, transparent + - `backgroundColor` (hex string, default "#667eea") -- Background color (for solid backgrounds) + - `gradientStops` (array, default [{color:"#667eea",position:0},{color:"#764ba2",position:100}]) -- Array of {color, position} objects for gradient backgrounds + - `gradientAngle` (number 0-360, default 135) -- Gradient angle in degrees + - `padding` (number 0-256, default 64) -- Space between screenshot and canvas edge in pixels + - `borderRadius` (number 0-64, default 12) -- Corner rounding radius for the screenshot + - `shadowPreset` (string, default "subtle") -- One of: none, subtle, medium, dramatic, custom + - `shadowBlur` (number 0-100, default 20) -- Shadow blur radius (used with custom shadow preset) + - `shadowOffsetX` (number -50 to 50, default 0) -- Shadow horizontal offset + - `shadowOffsetY` (number -50 to 50, default 10) -- Shadow vertical offset + - `shadowColor` (hex string, default "#000000") -- Shadow color + - `shadowOpacity` (number 0-100, default 30) -- Shadow opacity percentage + - `frame` (string, default "none") -- One of: none, macos-light, macos-dark, windows-light, windows-dark, browser-light, browser-dark, iphone, iphone-dark, macbook, macbook-dark, ipad, ipad-dark + - `frameTitle` (string, optional) -- Title text shown in window title bars + - `socialPreset` (string, default "none") -- One of: none, twitter, linkedin, instagram-square, instagram-story, facebook, producthunt + - `watermarkText` (string, optional) -- Watermark text to overlay + - `watermarkPosition` (string, default "bottom-right") -- One of: top-left, top-right, bottom-left, bottom-right, center + - `watermarkOpacity` (number 0-100, default 50) -- Watermark opacity percentage + - `outputFormat` (string, default "png") -- One of: png, jpeg, webp + responses: + "200": + description: Beautified image + content: + application/json: + schema: + $ref: "#/components/schemas/ToolResponse" + "400": + description: Invalid input + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + "401": + description: Authentication required + content: + application/json: + schema: + $ref: "#/components/schemas/UnauthorizedError" + /api/v1/tools/adjust-colors: post: tags: [Tools] diff --git a/apps/api/src/routes/docs.ts b/apps/api/src/routes/docs.ts index 136535a2..5737fa81 100644 --- a/apps/api/src/routes/docs.ts +++ b/apps/api/src/routes/docs.ts @@ -39,7 +39,7 @@ function generateLlmsTxt(spec: OpenAPISpec): string { lines.push(`# ${spec.info.title}`); lines.push(""); lines.push( - "> Self-hosted image processing API with 48 tools. Resize, compress, convert, remove backgrounds, upscale, run OCR, and more.", + "> Self-hosted image processing API with 50 tools. Resize, compress, convert, remove backgrounds, upscale, run OCR, and more.", ); lines.push(""); lines.push("## Docs"); diff --git a/apps/docs/.vitepress/config.mts b/apps/docs/.vitepress/config.mts index 0f31aa8b..a5296f0a 100644 --- a/apps/docs/.vitepress/config.mts +++ b/apps/docs/.vitepress/config.mts @@ -4,7 +4,7 @@ import llmstxt from "vitepress-plugin-llms"; export default defineConfig({ title: "SnapOtter", description: - "Documentation for SnapOtter - A Self Hosted Image Manipulator. 49 tools, local AI, pipelines, REST API.", + "Documentation for SnapOtter - A Self Hosted Image Manipulator. 50 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 49 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 50 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.", }, diff --git a/apps/docs/api/rest.md b/apps/docs/api/rest.md index 01268de4..3fa40cbe 100644 --- a/apps/docs/api/rest.md +++ b/apps/docs/api/rest.md @@ -184,6 +184,7 @@ All AI tools run on your hardware (CPU or NVIDIA GPU). No internet required. | `stitch` | Stitch / Combine | `direction` (horizontal/vertical/grid), `gap`, `backgroundColor`, `alignment` - multi-file | | `split` | Image Splitting | `mode` (grid/rows/cols), `rows`, `cols`, `tileWidth`, `tileHeight` | | `border` | Border & Frame | `width`, `color`, `style` (solid/gradient/pattern), `borderRadius`, `padding`, `shadow` | +| `beautify` | Beautify Screenshot | `backgroundType` (solid/linear-gradient/radial-gradient/image/transparent), `gradientStops`, `padding`, `borderRadius`, `shadowPreset`, `frame` (none/macos-light/macos-dark/windows-light/windows-dark/browser-light/browser-dark/iphone/macbook/ipad/...), `socialPreset` (none/twitter/linkedin/instagram-square/instagram-story/facebook/producthunt), `watermarkText`, `outputFormat` | ### Format & Conversion diff --git a/apps/docs/guide/architecture.md b/apps/docs/guide/architecture.md index f3f4ce32..cd6638d3 100644 --- a/apps/docs/guide/architecture.md +++ b/apps/docs/guide/architecture.md @@ -43,7 +43,7 @@ Shared TypeScript types, constants (like `APP_VERSION` and tool definitions), an ### API (`apps/api`) -A Fastify v5 server exposing 49 tool routes (33 standard image operations + 15 AI-powered) that handles: +A Fastify v5 server exposing 50 tool routes (34 standard image operations + 15 AI-powered + editor) 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) diff --git a/apps/docs/index.md b/apps/docs/index.md index 6959051b..ce47457e 100644 --- a/apps/docs/index.md +++ b/apps/docs/index.md @@ -4,7 +4,7 @@ layout: home hero: name: "SnapOtter" text: "A Self Hosted Image Manipulator" - tagline: 49 tools. Local AI. No cloud. Your images never leave your home. + tagline: 50 tools. Local AI. No cloud. Your images never leave your home. actions: - theme: brand text: Get started @@ -14,7 +14,7 @@ hero: link: /api/rest features: - - title: 49 Image Tools + - title: 50 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: 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.