--- layout: page title: Image Templates permalink: /getting-started/templates/ description: >- Create reusable templates for your HTML & CSS to make image generation easy. parent: Getting started nav_order: 4 --- # Image Templates {: .no_toc } {: .fs-9 } Create reusable templates to make image generation easy. {: .fs-6 .fw-300 } [Get an API Key](https://htmlcsstoimage.com){: .btn .btn-blue .fs-5 .mb-4 .mb-md-0 }

## What are Templates? A template defines reusable image markup with **variables** that are replaced when an image is created. You can create templates by sending HTML and CSS to the API, or by building a template visually in the [Template Editor](/template-editor/). Templates created in the editor are still rendered through the same template API. If you are building templates visually, start with the [Template Editor Quick Start](/template-editor/quick-start/). For API-only templates, continue below. ### Handlebars variables Templates support [Handlebars](https://handlebarsjs.com/) variables. Add {% raw %}`{{title_text}}`{% endraw %} to your HTML, then pass a value for `title_text` when creating the image. ### Common use cases - Define a reusable template, then pass variables to it to generate unique images. - Use the [Template Editor](/template-editor/) to build a reusable image from blocks instead of writing all of the HTML and CSS by hand. - Create images using signed URLs in a `GET` request. - Generate social sharing images, such as `og:image` or `twitter:image`. For an existing website or CMS, an [OG Image Config](/getting-started/og-images/) can populate the template from each page's metadata. ### Example This image was generated with a template. ```javascript { "text": "With templates, you can use variables to replace parts of your image.", "avatar_url": "https://avataaars.io/?avatarStyle=Transparent&topType=ShortHairDreads01&accessoriesType=Round&hairColor=BrownDark&facialHairType=BeardLight&facialHairColor=BrownDark&clotheType=BlazerShirt&eyeType=Happy&eyebrowType=DefaultNatural&mouthType=Eating&skinColor=Brown", "name": "Freddy", "username": "@freddy", } ```

    {% cloudinary /assets/images/template.png alt="Example of an image template use for converting html to an image" %}
  

HTML: {: .text-delta } ```html {% raw %}

{% endraw %} ``` ## Creating a Template To generate a template, make an HTTP request to the API.

  post https://hcti.io/v1/template

### Parameters The create template 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 \(`

Your content

`\) or an entire webpage. | | **css** | `String` | The CSS for your image. | |**name**| `String` | A short name to identify your template `max length 64`| |**description**| `String` | Description to elaborate on the use of your template `max length 1024` | {% include hint.md title="Required params" text="For creating a template, `html` is required while `css` is optional.
`name` and `description` are optional, but may be useful to help you differentiate your templates in the future." %} ### Additional parameters Optional parameters for greater control over your image. {% include template_additional_parameters.md %}

### Example responses ``` STATUS: 201 CREATED ``` ```javascript { "template_id": "t-b0354248-e7f6-4cca-81c6-2b4a70a16388", "template_version": 1594409399761 } ``` ``` STATUS: 400 BAD REQUEST ``` ```javascript { "error": "Bad Request", "statusCode": 400, "message": "HTML is Required" } ``` ``` STATUS: 429 TOO MANY REQUESTS ``` ```javascript { "error": "Plan limit exceeded", "statusCode": 429, "message": "The tryit plan is limited to 1 template" } ``` {% include hint.md title="Plan Limits" text="Free plans can create 1 template. Paid plans can create 1,000. You can edit your existing templates an unlimited number of times." %}

## Editing a Template To edit a template you've already made, make an HTTP request to the API with the template_id listed in the CREATE response.

  post https://hcti.io/v1/template/:template_id

### Parameters The edit template 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 \(`

Your content

## Creating an image with a template To generate a templated image, make an HTTP request to the API using the template_id listed in the [CREATE response](#example-responses).

  post https://hcti.io/v1/image/:template_id

You can also generate a templated image with a signed `GET` URL that renders on demand. See [Creating a templated image URL](/getting-started/create-and-render/#creating-a-templated-image-url). To use one template for automatic social cards across an existing site, select it in an [OG Image Config](/getting-started/og-images/#template-values). HCTI can map page titles, descriptions, Open Graph metadata, and explicit `html:tv:` values to its variables. {% include hint.md title="Template Versions" text="When you create an image using a `template_id`, it will automatically use the most recent version of that template. If you want to create an image from a specific template_version you can append `/:template_version` to your POST: `hcti.io/v1/image/:template_id/:template_version`" %} ### Parameters The create templated image endpoint accepts the following parameters, accepted as either `json` or `formdata`. - If you use `formdata`, your `template_values` need to be JSON encoded. | Name | Type | Description | |:-------------|:------------------|:------| | **template_values*** | `JSON` | Values for the variables in your template. For editor templates, see the [Variables guide](/template-editor/variables/). |

## Listing your templates To list all of your templates, send a get to `v1/template`. Authentication is required.

  get https://hcti.io/v1/template

### Example responses ``` STATUS: 200 OK ``` ```javascript { "data": [ { "css": null, "created_at": "2020-07-19T17:16:43.987+00:00", "description": null, "device_scale": 2.0, "google_fonts": null, "html": "

\n
\n\n\n\n

", "id": "t-5ff7b966-d32c-4143-bda3-57a440e97a80", "max_wait_ms": null, "ms_delay": 1500, "name": null, "render_when_ready": null, "render_count": 142, "storage_destination_id": "your-storage-destination-id", "color_scheme": null, "timezone": null, "updated_at": "2020-07-19T17:16:43.987+00:00", "version": 1595179003987, "viewport_height": null, "viewport_width": null } ], "pagination": { "next_page_start": null } } ``` ### Response fields | Field | Type | Description | |:------|:-----|:------------| | **render_count** | `Integer` | Number of times this template has been used to generate images. | | **storage_destination_id** | `String` or `null` | Storage destination inherited by images created from this template. | | **color_scheme** | `String` | Light or dark mode setting, if configured. | | **timezone** | `String` | Timezone setting, if configured. | ## Listing your template versions To list all versions of a template, send a get to `v1/template/:template_id`. Authentication is required.

  get https://hcti.io/v1/template/:template_id

\n
\n\n\n\n

{{name}}