Image Templates

Create re-usable templates to make image generation easy.

Table of contents

What are Templates?
Creating a Template
Editing a Template
- Parameters
- Additional parameters
Creating an image with a template
- Parameters
Listing your templates
- Example responses
Listing your template versions
- Example responses
Need help?

What are Templates?

A template allows you to define HTML that includes variables to be substituted at the time of image creation.

Handlebars variables

Templates support handlebars variables. This allows you to place {{title_text}} in your HTML. Then have that replaced with any value you’d like while creating your image.

Common usecases

Define a reusable template, then pass variables to it to generate unique images.
Create images using signed urls in a GET request (no need to POST and store the URL).
Useful for social sharing images. Such as og:image or twitter:image.

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.

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

Required params

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.

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.
device_scale	`Double`	This adjusts the pixel ratio for the screenshot. Minimum: `1`, Maximum: `3`.
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.
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.

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

Plan Limits

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 (`<div>Your content</div>`) 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`

Required params

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.

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.
device_scale	`Double`	This adjusts the pixel ratio for the screenshot. Minimum: `1`, Maximum: `3`.
render_when_ready	`Boolean`	Set to true to control when the image is generated. Call `ScreenshotReady()` from JavaScript to generate the image. 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.
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.

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

Template Versions

When you create an image using a template_id, it will automatically utilize 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`	These are the variables that will be substituted in your template’s HTML.

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,
      "updated_at": "2020-07-19T17:16:43.987+00:00",
      "version": 1595179003987,
      "viewport_height": null,
      "viewport_width": null
    }
  ],
  "pagination": {
    "next_page_start": null
  }
}

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,
      "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.