Docs / Getting Started

Getting Started

Welcome to HTML to Image! This guide will help you get started with our API and understand its core functionality.

Authentication

All API requests require authentication using an API key. You’ll need to include your API key in the X-API-Key header with every request.

Learn more about authentication →

API Endpoints

HTML to Image provides two main endpoints for different use cases:

1. HTML/CSS API

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

Converts raw HTML and CSS into an image. Perfect for generating dynamic images, charts, or social media cards.

2. Screenshot API

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

Takes a screenshot of any public URL.

When using the Screenshot API, we strongly recommend using the webhook_url parameter. Web pages can be unpredictable in their load times, and waiting for the response may result in timeouts. The API has a 30-second timeout limit, which may not be sufficient for complex pages or higher DPI settings.

For best results:

Always use webhook_url for Screenshot API requests
Keep dpi as low as possible (preferably 1)
Use synchronous requests only for the HTML API or simple screenshot requests

Required Parameters

HTML/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. While we allow these values to support specific use cases, they often lead to timeouts when not used with webhook_url. For most cases, a DPI of 1 provides sufficient quality.

Response Format

Successful Response

{
    "success": true,
    "credits_remaining": 95,
    "id": "abc123",
    "url": "https://storage.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."
}

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