Link Search Menu Expand Document

Image Templates

Create re-usable templates to make image generation easy.

Get an API Key


Table of contents


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",
}
Example of an image template use for converting html to an image

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.


Back to top

Built with extensive integration tests and serious care for developer happiness.
© 2018-2024 Code Happy, LLC.

Page last modified: Apr 9 2024 at 11:04 PM.

Edit this page on GitHub.