flashshot-sdk

The official JavaScript & TypeScript SDK for the FlashShot Screenshot API.

Website · Documentation · Dashboard · npm

---

What is FlashShot?

FlashShot is a high-performance screenshot API that captures pixel-perfect images of any web page. It supports full-page captures, device emulation, custom viewports, ad blocking, stealth mode, AI-powered image analysis, and more. This SDK provides a simple, fully-typed client for Node.js and edge runtimes.

Installation

# npm
npm install flashshot-sdk

# yarn
yarn add flashshot-sdk

# pnpm
pnpm add flashshot-sdk

Requires Node.js 20 or later.

Quick Start

import { FlashShot } from 'flashshot-sdk';

const flashshot = new FlashShot('fs_your_api_key');

const result = await flashshot.screenshot('https://example.com');
console.log(result.data.image_url);

Configuration

Pass a string to use just an API key with defaults, or pass a config object for full control.

const flashshot = new FlashShot({
  apiKey: 'fs_your_api_key',
  baseUrl: 'https://api.flashshot.dev', // default
  maxRetries: 2,                        // default, retries on 5xx / network errors
  timeout: 60_000,                      // default, request timeout in ms
});

Option	Type	Default	Description
apiKey	string	required	Your FlashShot API key
baseUrl	string	https://api.flashshot.dev	API base URL
maxRetries	number	2	Maximum retry attempts for 5xx and network errors
timeout	number	60000	Request timeout in milliseconds

Methods

screenshot(url, options?)

Capture a screenshot of a single URL.

const result = await flashshot.screenshot('https://example.com', {
  format: 'webp',
  full_page: true,
  width: 1440,
  quality: 90,
});

console.log(result.data.image_url);      // hosted image URL
console.log(result.data.render_time_ms); // time to capture
console.log(result.usage.credits_used);  // credits consumed

Response shape:

{
  success: boolean;
  data: {
    image_url: string;
    overview: string;
    description: string;
    render_time_ms: number;
    format: 'png' | 'jpeg' | 'webp';
    width: number;
    height: number;
    file_size: number;
  };
  usage: {
    credits_used: number;
    credits_remaining: number;
  };
}

batch(urls, options?)

Capture screenshots of multiple URLs in a single request. All URLs share the same options.

const result = await flashshot.batch(
  [
    'https://example.com',
    'https://example.com/pricing',
    'https://example.com/about',
  ],
  { format: 'png', width: 1280 },
);

for (const screenshot of result.data) {
  console.log(screenshot.image_url);
}

balance()

Check your current plan, quota, and remaining credits.

const balance = await flashshot.balance();

console.log(balance.plan);          // e.g. "pro"
console.log(balance.usage.used);    // credits used this period
console.log(balance.usage.quota);   // total credits available
console.log(balance.usage.period);  // billing period

usage(limit?)

Retrieve recent usage history. Defaults to 10 entries.

const history = await flashshot.usage(25);

for (const entry of history.data) {
  console.log(entry.timestamp, entry.endpoint, entry.credits, entry.url);
}

Screenshot Options

Every option below can be passed to screenshot() or batch().

Option	Type	Default	Description
format	'png' | 'jpeg' | 'webp'	'png'	Output image format
full_page	boolean	false	Capture the full scrollable page
width	number	—	Viewport width in pixels
height	number	—	Viewport height in pixels
device_scale_factor	number	—	Device pixel ratio (1–3)
device	DevicePreset	—	Emulate a device preset (see below)
quality	number	—	Image quality for jpeg/webp (1–100)
wait_for	string | number	—	CSS selector or time in ms to wait before capture
include_analysis	boolean	false	Include AI-powered analysis of the screenshot
cookies	Cookie[]	—	Cookies to set before navigation
headers	Record<string, string>	—	Custom HTTP headers sent with the request
basic_auth	{ username, password }	—	HTTP Basic Authentication credentials
custom_css	string	—	CSS to inject into the page
custom_js	string	—	JavaScript to execute before capture
block_cookies	boolean	false	Block all cookies on the page
block_ads	boolean	false	Block ads and trackers
cache_ttl	number	—	Cache time-to-live in seconds
stealth	boolean	false	Use stealth mode to avoid bot detection
webhook_url	string	—	URL to receive results via webhook callback

Cookie Object

{
  name: string;
  value: string;
  domain?: string;
  path?: string;
  secure?: boolean;
  httpOnly?: boolean;
  sameSite?: 'Strict' | 'Lax' | 'None';
  expires?: number;
}

Error Handling

All API errors throw a FlashShotError with structured fields for easy programmatic handling.

