RenderScreenshot

Content Input

RenderScreenshot supports three input methods: URL, raw HTML, and Markdown. Each request must include exactly one input type.

URL Input

The most common method. Fetch and render a live web page.

{
  "url": "https://example.com"
}

URL Requirements

  • Must be a valid HTTP or HTTPS URL
  • Must be publicly accessible (or use network options for authentication)
  • Maximum URL length: 2048 characters

Examples

{ "url": "https://example.com" }
{ "url": "https://example.com/page?param=value" }
{ "url": "https://staging:[email protected]" }

GET Request

GET /v1/screenshot?url=https://example.com

URL must be URL-encoded:

GET /v1/screenshot?url=https%3A%2F%2Fexample.com%2Fpage%3Fparam%3Dvalue

HTML Input

Render raw HTML content. Useful for generating images from templates.

{
  "html": "<html><body><h1>Hello World</h1></body></html>"
}

With Base URL

Set a base URL for relative links and assets:

{
  "html": "<html><body><img src=\"/logo.png\"></body></html>",
  "html_base_url": "https://example.com"
}

The base URL is used for: - Resolving relative URLs (/images/logo.png → https://example.com/images/logo.png) - Loading external stylesheets and scripts - Setting document.baseURI

Parameters

Parameter Type Required Description
html string Yes HTML content to render
html_base_url string No Base URL for relative links

Example: Social Card Template

{
  "html": "<!DOCTYPE html><html><head><style>body{font-family:system-ui;background:linear-gradient(135deg,#667eea,#764ba2);color:white;display:flex;align-items:center;justify-content:center;height:100vh;margin:0}.card{text-align:center;padding:40px}h1{font-size:48px;margin:0}</style></head><body><div class=\"card\"><h1>My Blog Post Title</h1><p>Posted on January 18, 2024</p></div></body></html>",
  "viewport": { "width": 1200, "height": 630 }
}

Example: Invoice Generation

{
  "html": "<!DOCTYPE html><html><head><link rel=\"stylesheet\" href=\"/styles/invoice.css\"></head><body><div class=\"invoice\"><h1>Invoice #12345</h1><table>...</table></div></body></html>",
  "html_base_url": "https://myapp.com",
  "output": { "format": "pdf" },
  "pdf": { "paper": "a4" }
}

Markdown Input

Render Markdown content with optional themes.

{
  "markdown": "# Hello World\n\nThis is **bold** and this is *italic*.",
  "markdown_theme": "github"
}

Parameters

Parameter Type Required Description
markdown string Yes Markdown content
markdown_theme string No Theme: github, dark, light

Available Themes

Theme Description
github GitHub-flavored markdown styling
dark Dark background with light text
light Light background (default)

Example: Documentation Screenshot

{
  "markdown": "# API Reference\n\n## Authentication\n\nAll requests require an API key:\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_KEY\" https://api.example.com\n```\n\n## Endpoints\n\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /users | List users |\n| POST | /users | Create user |",
  "markdown_theme": "github",
  "viewport": { "width": 800, "height": 600 }
}

Example: Dark Theme README

{
  "markdown": "# My Project\n\n> A powerful tool for developers\n\n## Installation\n\n```bash\nnpm install my-project\n```",
  "markdown_theme": "dark"
}

Input Method Comparison

Feature URL HTML Markdown
Live web content ✓ ✗ ✗
Dynamic JavaScript ✓ ✓ ✗
Custom templates ✗ ✓ ✓
External assets ✓ With base URL ✗
Code highlighting ✓ ✓ ✓
Easy formatting ✗ ✗ ✓

Error Handling

Missing Input

{
  "error": {
    "type": "validation_error",
    "code": "missing_required",
    "message": "One of 'url', 'html', or 'markdown' is required",
    "retryable": false
  }
}

Multiple Inputs

{
  "error": {
    "type": "validation_error",
    "code": "invalid_parameter",
    "message": "Only one of 'url', 'html', or 'markdown' can be specified",
    "retryable": false
  }
}

Invalid URL

{
  "error": {
    "type": "validation_error",
    "code": "invalid_url",
    "message": "The URL 'not-a-url' is not a valid HTTP(S) URL",
    "param": "url",
    "retryable": false
  }
}

Examples

URL Screenshot

curl -X POST https://api.renderscreenshot.com/v1/screenshot \
  -H "Authorization: Bearer rs_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com", "preset": "og_card"}' \
  --output github.png

HTML Template Screenshot

curl -X POST https://api.renderscreenshot.com/v1/screenshot \
  -H "Authorization: Bearer rs_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<html><body style=\"background:#1a1a2e;color:white;display:flex;align-items:center;justify-content:center;height:100vh;font-family:system-ui\"><h1>Welcome!</h1></body></html>",
    "viewport": {"width": 1200, "height": 630}
  }' \
  --output welcome.png

Markdown Screenshot

curl -X POST https://api.renderscreenshot.com/v1/screenshot \
  -H "Authorization: Bearer rs_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# Hello World\n\nThis is a test.",
    "markdown_theme": "github"
  }' \
  --output markdown.png

See Also

Was this page helpful?