mirror of https://github.com/snapotter-hq/SnapOtter.git synced 2026-08-03 07:46:42 +02:00

Files

T

SnapOtter 8532f3227b docs: audit all 157 tool pages against live schemas

Reconcile every tool page's parameters, defaults, and response shape against the tool's Zod settings schema and executionHint in code. Notable fixes: color-palette (add count + format params, hex output, median-cut algorithm), favicon (add 5 params, was documented as having none), qr-generate (add logoDataUri), convert (add ppm/eps/tga formats), video-loudnorm (-16 LUFS not -14), smart-crop (async 202 not sync 200), images-to-video (1080x1080 square), and several output-filename and behavior-note corrections.

Also normalize API endpoint paths to /api/v1/tools/<id> (no modality segment) and standardize curl examples on the Docker API port 1349. Verified with a clean docs build.

2026-06-18 14:12:28 +08:00

3.0 KiB

Raw Blame History

description

description
Capture webpages or HTML snippets as high-quality images with device emulation.

HTML to Image

Capture a webpage URL or raw HTML content as a screenshot image. Supports device emulation (desktop, tablet, mobile), full-page capture, and multiple output formats.

API Endpoint

POST /api/v1/tools/html-to-image

Accepts a JSON body (not multipart). No file upload is needed.

Parameters

Parameter	Type	Required	Default	Description
url	string	Conditional	-	URL to capture (must be a valid URL)
html	string	Conditional	-	Raw HTML content to render (1 to 5,000,000 characters)
format	string	No	`"png"`	Output format: `jpg`, `png`, `webp`
quality	number	No	`90`	Output quality for lossy formats (1 to 100)
fullPage	boolean	No	`false`	Capture the full scrollable page, not just the viewport
devicePreset	string	No	`"desktop"`	Device emulation: `desktop`, `tablet`, `mobile`, `custom`
viewportWidth	number	No	`1280`	Custom viewport width in pixels (320 to 3840, used when devicePreset is `custom`)
viewportHeight	number	No	`720`	Custom viewport height in pixels (320 to 2160, used when devicePreset is `custom`)

Either url or html must be provided, but not both.

Device Presets

Preset	Width	Height	Mobile UA
`desktop`	1280	720	No
`tablet`	768	1024	No
`mobile`	375	812	Yes
`custom`	(user-specified)	(user-specified)	No

Example Request

Capture a webpage:

curl -X POST http://localhost:1349/api/v1/tools/html-to-image \
  -H "Authorization: Bearer si_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "format": "png", "fullPage": true, "devicePreset": "desktop"}'

Render HTML content:

curl -X POST http://localhost:1349/api/v1/tools/html-to-image \
  -H "Authorization: Bearer si_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"html": "<div style=\"padding: 20px; background: #f0f0f0;\"><h1>Hello</h1></div>", "format": "png"}'

Example Response

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/screenshot.png",
  "originalSize": 0,
  "processedSize": 145000
}

Notes

Requires Chromium to be installed on the server. Returns HTTP 503 if the browser service is not available.
URLs are validated against SSRF attacks (private/internal network addresses are blocked).
This endpoint is rate-limited to 120 requests per hour.
originalSize is always 0 since this tool generates images from URLs/HTML.
The output filename is screenshot.<format>.
If the page takes too long to load, the request returns HTTP 504 (gateway timeout).
If the browser service crashes repeatedly, it is temporarily disabled and returns HTTP 503 with code BROWSER_CRASHED.

3.0 KiB Raw Blame History