import { FlashShot, FlashShotError } from 'flashshot-sdk';

const flashshot = new FlashShot('fs_your_api_key');

try {
  const result = await flashshot.screenshot('https://example.com');
} catch (error) {
  if (error instanceof FlashShotError) {
    console.error(error.message); // human-readable message
    console.error(error.code);    // e.g. "rate_limit_exceeded", "missing_api_key"
    console.error(error.status);  // HTTP status code (0 for network errors)
  }
}

Property	Type	Description
message	string	Human-readable error description
code	string	Machine-readable error code
status	number	HTTP status code, or 0 for network/timeout errors

Auto-Retry

The SDK automatically retries failed requests with exponential backoff and jitter:

• 429 Too Many Requests — Waits for the duration specified by the Retry-After header, then retries.
• 5xx Server Errors — Retries up to maxRetries times (default: 2) with exponential backoff.
• Network / Timeout Errors — Retries up to maxRetries times with the same backoff strategy.

Client errors (4xx other than 429) are thrown immediately and are never retried. Set maxRetries: 0 to disable retries entirely.

TypeScript

The SDK is written in TypeScript and ships with complete type definitions. All responses are fully typed out of the box.

import { FlashShot } from 'flashshot-sdk';
import type {
  ScreenshotOptions,
  ScreenshotResponse,
  ScreenshotData,
  BatchScreenshotResponse,
  BalanceResponse,
  UsageHistoryResponse,
  Cookie,
  BasicAuth,
  ImageFormat,
  DevicePreset,
} from 'flashshot-sdk';

const flashshot = new FlashShot('fs_your_api_key');

const options: ScreenshotOptions = {
  format: 'webp',
  full_page: true,
  width: 1440,
};

const result: ScreenshotResponse = await flashshot.screenshot(
  'https://example.com',
  options,
);

const data: ScreenshotData = result.data;
console.log(data.image_url, data.width, data.height, data.file_size);

Device Presets

Use the device option to emulate a specific device viewport and user agent.

Preset	Description
desktop	Standard desktop viewport
mobile	Generic mobile viewport
tablet	Generic tablet viewport
iphone-14	iPhone 14
iphone-14-pro	iPhone 14 Pro
pixel-7	Google Pixel 7
ipad	iPad
ipad-pro	iPad Pro

const result = await flashshot.screenshot('https://example.com', {
  device: 'iphone-14-pro',
});

Examples

Screenshot with AI Analysis

Receive an AI-generated overview and description alongside the captured image.

const result = await flashshot.screenshot('https://example.com', {
  include_analysis: true,
});

console.log(result.data.image_url);
console.log(result.data.overview);     // short AI-generated summary
console.log(result.data.description);  // detailed AI description

Mobile Device Screenshot

const result = await flashshot.screenshot('https://example.com', {
  device: 'iphone-14',
  format: 'webp',
  quality: 85,
});

Screenshot with Stealth Mode

Bypass bot detection for pages that block headless browsers.

const result = await flashshot.screenshot('https://protected-site.com', {
  stealth: true,
  wait_for: 3000,
});

HTML to Image

Render raw HTML by passing a data URL.

const html = `
  <div style="padding: 40px; font-family: sans-serif;">
    <h1>Hello, FlashShot!</h1>
    <p>Rendered from raw HTML.</p>
  </div>
`;

const result = await flashshot.screenshot(
  `data:text/html,${encodeURIComponent(html)}`,
  { width: 800, height: 600 },
);

Webhook Callback

Receive results asynchronously via a webhook instead of waiting for the response.

await flashshot.screenshot('https://example.com', {
  webhook_url: 'https://your-server.com/api/webhook/screenshot',
  full_page: true,
});

Disable Ads and Cookie Blocking

Block ads, trackers, and cookies for a clean capture.

const result = await flashshot.screenshot('https://news-site.com', {
  block_ads: true,
  block_cookies: true,
  full_page: true,
});

Authenticated Page with Custom Headers

const result = await flashshot.screenshot('https://internal-app.com/dashboard', {
  basic_auth: { username: 'admin', password: 'secret' },
  headers: { 'X-Custom-Header': 'value' },
  cookies: [
    { name: 'session', value: 'abc123', domain: 'internal-app.com' },
  ],
});

Custom CSS and JavaScript Injection

const result = await flashshot.screenshot('https://example.com', {
  custom_css: 'body { background: #1a1a2e; color: #eee; }',
  custom_js: 'document.querySelector(".banner")?.remove();',
  wait_for: '.main-content',
});

License

MIT

---

Website · Documentation · Dashboard · npm