lensh

Official Node.js SDK for len.sh — Screenshot, OG Image & PDF generation API.

Installation

npm install lensh

Quick Start

import LenSh from "lensh";

const lensh = new LenSh("sk_live_your_api_key");

// Take a screenshot
const screenshot = await lensh.screenshot("https://example.com");
// screenshot.data is an ArrayBuffer — write it to a file:
import { writeFile } from "node:fs/promises";
await writeFile("screenshot.png", Buffer.from(screenshot.data));

// Generate a PDF
const pdf = await lensh.pdf("https://example.com");
await writeFile("page.pdf", Buffer.from(pdf.data));

// Generate an OG image
const og = await lensh.ogImage({
  title: "Hello World",
  subtitle: "Generated with len.sh",
  theme: "dark",
});
await writeFile("og.png", Buffer.from(og.data));

API Reference

Constructor

const lensh = new LenSh(apiKey: string, options?: {
  baseUrl?: string; // default: "https://api.len.sh"
});

screenshot(url, options?)

Take a screenshot of a URL.

const result = await lensh.screenshot("https://example.com", {
  width: 1920,
  height: 1080,
  format: "webp",
  quality: 90,
  full_page: true,
  block_ads: true,
  block_cookie_banners: true,
  delay: 1000,
});

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | width | number | 1280 | Viewport width (1-3840) | | height | number | 720 | Viewport height (1-2160) | | device | string | — | Device preset (e.g. "iphone-14") | | device_scale | number | 1 | Device pixel ratio (1-3) | | format | "png" \| "jpeg" \| "webp" | "png" | Image format | | quality | number | 80 | Image quality (1-100) | | full_page | boolean | false | Capture full scrollable page | | wait_until | string | "load" | "load", "domcontentloaded", "networkidle0", "networkidle2" | | timeout | number | 15000 | Render timeout in ms (1-30000) | | delay | number | 0 | Delay after load in ms (0-10000) | | selector | string | — | CSS selector to capture | | transparent | boolean | false | Transparent background | | block_ads | boolean | false | Block ad requests | | block_cookie_banners | boolean | false | Block cookie banners | | block_popups | boolean | false | Block popups | | js | string | — | Inject custom JavaScript | | css | string | — | Inject custom CSS | | user_agent | string | — | Custom user agent | | cache_ttl | number | 86400 | Cache TTL in seconds (0 = disable) | | response_type | "image" \| "json" | "image" | Return binary or JSON metadata |

Returns ScreenshotImageResult (or ScreenshotJsonResult when response_type: "json"):

// Image result
{ data: ArrayBuffer, contentType: string, cache: "HIT" | "MISS", renderTime: number, requestId: string }

// JSON result
{ url: string, width: number, height: number, format: string, size: number, cache: string, render_time_ms: number, request_id: string }

screenshotHtml(html, options?)

Take a screenshot of raw HTML content.

const result = await lensh.screenshotHtml("<h1>Hello World</h1>", {
  width: 800,
  height: 600,
});

ogImage(options)

Generate an Open Graph image.

const result = await lensh.ogImage({
  title: "My Blog Post",
  subtitle: "A deep dive into Node.js SDKs",
  badge: "NEW",
  url: "https://myblog.com/post",
  brand_name: "My Blog",
  brand_color: "#ff6600",
  theme: "light",
  format: "png",
  quality: 90,
});

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | title | string | required | Main title (1-200 chars) | | subtitle | string | — | Subtitle (1-300 chars) | | badge | string | — | Badge text (1-50 chars) | | url | string | — | Display URL on image | | brand_name | string | — | Brand name (1-100 chars) | | brand_color | string | "#4850e5" | Brand color (hex) | | theme | "dark" \| "light" | "dark" | Color theme | | format | "png" \| "jpeg" \| "webp" | "png" | Image format | | quality | number | 90 | Image quality (1-100) | | cache_ttl | number | 86400 | Cache TTL in seconds |

pdf(url, options?)

Generate a PDF from a URL.

const result = await lensh.pdf("https://example.com", {
  paper_size: "Letter",
  landscape: true,
  print_background: true,
  margin_top: "1in",
  margin_bottom: "1in",
});

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | paper_size | string | "A4" | "A4", "Letter", "Legal", "Tabloid", "Ledger" | | landscape | boolean | false | Landscape orientation | | scale | number | 1.0 | Scale factor (0.1-2.0) | | margin_top | string | "0.4in" | Top margin (CSS value) | | margin_right | string | "0.4in" | Right margin | | margin_bottom | string | "0.4in" | Bottom margin | | margin_left | string | "0.4in" | Left margin | | print_background | boolean | true | Include backgrounds | | page_ranges | string | — | Pages to include (e.g. "1-3") | | header_template | string | — | HTML header template | | footer_template | string | — | HTML footer template | | wait_until | string | "load" | Wait strategy | | timeout | number | 15000 | Render timeout in ms | | delay | number | 0 | Delay after load in ms | | block_ads | boolean | false | Block ad requests | | block_cookie_banners | boolean | false | Block cookie banners | | js | string | — | Inject custom JavaScript | | css | string | — | Inject custom CSS | | cache_ttl | number | 86400 | Cache TTL in seconds | | response_type | "pdf" \| "json" | "pdf" | Return binary or JSON metadata |

pdfFromHtml(html, options?)

Generate a PDF from raw HTML content.

const result = await lensh.pdfFromHtml("<h1>Invoice #123</h1><p>Total: $99</p>", {
  paper_size: "A4",
  margin_top: "1in",
});

Error Handling

import LenSh, { LenShApiError } from "lensh";

try {
  await lensh.screenshot("https://example.com");
} catch (err) {
  if (err instanceof LenShApiError) {
    console.error(err.code);       // "RATE_LIMITED", "QUOTA_EXCEEDED", etc.
    console.error(err.statusCode);  // 429
    console.error(err.message);     // Human-readable message
    console.error(err.requestId);   // Request ID for support
  }
}

Error codes: MISSING_URL, INVALID_URL, INVALID_PARAMETER, UNAUTHORIZED, RATE_LIMITED, QUOTA_EXCEEDED, RENDER_FAILED, RENDER_TIMEOUT, INTERNAL_ERROR

Requirements

• Node.js 18+ (uses native fetch)
• No external dependencies

Links

• len.sh — API docs & dashboard
• GitHub — Source code & issues

License

MIT