# Example code

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

[Live demo](https://htmlcsstoimage.com/#demo) [Get an API key](https://htmlcsstoimage.com/dashboard)

Using an AI coding assistant?

Connect our [MCP server](/integrations/mcp/) to generate images from your coding assistant.

## 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:

1.  Send a `POST` request to `https://hcti.io/v1/image`
2.  Include your HTML/CSS, a URL, or template values in the request
3.  Authenticate with HTTP Basic Auth
4.  Receive a JSON response with a generated image URL
5.  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](/example-code/typescript/#official-npm-client) |
| C# / .NET | [Official NuGet package](/example-code/c/) |
| Python | [Official PyPI client](/example-code/python/#official-pypi-client) |
| PHP | [Official Composer client](/example-code/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)

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

### Response

```json
{
  "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.

```bash
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:

```bash
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`. |

Required parameters

† Send `html` or `url`. CSS is optional.

### Rendering options

| Name | Type | Description |
| --- | --- | --- |
| [`additional_header_origins`](/parameters/headers/#additional-header-origins) | `Array` | Allow custom `headers` on requests to specific additional HTTP or HTTPS origins. |
| [`block_consent_banners`](/guides/advanced/blocking-cookie-banners/) | `Boolean` | When set to `true`, automatically blocks cookie consent banners and popups on websites. Most useful for URL screenshots. |
| [`color_scheme`](/parameters/color_scheme/) | `String` | Set Chrome to render in `light` or `dark` mode. Affects websites using `prefers-color-scheme`. |
| [`dedupe_duration_s`](/parameters/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`](/parameters/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`](/guides/debugging/emoji/#disabling-twemoji) | `Boolean` | Set to `true` to use native emoji fonts instead of Twemoji. |
| [`format`](/parameters/format/) | `String` | Choose the file extension in the initially returned image URL: `png`, `jpg`, `webp`, or `pdf`. |
| [`full_screen`](/parameters/full_screen/) | `Boolean` | Generate an image of the entire height of a URL page. |
| [`google_fonts`](/parameters/google_fonts/) | `String` | Load one or more Google fonts, such as `Roboto\|Open Sans`. |
| [`headers`](/parameters/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`](/parameters/identify_as_hcti/) | `Boolean` | Add `X-HCTI-SCREENSHOT: 1` to the top-level request when screenshotting a URL. |
| [`include_headers_on_subrequests`](/parameters/headers/#include-headers-on-subrequests) | `Boolean` | Also add custom `headers` to same-origin subrequests and subrequests matching `additional_header_origins`. |
| [`jumbo_max_height`](/guides/advanced/jumbo-images/) | `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`](/guides/advanced/jumbo-images/) | `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`](/parameters/max_wait_ms/) | `Integer` | Set a maximum time limit from `500` to `10000` milliseconds for waiting before taking the screenshot. |
| [`media_type`](/parameters/media_type/) | `String` | Set Chrome to render using `screen` or `print` CSS media styles. |
| [`ms_delay`](/parameters/ms_delay/) | `Integer` | Delay before generating the image. Useful when waiting for JavaScript; start with `500` milliseconds. |
| [`pdf_options`](/parameters/pdf_options/) | `Object` | Customize PDF output with page size, margins, scale, and background printing. |
| [`proxy_id`](/parameters/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`](/parameters/render_when_ready/) | `Boolean` | Wait to generate the image until JavaScript calls `ScreenshotReady()`. |
| [`selector`](/parameters/selector/) | `String` | Crop the image to an element matching this CSS selector, such as `section#complete-toolkit.container-lg`. |
| [`storage_destination_id`](/parameters/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`](/parameters/timezone/) | `String` | Set Chrome's timezone with an IANA identifier such as `America/New_York`. |
| [`transparent_background`](/parameters/transparent_background/) | `Boolean` | Set to `true` to render with a transparent background. |
| [`viewport_height`](/parameters/viewport/#viewport-width-and-height) | `Integer` | Set the height of Chrome's viewport. Both dimensions must be set when using either. |
| [`viewport_landscape`](/parameters/viewport/#viewport-landscape) | `Boolean` | Set Chrome's viewport to landscape mode. |
| [`viewport_mobile`](/parameters/viewport/#viewport-mobile) | `Boolean` | Set Chrome's viewport to emulate a mobile device. |
| [`viewport_touch`](/parameters/viewport/#viewport-touch) | `Boolean` | Set Chrome's viewport to support touch events. |
| [`viewport_width`](/parameters/viewport/#viewport-width-and-height) | `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:

```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](/getting-started/using-the-api/) and [Image Templates](/getting-started/templates/).

* * *

## Choose your language

Select your programming language to see a complete working example:

| Language | Example |
| --- | --- |
| cURL | [Terminal example](/example-code/curl/) |
| JavaScript | [JavaScript example](/example-code/javascript/) |
| TypeScript | [TypeScript example](/example-code/typescript/) |
| Python | [Python example](/example-code/python/) |
| PHP | [PHP example](/example-code/php/) |
| Ruby | [Ruby example](/example-code/ruby/) |
| Go | [Go example](/example-code/go/) |
| C# / .NET | [C# / .NET example](/example-code/c/) |
| VB.NET | [VB.NET example](/example-code/vb.net/) |
| Java | [Java example](/example-code/java/) |
| Kotlin | [Kotlin example](/example-code/kotlin/) |
| Rust | [Rust example](/example-code/rust/) |
| Elixir | [Elixir example](/example-code/elixir/) |
| Google Apps Script | [Google Apps Script example](/example-code/google-apps-script/) |