Docs / Getting Started | HTML to Image Docs

Getting Started

Welcome to html2img. This guide covers the three endpoints, authentication, and the response format you can expect.

Authentication

All API requests require authentication using an API key. Include your key in the X-API-Key header on every request.

Which should I use?

Pick raw HTML for full control, the URL endpoint for screenshots of pages you already host, or named templates when you want to skip the markup step entirely.

Three endpoints

1. HTML and CSS API

POST https://app.html2img.com/api/html

Send raw HTML and CSS, get back a PNG. Run inline JavaScript up to a 30 second budget. Best for full design control.

2. Screenshot API

POST https://app.html2img.com/api/screenshot

Send a public URL, get back a PNG of the rendered page. Best for capturing pages you already host.

3. Templates API

POST https://app.html2img.com/api/v1/templates/[slug]

Send a JSON payload to a named template endpoint. Best for skipping the markup step.

For the Screenshot API, use the webhook_url parameter when render time is unpredictable. The 30 second sync timeout is enough for most requests, but a slow third-party page can blow past it. See webhook_url docs.

For best results:

Use webhook_url for slow Screenshot API requests
Keep dpi at 1 unless you specifically need retina output
Use sync requests for the HTML API or fast Screenshot requests

Required Parameters

HTML and CSS API

Parameter	Type	Description
`html`	string	The HTML content to render. Can include inline CSS and JavaScript.

Screenshot API

Parameter	Type	Description
`url`	string	The URL to capture. Must be a valid, publicly accessible URL.

Optional Parameters

Both APIs support the following optional parameters:

Parameter	Type	Default	Description
`css`	string	null	Additional CSS to inject into the page
`width`	integer	1440	Viewport width (1-5000 pixels)
`height`	integer	900	Viewport height (1-5000 pixels)
`fullpage`	boolean	false	Whether to capture the full page height
`dpi`	integer	1	Device pixel ratio (1-4)
`webhook_url`	string	null	URL to receive the image when ready
`wait_for_selector`	string	null	Wait for a specific element to appear before capturing (does not work with iframes)
`ms_delay`	integer	0	Fixed delay in milliseconds before capture (useful for iframes and embedded content)

The Screenshot API also supports:

Parameter	Type	Default	Description
`selector`	string	null	CSS selector to capture a specific element

Higher DPI values (2-4) significantly increase processing time and memory usage. We allow these values to support specific use cases, but they often lead to timeouts when not used with webhook_url. For most cases, a DPI of 1 provides enough quality.

Response Format

Successful Response

{
    "success": true,
    "credits_remaining": 95,
    "id": "abc123",
    "url": "https://i.html2img.com/abc123.png"
}

For when using webhook_url:

{
    "success": true,
    "credits_remaining": 95,
    "id": "abc123",
    "status": "processing",
    "message": "Your image is being processed. It will be delivered to your webhook URL when ready."
}

The webhook payload, posted to your webhook_url when the render finishes, includes the same shape with the final url populated:

{
    "success": true,
    "id": "abc123",
    "url": "https://i.html2img.com/abc123.png"
}

Error Responses

Validation Error (422)

{
    "error": "Validation failed",
    "code": "validation_error",
    "details": {
        "html": ["The html field is required."]
    }
}

Timeout Error (504)

{
    "error": "Request timed out",
    "code": "timeout_error",
    "message": "The request timed out while processing. Consider using the webhook_url parameter for large images.",
    "id": "abc123"
}

Service Error (500)

{
    "error": "Service error",
    "code": "service_error",
    "message": "An unknown error occurred. Please try again, and if the problem persists, contact support with reference ID: abc123.",
    "id": "abc123"
}

Documentation