Concepts

This page explains the key concepts behind RendShot. You don't need to read all of this to use the API, but it helps when you hit edge cases or want to optimize.

How Rendering Works

When you send HTML to RendShot, here's what happens:

1. Validate — The API validates your request (auth, rate limits, HTML content, dimensions)
2. Render — Your HTML is loaded into a headless Chromium browser tab, with any custom CSS and Google Fonts applied
3. Capture — The browser takes a screenshot of the rendered page at your specified dimensions
4. Upload — The resulting image is uploaded to a global CDN (Cloudflare R2)
5. Respond — You receive an image ID and a CDN URL

The entire process typically takes 1–3 seconds depending on complexity. Fonts and external resources add latency.

For URL screenshots, step 2 navigates to your URL instead of loading HTML content. The browser waits for the page to finish loading before capturing.

Image Lifecycle

Every image goes through this lifecycle:

Retention depends on your plan:

After expiration, the image URL returns a 410 Gone error. The API returns IMAGE_EXPIRED if you try to fetch metadata for a deleted image.

Tip: If you need images to persist longer than your plan allows, download them immediately after rendering (--save flag in CLI, or fetch the URL in your code).

Authentication

RendShot uses API keys for all rendering operations. Keys start with rs_live_ and are created in your Dashboard.

How keys work:

• You create a key in the dashboard — this is the only time you see the full key
• The key is hashed (SHA-256) before storage — we never store your raw key
• Every API request must include the key in the Authorization: Bearer header
• If a key is compromised, delete it and create a new one

Two auth systems:

• API keys (rs_live_...) — For rendering and usage endpoints. This is what you use in code.
• JWT tokens — For the dashboard and key management. You get these by logging in at rendshot.ai.

Rate Limits

Every plan has two limits:

When you hit a rate limit, the API returns 429 Too Many Requests with a RATE_LIMIT_EXCEEDED or QUOTA_EXCEEDED error code. The response includes a Retry-After header indicating when you can try again.

Best practices:

• Add retry logic with exponential backoff in your code
• Use the Usage endpoint to monitor your consumption
• If you consistently hit limits, consider upgrading your plan

Dimensions & Device Scale

Dimensions set the viewport size in CSS pixels:

• Minimum: 1 × 1
• Maximum: 4096 × 4096
• Default: 1080 × 1080 (for render), 1280 × 800 (for screenshot)

Device Scale (also called device pixel ratio or DPR) controls the actual pixel density:

• 1 — Standard resolution (1 CSS pixel = 1 image pixel)
• 2 — Retina / 2× (1 CSS pixel = 4 image pixels). An 800×400 viewport produces a 1600×800 image.
• 3 — Ultra-high (1 CSS pixel = 9 image pixels). An 800×400 viewport produces a 2400×1200 image.

When to use 2× or 3×: Whenever the image will be displayed on high-DPI screens (phones, modern laptops, Retina displays). The image will look sharp instead of blurry.

Watch your pixel budget: Width × height × deviceScale² must not exceed 16,777,216 pixels (4096 × 4096). A 4096×4096 image at 2× would be 8192×8192 actual pixels — that exceeds the budget and returns PIXEL_BUDGET_EXCEEDED.

Fonts

RendShot loads Google Fonts automatically. Pass the font family names in the fonts parameter:

await client.renderImage({
  html: '<p style="font-family: Noto Sans SC">你好世界</p>',
  fonts: ['Noto Sans SC'],
  width: 400,
  height: 200,
})

Chinese, Japanese, Korean (CJK) fonts: Use Noto Sans SC (Simplified Chinese), Noto Sans TC (Traditional Chinese), Noto Sans JP (Japanese), or Noto Sans KR (Korean).

Custom fonts: Not supported yet — only Google Fonts are available. You can embed fonts as base64 data URIs in your CSS as a workaround.

Security

SSRF Protection

When you use the screenshot endpoint, RendShot validates the URL before loading it:

• DNS resolution is checked — if the URL resolves to a private IP (10.x.x.x, 192.168.x.x, 127.0.0.1, etc.), the request is blocked
• Both IPv4 (A records) and IPv6 (AAAA records) are checked
• The error code is SSRF_BLOCKED

This prevents attackers from using RendShot to screenshot internal services, cloud metadata endpoints, or other private resources.

What this means for you: You can only screenshot publicly accessible URLs. If your staging site is behind a VPN, RendShot can't reach it.

Content Limits

• Request body: 1MB maximum
• HTML content: validated for parsability
• URL schemes: only http:// and https:// are allowed

Next Steps

• Quickstart — Try the API yourself
• Use Cases — See practical examples
• API Reference — Full parameter and error code reference