Image Templates

Create reusable templates to make image generation easy.

Get an API Key

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. 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. For API-only templates, continue below.

Handlebars variables

Templates support Handlebars variables. Add {{title_text}} 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 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 can populate the template from each page’s metadata.

Example

This image was generated with a template.

{ 
  "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",
}

HTML:

<div class="p-4 text-center mt-4" style="width: 500px">
  <span class="tweet-text mb-4">
    {{text}}
  </span>
  <div class="mt-2 p-4">
    <img src="{{avatar_url}}" class="rounded-circle shadow border mt-4" width="100px">
  </div>
  <h4 class="mt-2">
    {{name}}
  </h4>
  <span class="text-muted">{{username}}</span>
</div>

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.

Additional parameters

Optional parameters for greater control over your image.

Example responses

STATUS: 201 CREATED

{
    "template_id": "t-b0354248-e7f6-4cca-81c6-2b4a70a16388",
    "template_version": 1594409399761
}

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": "The tryit plan is limited to 1 template"
}

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.

Additional parameters

Optional parameters for greater control over your image.

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.

  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.

To use one template for automatic social cards across an existing site, select it in an OG Image Config. HCTI can map page titles, descriptions, Open Graph metadata, and explicit html:tv: values to its variables.

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.

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

{
  "data": [
    {
      "css": null,
      "created_at": "2020-07-19T17:16:43.987+00:00",
      "description": null,
      "device_scale": 2.0,
      "google_fonts": null,
      "html": "<blockquote class=\"twitter-tweet\" style=\"width: 400px;\" data-dnt=\"true\">\n<p lang=\"en\" dir=\"ltr\"></p>\n\n<a href=\"\"></a>\n\n</blockquote> <script async src=\"https://platform.twitter.com/widgets.js\" charset=\"utf-8\"></script>",
      "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

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

Example responses

STATUS: 200 OK

{
  "data": [
    {
      "css": null,
      "created_at": "2020-07-19T17:16:43.987+00:00",
      "description": null,
      "device_scale": 2.0,
      "google_fonts": null,
      "html": "<blockquote class=\"twitter-tweet\" style=\"width: 400px;\" data-dnt=\"true\">\n<p lang=\"en\" dir=\"ltr\"></p>\n\n<a href=\"\"></a>\n\n</blockquote> <script async src=\"https://platform.twitter.com/widgets.js\" charset=\"utf-8\"></script>",
      "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
  }
}

Need help?

We’re always looking to improve this documentation. Please send us an email: support@htmlcsstoimage.com. We respond fast.