---
title: "Create Templated Images in Batches"
description: "Generate multiple images from saved templates in one API request, with shared defaults and per-image variations."
published: "2026-10-02"
author: "Jeffrey Needles"
canonical: "https://htmlcsstoimage.com/blog/batch-templated-images"
---


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:

```bash
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:

```json
{
  "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:

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

A variation can change the color while keeping the name:

```json
{
  "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:

| Variation | Template version used |
|:----------|:----------------------|
| Omits both template fields | Version 3 of `t-article-card` |
| Sets only `template_version: 4` | Version 4 of `t-article-card` |
| Sets only `template_id: "t-announcement"` | Latest version of `t-announcement` |
| Sets `template_id: "t-announcement"` and `template_version: 2` | Version 2 of `t-announcement` |

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:

```typescript
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](https://docs.htmlcsstoimage.com/getting-started/templates/) and a few records from your application. The [batch templated image API reference](https://docs.htmlcsstoimage.com/getting-started/using-the-api/#batch-templated-image-creation) covers the request fields, inheritance rules, and response format.