Using the HTML/CSS to Image API
Generate images from HTML and CSS.
Using Cursor or Claude Code?
Generate images without writing code using our MCP Server integration.
Authentication
The API uses HTTP Basic authentication.
- Your username is your User ID and your password is your API Key. Both of these are available from the dashboard. The code samples demonstrate how to authenticate your request.
- Treat your API Key like a password. If exposed, it could be used to create images using your account.
Creating an image
To generate an image, make an HTTP request to the API.
post https://hcti.io/v1/image
Parameters
The create image endpoint accepts the following parameters. Accepted as either json or formdata.
| Name | Type | Description |
|---|---|---|
| html† | String | This is the HTML you want to render. You can send an HTML snippet (<div>Your content</div>) or an entire webpage. |
| css | String | The CSS for your image. When using with url it will be injected into the page. |
| url† | String | The fully qualified URL to a public webpage. Such as https://htmlcsstoimage.com. When passed this will override the html param and will generate a screenshot of the url. |
Required params
† Either url OR html is required, but not both. css is optional.
Additional parameters
Optional parameters for greater control over your image.
| Name | Type | Description |
|---|---|---|
| google_fonts | String | Google fonts to be loaded. Example: Roboto. Multiple fonts can be loaded like this: Roboto|Open Sans |
| selector | String | A CSS selector for an element on the webpage. We’ll crop the image to this specific element. For example: section#complete-toolkit.container-lg |
| ms_delay | Integer | The number of milliseconds the API should delay before generating the image. This is useful when waiting for JavaScript. We recommend starting with 500. Large values slow down the initial render time. Learn more. |
| max_wait_ms | Integer | Sets a maximum time limit (500-10000ms) for waiting before taking the screenshot. Unlike ms_delay, this is a cap rather than a fixed delay. Useful when pages load extra irrelevant content. |
| device_scale | Double | Controls the image resolution by adjusting the pixel ratio. Minimum: 0.1, Maximum: 3. Higher values increase image quality and file size. For example, 2 will double the resolution. Learn more. |
| render_when_ready | Boolean | Set to true to control when the image is generated. Call ScreenshotReady() from JavaScript to generate the image. Learn more. |
| full_screen | Boolean | When set to true, the API will generate an image of the entire height of the page. Learn more. |
| block_consent_banners | Boolean | When set to true, automatically blocks cookie consent banners and popups on websites. Most useful for URL screenshots. Learn more. |
| viewport_width | Integer | Set the width of Chrome’s viewport. This will disable automatic cropping. Both height and width parameters must be set if using either. Learn more. |
| viewport_height | Integer | Set the height of Chrome’s viewport. This will disable automatic cropping. Both height and width parameters must be set if using either. Learn more. |
| color_scheme | String | Set Chrome to render in light or dark mode. Affects websites using prefers-color-scheme. Learn more. |
| timezone | String | Render your image with Chrome set to a specified timezone. Use IANA timezone identifiers like America/New_York. Learn more. |
| disable_twemoji | Boolean | Twemoji is used by default to render emoji consistently. Set to true to use native emoji fonts instead. |
Example responses
STATUS: 200 OK
{
"url": "https://hcti.io/v1/image/be4c5118-fe19-462b-a49e-48cf72697a9d",
"id": "be4c5118-fe19-462b-a49e-48cf72697a9d"
}
STATUS: 400 BAD REQUEST
{
"error": "Bad Request",
"statusCode": 400,
"message": "HTML is Required"
}
STATUS: 429 TOO MANY REQUESTS
{
"error": "Plan limit exceeded",
"statusCode": 429,
"message": "You've used 3055 of your 3000 renders. Upgrade via the Dashboard: https://htmlcsstoimage.com/dashboard"
}
Getting an image
After creating an image, you can use the returned URL to either download your image, or use it directly in your website.
get https://hcti.io/v1/image/:image_id
This URL is permanent for as long as your account is active. It’s automatically cached and optimized by Cloudflare’s global content delivery network. You can use it directly on your webpages and not worry about hurting your page speed score.
- Lossless optimization: each image is optimized with no change in image quality.
- Global cache: the image is cached near your users to reduce latency.
File formats
The API supports jpg, png, webp, and pdf. If no file extension is passed, you’ll get back a png by default. If you need a different file format, adjust the extension on the url.
| Format | Example |
|---|---|
| png | https://hcti.io/v1/image/a3ab2ab2-906e-4b5c-a88d-41a1c3f3779e.png |
| jpg | https://hcti.io/v1/image/a3ab2ab2-906e-4b5c-a88d-41a1c3f3779e.jpg |
| webp | https://hcti.io/v1/image/a3ab2ab2-906e-4b5c-a88d-41a1c3f3779e.webp |
https://hcti.io/v1/image/a3ab2ab2-906e-4b5c-a88d-41a1c3f3779e.pdf |
PNG by default
The API returns png by default. If no extension is on the URL, a png will be generated.
Query parameters
Query parameters can be added to the URL to adjust your image.
| Name | Type | Description |
|---|---|---|
| height | Integer | The height of the image. Maximum 5000. |
| width | Integer | The width of the image. Maximum 5000. |
| dpi | Integer | Sets the DPI metadata tag on the image. Minimum 30, maximum 600. |
| dl | Integer | Set dl=1 and the image will be served as a downloadable attachment. |
Cropping parameters
Advanced cropping options for precise control over the rendered image region.
| Name | Type | Description |
|---|---|---|
| aspect_ratio | String | Crop to a specific aspect ratio. Format: width_height (e.g., 16_9, 1_1). |
| x_origin | String | Origin point for x-axis cropping. Accepts pixels (100px) or percentage (50%). |
| y_origin | String | Origin point for y-axis cropping. Accepts pixels (100px) or percentage (50%). |
| x_1 | String | Starting x coordinate for crop region. Use with x_2 or crop_width. |
| x_2 | String | Ending x coordinate for crop region. Must be used with x_1. |
| y_1 | String | Starting y coordinate for crop region. Use with y_2 or crop_height. |
| y_2 | String | Ending y coordinate for crop region. Must be used with y_1. |
| crop_width | String | Width of the crop region. Use with x_1 or alone with aspect_ratio. |
| crop_height | String | Height of the crop region. Use with y_1 or alone with aspect_ratio. |
Cropping examples
Here’s a base image (600x400 pixels) and how different cropping parameters affect it:
Original image:
Crop to 1:1 square from center (aspect_ratio=1_1&crop_height=100%):
?aspect_ratio=1_1&crop_height=100%
Crop left third (x_1=0&crop_width=33%):
?x_1=0&crop_width=33%
Crop center section (x_1=33%&x_2=66%):
?x_1=33%&x_2=66%
Crop right third (x_1=67%&crop_width=33%):
?x_1=67%&crop_width=33%
Crop to 16:9 aspect ratio (aspect_ratio=16_9&crop_width=100%):
?aspect_ratio=16_9&crop_width=100%
Deleting an image
delete https://hcti.io/v1/image/:image_id
To delete an image using the API, you can send a DELETE request to your image URL. This will remove your image from our servers and clear the caching for the image in our CDN.
All data and copies of the image are deleted. This cannot be undone.
Example response
STATUS: 202 ACCEPTED
Batch image creation
Create up to 25 images in a single API request. This is more efficient than making multiple individual requests.
post https://hcti.io/v1/image/batch
Parameters
| Name | Type | Description |
|---|---|---|
| default_options | Object | Default parameters applied to all images in the batch. Accepts all standard image creation parameters. |
| variations | Array | Array of image objects. Each can override default_options. Maximum 25 items. |
Example request
{
"default_options": {
"css": "body { font-family: sans-serif; }",
"device_scale": 2
},
"variations": [
{ "html": "<div>Image 1</div>" },
{ "html": "<div>Image 2</div>" },
{ "html": "<div>Image 3</div>", "device_scale": 1 }
]
}
Example response
STATUS: 200 OK
{
"images": [
{ "url": "https://hcti.io/v1/image/abc123", "id": "abc123" },
{ "url": "https://hcti.io/v1/image/def456", "id": "def456" },
{ "url": "https://hcti.io/v1/image/ghi789", "id": "ghi789" }
]
}
Batch deletion
Delete multiple images at once by sending their IDs.
delete https://hcti.io/v1/image/batch
{
"ids": ["abc123", "def456", "ghi789"]
}
STATUS: 202 ACCEPTED
Listing images
Retrieve a list of all images created by your account with pagination support.
get https://hcti.io/v1/images
Query parameters
| Name | Type | Description |
|---|---|---|
| count | Integer | Number of images to return. Default 50, maximum 50. |
| page_token | String | Token for pagination. Use next_page_token from the previous response. |
Example response
STATUS: 200 OK
{
"images": [
{
"id": "be4c5118-fe19-462b-a49e-48cf72697a9d",
"url": "https://hcti.io/v1/image/be4c5118-fe19-462b-a49e-48cf72697a9d",
"created_at": "2024-03-15T10:30:00Z"
},
{
"id": "a3ab2ab2-906e-4b5c-a88d-41a1c3f3779e",
"url": "https://hcti.io/v1/image/a3ab2ab2-906e-4b5c-a88d-41a1c3f3779e",
"created_at": "2024-03-14T08:15:00Z"
}
],
"next_page_token": "eyJsYXN0X2lkIjoiYTNhYjJhYjItOTA2ZS00YjVjLWE4OGQtNDFhMWMzZjM3NzllIn0=",
"has_next_page": true
}
Checking account usage
get https://hcti.io/v1/usage
To check your account usage, you can make a request to the usage endpoint. It will return the total images created for your account rolled up into different time periods.
We recommend using this endpoint for tracking your usage in tools such as Datadog.
Example response
STATUS: 200 OK
{
"data": {
"hour": {
"2024-03-14T14:00:00Z": 54,
"2024-03-14T15:00:00Z": 56,
"2024-03-14T16:00:00Z": 56,
"2024-03-14T17:00:00Z": 57,
"2024-03-14T18:00:00Z": 59,
"2024-03-14T19:00:00Z": 55,
"2024-03-14T20:00:00Z": 58,
"2024-03-14T21:00:00Z": 54,
"2024-03-14T22:00:00Z": 57,
"2024-03-14T23:00:00Z": 57,
"2024-03-15T00:00:00Z": 60,
"2024-03-15T01:00:00Z": 56,
"2024-03-15T02:00:00Z": 56,
"2024-03-15T03:00:00Z": 55,
"2024-03-15T04:00:00Z": 57,
"2024-03-15T05:00:00Z": 55,
"2024-03-15T06:00:00Z": 55,
"2024-03-15T07:00:00Z": 56,
"2024-03-15T08:00:00Z": 55,
"2024-03-15T09:00:00Z": 60,
"2024-03-15T10:00:00Z": 62,
"2024-03-15T11:00:00Z": 60,
"2024-03-15T12:00:00Z": 62,
"2024-03-15T13:00:00Z": 62,
"2024-03-15T14:00:00Z": 62,
"2024-03-15T15:00:00Z": 61,
"2024-03-15T16:00:00Z": 61,
"2024-03-15T17:00:00Z": 60,
"2024-03-15T18:00:00Z": 61,
"2024-03-15T19:00:00Z": 64,
"2024-03-15T20:00:00Z": 61,
"2024-03-15T21:00:00Z": 61,
"2024-03-15T22:00:00Z": 62,
"2024-03-15T23:00:00Z": 63,
"2024-03-16T00:00:00Z": 62,
"2024-03-16T01:00:00Z": 62,
"2024-03-16T02:00:00Z": 60,
"2024-03-16T03:00:00Z": 60,
"2024-03-16T04:00:00Z": 62,
"2024-03-16T05:00:00Z": 53,
"2024-03-16T06:00:00Z": 60,
"2024-03-16T07:00:00Z": 60,
"2024-03-16T08:00:00Z": 60,
"2024-03-16T09:00:00Z": 60,
"2024-03-16T10:00:00Z": 60,
"2024-03-16T11:00:00Z": 60,
"2024-03-16T12:00:00Z": 68,
"2024-03-16T13:00:00Z": 62,
"2024-03-16T14:00:00Z": 61,
"2024-03-16T15:00:00Z": 60,
"2024-03-16T16:00:00Z": 60,
"2024-03-16T17:00:00Z": 65,
"2024-03-16T18:00:00Z": 63,
"2024-03-16T19:00:00Z": 60,
"2024-03-16T20:00:00Z": 60,
"2024-03-16T21:00:00Z": 60,
"2024-03-16T22:00:00Z": 62,
"2024-03-16T23:00:00Z": 61,
"2024-03-17T00:00:00Z": 60,
"2024-03-17T01:00:00Z": 60,
"2024-03-17T02:00:00Z": 65,
"2024-03-17T03:00:00Z": 63,
"2024-03-17T04:00:00Z": 62,
"2024-03-17T05:00:00Z": 63,
"2024-03-17T06:00:00Z": 63,
"2024-03-17T07:00:00Z": 64,
"2024-03-17T08:00:00Z": 63,
"2024-03-17T09:00:00Z": 64,
"2024-03-17T10:00:00Z": 60,
"2024-03-17T11:00:00Z": 61,
"2024-03-17T12:00:00Z": 61,
"2024-03-17T13:00:00Z": 29
},
"day": {
"2024-01-19T00:00:00Z": 1569,
"2024-01-20T00:00:00Z": 1722,
"2024-01-21T00:00:00Z": 1604,
"2024-01-22T00:00:00Z": 1560,
"2024-01-23T00:00:00Z": 1571,
"2024-01-24T00:00:00Z": 1627,
"2024-01-25T00:00:00Z": 1660,
"2024-01-26T00:00:00Z": 1527,
"2024-01-27T00:00:00Z": 1588,
"2024-01-28T00:00:00Z": 1549,
"2024-01-29T00:00:00Z": 1523,
"2024-01-30T00:00:00Z": 1662,
"2024-01-31T00:00:00Z": 1556,
"2024-02-01T00:00:00Z": 1585,
"2024-02-02T00:00:00Z": 1539,
"2024-02-03T00:00:00Z": 1556,
"2024-02-04T00:00:00Z": 1487,
"2024-02-05T00:00:00Z": 1580,
"2024-02-06T00:00:00Z": 1498,
"2024-02-07T00:00:00Z": 1485,
"2024-02-08T00:00:00Z": 1474,
"2024-02-09T00:00:00Z": 1487,
"2024-02-10T00:00:00Z": 1513,
"2024-02-11T00:00:00Z": 1477,
"2024-02-12T00:00:00Z": 1464,
"2024-02-13T00:00:00Z": 1458,
"2024-02-14T00:00:00Z": 1452,
"2024-02-15T00:00:00Z": 1477,
"2024-02-16T00:00:00Z": 1471,
"2024-02-17T00:00:00Z": 1482,
"2024-02-18T00:00:00Z": 1499,
"2024-02-19T00:00:00Z": 1504,
"2024-02-20T00:00:00Z": 1530,
"2024-02-21T00:00:00Z": 1502,
"2024-02-22T00:00:00Z": 1501,
"2024-02-23T00:00:00Z": 1486,
"2024-02-24T00:00:00Z": 1475,
"2024-02-25T00:00:00Z": 1469,
"2024-02-26T00:00:00Z": 1460,
"2024-02-27T00:00:00Z": 1451,
"2024-02-28T00:00:00Z": 1443,
"2024-02-29T00:00:00Z": 1447,
"2024-03-01T00:00:00Z": 1443,
"2024-03-02T00:00:00Z": 1455,
"2024-03-03T00:00:00Z": 1473,
"2024-03-04T00:00:00Z": 1482,
"2024-03-05T00:00:00Z": 1463,
"2024-03-06T00:00:00Z": 1472,
"2024-03-07T00:00:00Z": 1452,
"2024-03-08T00:00:00Z": 1469,
"2024-03-09T00:00:00Z": 1478,
"2024-03-10T00:00:00Z": 1494,
"2024-03-11T00:00:00Z": 1469,
"2024-03-12T00:00:00Z": 1471,
"2024-03-13T00:00:00Z": 1465,
"2024-03-14T00:00:00Z": 1462,
"2024-03-15T00:00:00Z": 1336,
"2024-03-16T00:00:00Z": 1427,
"2024-03-17T00:00:00Z": 838
},
"month": {
"2023-10-01T00:00:00Z": 44847,
"2023-11-01T00:00:00Z": 44973,
"2023-12-01T00:00:00Z": 43263,
"2024-01-01T00:00:00Z": 59095,
"2024-02-01T00:00:00Z": 56422,
"2024-03-01T00:00:00Z": 50747
}
},
"per_billing_period": [
{
"total_images": 439,
"start": "2018-11-02T22:57:29.015Z",
"end": "2018-12-02T22:57:29.015Z"
},
{
"total_images": 3744,
"start": "2018-12-02T22:57:29.015Z",
"end": "2019-01-01T22:57:29.015Z"
},
{
"total_images": 595,
"start": "2019-01-01T22:57:29.015Z",
"end": "2019-01-31T22:57:29.015Z"
},
{
"total_images": 123570,
"start": "2019-01-31T22:57:29.015Z",
"end": "2019-03-02T22:57:29.015Z"
},
{
"total_images": 55398,
"start": "2019-03-02T22:57:29.015Z",
"end": "2019-04-01T22:57:29.015Z"
},
{
"total_images": 40935,
"start": "2019-04-01T22:57:29.015Z",
"end": "2019-05-01T22:57:29.015Z"
}
]
}
Need help?
Talk to a human. Please email us support@htmlcsstoimage.com with any questions and we’ll gladly help you get started.