HTML To Image API » Technical Documentation
API for converting HTML documents with CSS and JavaScript to multiple image formats.
This API enables your application to capture screenshots of websites or HTML documents. It can be used to take full-page screenshots or capture specific elements within the DOM. This functionality allows your application to create images in various formats, such as PNG or WEBP, using web technologies.
API connection
Server and protocols involved.
| Server: | https://zpk.systems |
|---|---|
| Scheme: | HTTPS, secure connections only. |
| Protocol: |
JSON recommended
Sending a JSON in the request body, and specifying a Content-Type: application/json header in the request Files should be sent encoded as a base64 string. Form-Data not recommended
Format used in web forms, not recommended. When sending a form_data request you can send all the fields separately. However if the request is very large we recommend that you send the content of the request in a single text field called _json (with an underscore). This special parameter will be processed by our backend as if it were a regular JSON request. |
The server to send the requests to is https://zpk.systems, using a secure HTTPS connection.
The recommended communication type is JSON, in which case we will specify in the connection a Content-Type: application/json, and we will send the request body as a valid JSON string.
Convert an HTML page or element to an image
Endpoint and Request Parameters
Capture request
Call the /capture endpoint, specifying the HTML document and the elements to capture.
| Parameter | Description |
|---|---|
| application_id |
string required An application ID, which can be obtained by clicking on 'details' in your dashboard. |
| api_key |
string required The API KEY of the application making the call to this API, which can be obtained in your dashboard by clicking on 'details' of an application. |
| url |
string required The URL to load before capturing, which can include port and extra GET parameters. Our systems will wait for the page to be fully loaded before starting the capture to ensure that CSS, fonts, and images are captured correctly. The maximum wait time for the page to be fully loaded is 8 seconds. |
| resolution_width |
integer optional defaulting to 1920 max:3200 | min:320 The width in pixels of the virtual capture window; note that responsive pages will adapt to the specified resolution. The resolution parameters can be used to obtain the version of the page adapted for different devices such as desktop, smartphone, or tablet. |
| resolution_height |
integer optional defaulting to 1080 max:3200 | min:320 The height in pixels of the virtual capture window; note that responsive pages will adapt to the specified resolution. Resolution parameters can be used to obtain versions of the page adapted for different devices such as desktops, smartphones, or tablets |
| injected_js |
string optional JavaScript code that will execute as soon as the page is loaded. Once this code execution finishes, the image capture will proceed. This code allows interaction with page elements before capturing, for example, to close a cookie notice if present. |
| capture_list |
array of capture elements required A list of objects that define which parts of the document to capture and how this capture should be performed. Refer to the following table for the format of this list and instructions on configuring the capture of one or multiple DOM elements. |
Structure of capture_list
This array contains information about which elements of the page to capture.
| parameter | description |
|---|---|
| selector |
string required A CSS selector pointing to the element to capture. Examples of selectors:
|
| force_transparency |
bolean optional, false Setting this parameter to true will remove the background set by the page on the selected element and all its parent elements in the DOM hierarchy, ensuring the final image has a transparent background. It's important to note that these DOM changes persist until a new API request is made. |
| force_parent_transparency |
bolean optional, false Setting this parameter to true will remove the background set by the page on the parent element and all its ancestors in the DOM hierarchy, aiming to ensure that the container of the selector has a transparent background. This action does not affect the background color or image of the element targeted by the selector. Please note that these DOM changes persist until a new API request is made. |
| output_format |
string optional, default PNG The image format returned. Supported formats include JPEG, WebP, and PNG. Please note that PNG images always maintain the same output quality, so the output_quality parameter will be ignored by the API when requesting a PNG image. Note that JPEG images do not support transparency. If you need full or partial transparency, you should use PNG or WebP formats. |
| output_quality |
integer optional, default 80 The quality of the returned image increases with higher values, resulting in larger file sizes. The maximum quality is 100, with a default of 80. This parameter applies only to formats that support output quality, such as WebP and JPEG. For PNG images, this parameter will be ignored. |
API response
Success responses
{
"success": true,
"results": [
{
"selector": "#list:first-child",
"success": true,
"download_url": "http://zpk.systems/api-results/html-to-image/download/SDFKJ98jjsdfDsfpaapsZWSXXX/4893.webp"
},
{
"selector": "#unexisting_element_id",
"success": false,
"error": "NO_MATCH_FOR_SELECTOR"
}
],
"costs": {
"base_request_cost": 0.002,
"price_extra_pixels": 0.0003,
"total_cost": 0.0023
}
}
In this example, the first element was successfully captured, but the second element could not be captured because there is no element on the page that matches the selector.
Response structure
| Parameter | Description |
|---|---|
| success |
bolean
A boolean with a value of true if your request was successfully processed, or false in case of errors. |
| results |
array
An array of objects that contains capture data for each requested element, including the download URL and an error code if any issues were detected. Refer to the table below for details on the elements within this array. |
| costs |
array
Detailed information about the cost of the sent request, where:
base_request_cost: The cost of the capture request: 0,002 €
total_cost: The total cost of this request, which in this API is the same as base_request_cost.
|
| errors |
array One or more errors that occurred, the errors array is only returned when the boolean success is false. Each element of the errors array includes: id: An error identifier code.
on: An indicator of the element in the sent data causing the error (only for errors caused by incorrect data submission).
message: Text providing details of the error for debugging purposes.
|
Results structure
| Parameter | Description |
|---|---|
| selector |
string
Used selector to capture this element. |
| success |
boleano
A boolean indicating if this element could be captured, true if affirmative. |
| download_url |
string
A URL where you can download the generated image for the item. This image is kept on our servers for a maximum of 24 hours and can be downloaded up to ten times. |
| error |
string
Only in case of errors, it will contain a string indicating the type of error. These are the possible errors returned when the image could not be processed. NO_MATCH_FOR_SELECTOR: No element matching the specified selector was found. UNEXPECTED_ERROR: This is an internal error that should not happen, please contact ZPK. |
Example for general error
{
"success": false,
"errors": [
{
"id": "MISSING_REQUIRED_PARAMETER",
"message": "Parameter 'url' is required",
"on": "url"
}
]
}
Error management and debugging
General Errors and Capture Errors
This API returns two types of errors: a general error if the document's URL cannot be accessed, and specific errors related to capturing an element within the page.
A general error indicates that the document could not be accessed, thus preventing the capture of any elements.
It is important to note that this API does not consider it a connection error if it successfully connects to the other end, even if the destination server returns HTTP error codes such as 404 or 500.
This is designed to allow capturing error pages in quality control applications.
General errors
These errors prevent the page from loading. Common issues include insufficient balance in your account to make the request, or a network error when attempting to load the resource specified in the URL.
Debugging Network Errors
Ensure that the URL provided is valid, does not timeout, and is not blocked or cached in a way that prevents our servers from accessing it.
Element Capture Errors
These errors occur at the element level when an attempt to capture fails, typically due to an incorrect selector being specified.
Ensure that the correct page is being loaded and that the selector used is accurate.
Remember, you can capture the entire document by using "document" as the selector.
Make sure there are no factors influencing the visibility of the element, such as it being shown only to authenticated users.
HTML to Image PHP integration
PHP-ZPK is an open-source library installable via Composer that allows you to integrate our APIs into your PHP project with minimal effort.
Go to PHP SDKPHP-ZPK installation with composer
composer require zpksystems/phpzpk
Example of a request
<?php
$application = new zpkApplication('app_id','api_key');
$capturer = new zpkHtmlToImageCapturer($application,$url);
$capturer->addElement(['selector'=>'#example_1']);
$capturer->addElement(['selector'=>'#example_2','output_format'=>'webp','force_transparency'=>true]);
echo json_encode($imageCapturer->capture(),
JSON_PRETTY_PRINT|JSON_UNESCAPED_UNICODE);
Html To Image Pricing
HtmlToImage has a cost per document capture request. The cost per request is 0,002€ which will be deducted from your current credit.