Example code

Use these examples to render HTML/CSS, webpage screenshots, PDFs, and reusable templates from your application.

Works with any programming language

The HTML/CSS to Image API is a simple REST API. If your language can make an HTTP request, it can generate images and PDFs.

We provide example code for popular languages, but the API works the same way everywhere:

Send a POST request to https://hcti.io/v1/image
Include your HTML/CSS, a URL, or template values in the request
Authenticate with HTTP Basic Auth
Receive a JSON response with a generated image URL
Use the returned URL as PNG, JPG, WebP, or PDF

Start with a client library

If you are using TypeScript, JavaScript, .NET, Python, or PHP, start with the official clients. They include helpers for authentication, JSON requests, templates, and signed image URLs.

Language	Recommended starting point
TypeScript / JavaScript	Official npm client
C# / .NET	Official NuGet package
Python	Official PyPI client
PHP	Official Composer client

The pages also include direct HTTP examples when you want to work with the API without an SDK.

Common API requests

Create an image

Property	Description
Endpoint	`https://hcti.io/v1/image`
Method	`POST`
Content-Type	`application/json`
Authentication	HTTP Basic Auth (User ID + API Key)

Request body (JSON)

{
  "html": "<div class='box'>Hello, world!</div>",
  "css": ".box { padding: 20px; background: #03B875; color: white; }",
  "google_fonts": "Roboto",
  "device_scale": 2
}

Response

{
  "url": "https://hcti.io/v1/image/be4c5118-fe19-462b-a49e-48cf72697a9d",
  "id": "be4c5118-fe19-462b-a49e-48cf72697a9d"
}

The returned URL is your generated image. Append .png, .jpg, .webp, or .pdf to get a specific format.

Render a reusable template

Use a template when the design stays the same and only the data changes.

curl -X POST https://hcti.io/v1/image/t-your-template-id \
  -u "$HCTI_USER_ID:$HCTI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "template_values": {
      "title": "Quarterly report",
      "stats": {
        "revenue": "$48k",
        "growth": "12%"
      }
    }
  }'

Objects inside template_values should be encoded as JSON. If you use form data instead of JSON, send template_values as a JSON-encoded string.

Quick reference with cURL

The simplest way to test a direct HTML/CSS render:

curl -X POST https://hcti.io/v1/image \
  -u "$HCTI_USER_ID:$HCTI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"html": "<h1>Hello!</h1>"}'

Available parameters

The examples send JSON. The API also accepts form data; when using form data, nested objects such as pdf_options should be JSON encoded.

Create image body parameters

Name	Type	Description
`html`†	`String`	HTML to render. Send a snippet or a full HTML document.
`css`	`String`	CSS for your HTML. When used with `url`, the CSS is injected into the page.
`url`†	`String`	Fully qualified public URL to screenshot. When passed, it overrides `html`.

Rendering options

Name	Type	Description
`additional_header_origins`	`Array`	Allow custom `headers` on requests to specific additional HTTP or HTTPS origins.
`block_consent_banners`	`Boolean`	When set to `true`, automatically blocks cookie consent banners and popups on websites. Most useful for URL screenshots.
`color_scheme`	`String`	Set Chrome to render in `light` or `dark` mode. Affects websites using `prefers-color-scheme`.
`dedupe_duration_s`	`Integer`	Reuse an identical recent image without consuming image credits. Sets the lookback window in seconds; defaults and allowed values vary by image type and plan.
`device_scale`	`Double`	Control resolution by adjusting the pixel ratio from `0.1` to `3`. Higher values increase image quality and file size.
`disable_twemoji`	`Boolean`	Set to `true` to use native emoji fonts instead of Twemoji.
`format`	`String`	Choose the file extension in the initially returned image URL: `png`, `jpg`, `webp`, or `pdf`.
`full_screen`	`Boolean`	Generate an image of the entire height of a URL page.
`google_fonts`	`String`	Load one or more Google fonts, such as `Roboto\|Open Sans`.
`headers`	`Object`	Add custom HTTP headers when screenshotting a URL. Headers are restricted to the requested URL's origin and any `additional_header_origins`.
`identify_as_hcti`	`Boolean`	Add `X-HCTI-SCREENSHOT: 1` to the top-level request when screenshotting a URL.
`include_headers_on_subrequests`	`Boolean`	Also add custom `headers` to same-origin subrequests and subrequests matching `additional_header_origins`.
`jumbo_max_height`	`Integer`	Maximum output height in jumbo mode, up to `80,000` pixels. Must be set with `jumbo_max_width` and consumes additional image credits.
`jumbo_max_width`	`Integer`	Maximum output width in jumbo mode, up to `80,000` pixels. Must be set with `jumbo_max_height` and consumes additional image credits.
`max_wait_ms`	`Integer`	Set a maximum time limit from `500` to `10000` milliseconds for waiting before taking the screenshot.
`media_type`	`String`	Set Chrome to render using `screen` or `print` CSS media styles.
`ms_delay`	`Integer`	Delay before generating the image. Useful when waiting for JavaScript; start with `500` milliseconds.
`pdf_options`	`Object`	Customize PDF output with page size, margins, scale, and background printing.
`proxy_id`	`String`	Route outbound traffic through one of your organization's configured HTTP proxies. Available on the 10,000 images/month plan or higher.
`render_when_ready`	`Boolean`	Wait to generate the image until JavaScript calls `ScreenshotReady()`.
`selector`	`String`	Crop the image to an element matching this CSS selector, such as `section#complete-toolkit.container-lg`.
`storage_destination_id`	`String`	Save rendered files to one of your organization's configured storage destinations. Available on the 10,000 images/month plan or higher.
`timezone`	`String`	Set Chrome's timezone with an IANA identifier such as `America/New_York`.
`transparent_background`	`Boolean`	Set to `true` to render with a transparent background.
`viewport_height`	`Integer`	Set the height of Chrome's viewport. Both dimensions must be set when using either.
`viewport_landscape`	`Boolean`	Set Chrome's viewport to landscape mode.
`viewport_mobile`	`Boolean`	Set Chrome's viewport to emulate a mobile device.
`viewport_touch`	`Boolean`	Set Chrome's viewport to support touch events.
`viewport_width`	`Integer`	Set the width of Chrome's viewport. Both dimensions must be set when using either.

When rendering templated images, send a POST request to https://hcti.io/v1/image/:template_id with template_values as JSON:

{
  "template_values": {
    "title": "Quarterly report",
    "subtitle": "Q4 summary"
  }
}

For the full list of request, template, and generated image URL parameters, see Using the API and Image Templates.

Choose your language

Select your programming language to see a complete working example:

Language	Example
cURL	Terminal example
JavaScript	JavaScript example
TypeScript	TypeScript example
Python	Python example
PHP	PHP example
Ruby	Ruby example
Go	Go example
C# / .NET	C# / .NET example
VB.NET	VB.NET example
Java	Java example
Kotlin	Kotlin example
Rust	Rust example
Elixir	Elixir example
Google Apps Script	Google Apps Script example