Create Templated Images in Batches

We've added batch creation for templated images. Send one request to POST /v1/image/batch/templated with shared defaults and a list of variations, and get back an image URL for each variation. A batch can use one template or several, including templates built in the visual Template Editor.

If you're generating social cards for a set of articles, product previews for a catalog, or personalized event cards, much of the request is the same each time. The template stays the same. Your brand values stay the same. The title, product, or recipient changes.

Now you can put the common values in one place and send the changes for each image together.

Shared defaults and individual variations

The request has two parts: default_options for values shared across the batch, and variations for each image you want to create.

Here's a batch of three article cards. Replace t-article-card with your saved template ID, and use variable names that match your template:

curl -X POST 'https://hcti.io/v1/image/batch/templated' \
  -u "$HCTI_API_ID:$HCTI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "default_options": {
      "template_id": "t-article-card",
      "format": "webp",
      "template_values": {
        "site_name": "Acme Engineering",
        "author": "Alex Morgan"
      }
    },
    "variations": [
      { "template_values": { "title": "Building our first API" } },
      { "template_values": { "title": "How we test our integrations" } },
      {
        "template_values": {
          "title": "A guide to our design system",
          "author": "Sam Lee"
        }
      }
    ]
  }'

Every image inherits the template, output format, and site name. The first two also inherit the author. The third supplies its own author.

The response contains an images array in the same order as your variations:

{
  "images": [
    { "id": "image-1", "url": "https://hcti.io/v1/image/image-1.webp" },
    { "id": "image-2", "url": "https://hcti.io/v1/image/image-2.webp" },
    { "id": "image-3", "url": "https://hcti.io/v1/image/image-3.webp" }
  ]
}

These are illustrative IDs, but the response shape is the same. You can match each result to its source article by position and save the returned URL with that record.

Structured values inherit by key

Templates can accept structured data, so sharing defaults needs to work inside objects too.

Suppose your defaults contain a brand object:

{
  "brand": {
    "name": "Acme",
    "color": "#2563eb"
  },
  "tags": ["New"],
  "subtitle": "Available now"
}

A variation can change the color while keeping the name:

{
  "brand": { "color": "#dc2626" },
  "tags": ["Sale"],
  "subtitle": null
}

Objects merge recursively by key. This variation keeps brand.name as Acme and changes brand.color to red. Arrays replace the entire default array, so its tags become just ["Sale"]. Scalar values and explicit null values also replace the corresponding defaults; subtitle becomes null.

That gives you a way to share nested settings while keeping each variation small. Use null only where your template allows it: required variables still have to satisfy the template's validation rules.

Multiple templates in one batch

You can supply template_id in any variation. A batch might use an article card for most entries and a different layout for an announcement. Shared template values still apply across both templates.

Version selection follows a specific rule. When a variation inherits the default template ID, it also inherits the default version. When it supplies a template ID, it resets that inherited version, even if the ID is the same.

For example, with template_id: "t-article-card" and template_version: 3 in your defaults:

Pin versions when you want a batch to use a particular saved design. Omit them when you want the latest version.

SDK support

The SDK updates for this release add dedicated templated batch methods in TypeScript, .NET, Go, Python, PHP, and Ruby. The typed clients have a TemplatedBatchImageOptions model with optional fields, so a variation can inherit its template and supply just the values that change.

In TypeScript, the same article batch looks like this:

import {
  HtmlCssToImageClient,
  TemplatedBatchImageOptions
} from '@html-css-to-image/client';

const client = HtmlCssToImageClient.fromEnv();

const result = await client.createTemplatedImageBatch([
  new TemplatedBatchImageOptions({
    template_values: {title: 'Building our first API'}
  }),
  new TemplatedBatchImageOptions({
    template_values: {title: 'How we test our integrations'}
  }),
  new TemplatedBatchImageOptions({
    template_values: {
      title: 'A guide to our design system',
      author: 'Sam Lee'
    }
  })
], new TemplatedBatchImageOptions({
  template_id: 't-article-card',
  format: 'webp',
  template_values: {
    site_name: 'Acme Engineering',
    author: 'Alex Morgan'
  }
}));

if (result.success) {
  for (const image of result.images) {
    console.log(image.url);
  }
} else {
  throw new Error(result.message);
}

The clients leave template resolution and value merging to the API. The new methods use the existing batch response types and error handling.

Batch templated creation is also exposed through MCP as create_batch_templated_images, so connected assistants can create a set of template variations together.

Try a template batch

Use an API key with images:create permission and a plan that supports batches. Send a nonempty list of variations within your plan's batch limit. Each entry must resolve to a template in your organization, and its merged values must be nonempty and satisfy that template's required variables.

Identical template images reuse existing assets. You still get one result per variation, so repeated entries can return the same image ID.

Start with a saved template and a few records from your application. The batch templated image API reference covers the request fields, inheritance rules, and response format.