Eastsea HTML to Image Converter: Batch Conversion & Custom Options

Eastsea HTML to Image Converter — CLI, API, and Web Interface Guide### Overview

Eastsea HTML to Image Converter is a versatile tool that converts HTML content into raster images (PNG, JPEG, WebP) and vector formats (SVG) for use in previews, thumbnails, documentation, testing, or visual regression. It supports multiple usage modes: a command-line interface (CLI) for automation, an HTTP API for integration into web services, and a web interface for interactive use. This guide explains features, installation, configuration, common workflows, performance considerations, and troubleshooting.

Key features

Multiple output formats: PNG, JPEG, WebP, and SVG.
Headless browser rendering: Accurate rendering using Chromium-based engines for modern CSS and JavaScript.
CLI, API, and web UI: Flexible integration options for developers and non-technical users.
Custom viewport and device emulation: Set viewport size, device pixel ratio, user agent, and emulate mobile devices.
Full-page and clip capture: Capture entire pages, specific DOM elements, or custom clipping rectangles.
Batch conversion: Process multiple HTML files or URLs in parallel.
Templates and custom CSS injection: Apply styles or scripts before capture.
Authentication and cookies: Support for basic auth, bearer tokens, and cookies for authenticated pages.
Scheduling and caching: Schedule rendering jobs and cache outputs to reduce repeated work.
Quality, compression, and optimization options: Control image quality, background transparency, and file size.

Installation and setup

Requirements

A modern Linux, macOS, or Windows environment.
Node.js (if Eastsea is distributed as an npm package) or a Docker runtime (if provided as an image).
Optional: Chromium/Chrome binary if not bundled.

Install via npm (example)

npm install -g eastsea-html-to-image

Run with Docker (example)

docker run --rm -p 8080:8080 eastsea/eastsea-html-to-image:latest

Command-Line Interface (CLI)

Basic usage

Convert a URL or HTML file to PNG:

eastsea convert --input "https://example.com" --output ./screenshot.png

Convert a local HTML file:

eastsea convert --input ./index.html --output ./index.png

Common CLI options

–input, -i: URL or local HTML file path.
–output, -o: Output file path.
–format, -f: Output format (png, jpeg, webp, svg).
–width, –height: Viewport dimensions.
–full-page: Capture the full scrollable page.
–selector: Capture a specific DOM element by CSS selector.
–quality: JPEG/WebP quality (0–100).
–background: Background color (e.g., #ffffff) or transparent.
–wait-for: Wait for a selector or timeout before capturing (e.g., “#loaded” or “5000ms”).
–cookies: Path to a cookies JSON file.
–auth: Basic auth credentials user:pass.
–user-agent: Custom user agent string.
–device-scale-factor: Device pixel ratio.

Examples

Capture an element:

eastsea convert -i https://example.com -o element.png -f png --selector ".hero" --width 1200

Batch convert files:

eastsea batch --input-list urls.txt --output-dir ./screenshots --parallel 5

HTTP API

Starting the server

eastsea serve --port 8080

API endpoints (examples)

POST /render — Convert HTML/URL to an image.

Request JSON:


{ "input": "https://example.com", "format": "png", "width": 1280, "height": 720, "fullPage": false, "selector": null, "waitFor": "5000ms" }

Response:
- 200: Binary image stream with appropriate Content-Type.
- ⁄₅₀₀: JSON error.

POST /render/html — Send raw HTML in the request body (multipart or JSON).
GET /health — Health check endpoint.
GET /metrics — Prometheus-style metrics (requests, failures, average render time).

Authentication and rate limiting

API supports API keys via headers: X-API-Key: .
Rate limiting configurable via server options or reverse proxy.

Example with curl

Render a URL to PNG:

curl -X POST "http://localhost:8080/render"    -H "Content-Type: application/json"    -H "X-API-Key: your_api_key"    -d '{"input":"https://example.com","format":"png","width":1280,"height":720}'    --output example.png

Web Interface

The web UI provides:

A URL/HTML input field.
Preview pane with live rendering.
Controls for viewport size, format, background, and quality.
Advanced settings: custom CSS/JS injection, authentication, cookies.
Download button and shareable permalinks for rendered images.

Use it for quick previews, manual tweaking, or non-developers who need screenshots.

Workflows and examples

Generating thumbnails for link previews

Use CLI or API to render pages at small viewport (e.g., 600×315) with device pixel ratio 2 for high-density displays.
Apply custom CSS to hide overlays and cookie banners before capture.

Visual regression testing

Automate periodic captures with the CLI or API.
Compare produced images to baselines using pixel diff tools (e.g., pixelmatch).
Store images in object storage and record job metadata (URL, timestamp, viewport).

Generating documentation screenshots

Use selector capture to produce consistent component screenshots.
Inject custom CSS to remove unrelated elements and set background.

On-demand rendering in web apps

Accept HTML snippets via API endpoint and return base64-encoded images for inline display.
Cache popular renders and invalidate on content update.

Performance and scaling

Single-instance performance

Typical render time depends on page complexity; simple pages often render in 200–600ms, complex apps may take multiple seconds.
Keep a pool of Chromium instances to reduce startup overhead.
Use request queuing and concurrency limits to avoid CPU/memory spikes.

Horizontal scaling

Run multiple containers behind a load balancer.
Use shared cache (Redis or S3) to store rendered outputs and job metadata.
Autoscale based on queue length or CPU utilization.

Security considerations

Sanitize input when rendering raw HTML to avoid server-side XSS and injection attacks.
Run headless browser processes in sandboxed containers with resource limits (CPU, memory, timeout).
Restrict network access for renderer to prevent SSRF — allow only required domains or use a proxy.
Rotate API keys and enforce HTTPS.

Troubleshooting

Blank images: Check waitFor settings; the page may need time to render dynamic content. Use –wait-for selector or longer timeout.
Wrong layout: Verify viewport, device-scale-factor, and user-agent. Ensure external resources are accessible.
High memory use: Lower concurrency and use a smaller Chromium instance or increase swap cautiously.
Authentication failures: Provide cookies or Authorization headers; verify same-origin requirements.

Best practices

Use consistent viewports and device pixel ratios for reproducible images.
Cache outputs and implement cache headers for static pages.
Provide a health check and metrics for observability.
Test with representative pages (heavy JS, third-party ads) to tune timeouts and resource limits.
Offer a “preflight” lightweight HTML-only render option for very fast thumbnails when JS rendering isn’t required.

Conclusion

Eastsea HTML to Image Converter combines the flexibility of a CLI, the integration power of an API, and the convenience of a web UI to handle a wide range of screenshot and rendering needs. Carefully configure rendering options, security, and scaling to match your use case — from single-shot documentation screenshots to large-scale automated thumbnail generation.