add templated batch create support

Author: jsneedles

README.md

@@ -101,7 +101,7 @@ result = client.create_image_batch(
 )
 ```
 
-Only HTML/CSS and URL requests can be batched. Empty `html` or `url` values in variations are omitted so they can inherit from `default_options`. An empty variation list returns a successful empty result without sending an HTTP request. Options unsupported by the batch API, such as `dedupe_duration_s`, are not serialized. See the [batch API documentation](https://docs.htmlcsstoimage.com/getting-started/using-the-api/#batch-image-creation).
+`create_image_batch` accepts HTML/CSS and URL requests; use `create_templated_image_batch` for templates. Empty `html` or `url` values in variations are omitted so they can inherit from `default_options`. An empty variation list returns a successful empty result without sending an HTTP request. Options unsupported by the batch API, such as `dedupe_duration_s`, are not serialized. See the [batch API documentation](https://docs.htmlcsstoimage.com/getting-started/using-the-api/#batch-image-creation).
 
 ## Signed URLs
 
@@ -243,6 +243,7 @@ else:
 | `from_env(...)` | `HtmlCssToImageClient` | Reads credentials from the environment. |
 | `create_image(request)` | `CreateImageResponse` | Sends `POST /v1/image`. |
 | `create_image_batch(variations, default_options=None)` | `CreateImageBatchResponse` | Sends `POST /v1/image/batch`, unless the list is empty. |
+| `create_templated_image_batch(variations, default_options=None)` | `CreateImageBatchResponse` | Sends `POST /v1/image/batch/templated`, unless the list is empty. |
 | `delete_image(image_id)` | `DeleteImageResponse` | Sends `DELETE /v1/image/{id}`. |
 | `delete_image_batch(image_ids)` | `DeleteImageResponse` | Sends `DELETE /v1/image/batch`. |
 | `image_url(image_id, render_options=None)` | `str` | Builds an existing-image URL locally. |
@@ -268,3 +269,23 @@ python -m build
 ## License
 
 MIT
+
+## Templated image batches
+
+Create images from one or more templates with shared defaults and ordered variations:
+
+```python
+from html_css_to_image import TemplatedBatchImageOptions
+
+result = client.create_templated_image_batch(
+    [
+        TemplatedBatchImageOptions(template_values={"title": "First"}),
+        TemplatedBatchImageOptions(template_id="t-other", template_values={"title": "Second"}),
+    ],
+    TemplatedBatchImageOptions(template_id="t-card", template_version=3, format="webp"),
+)
+```
+
+Omitted fields inherit defaults. Supplying a template ID resets the inherited version; omit its version to use latest. Template value objects merge recursively on the API; arrays, scalars, and explicit null values replace defaults. Results preserve input order and identical images reuse existing assets. Each merged values object must be nonempty and satisfy its template's required variables.
+
+See the [API reference](https://docs.htmlcsstoimage.com/getting-started/using-the-api/#batch-templated-image-creation) for plan limits and examples.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "html-css-to-image"
-version = "0.3.0"
+version = "0.4.0"
 description = "Official Python client for the HTML/CSS to Image API"
 readme = "README.md"
 requires-python = ">=3.10"

src/html_css_to_image/__init__.py

@@ -37,6 +37,7 @@
     RequestOverride,
     RequestOverrideAction,
     RequestOverrideResourceType,
+    TemplatedBatchImageOptions,
     ValidationError,
 )
 
@@ -52,6 +53,7 @@
     "CreateImageResponse",
     "CreateImageSuccessResponse",
     "CreateTemplatedImageRequest",
+    "TemplatedBatchImageOptions",
     "CreateUrlImageRequest",
     "DeleteImageResponse",
     "DeleteImageSuccessResponse",

src/html_css_to_image/_request_mapper.py

@@ -16,6 +16,7 @@
     PDFValueInput,
     PDFValueWithUnits,
     RequestOverride,
+    TemplatedBatchImageOptions,
 )
 
 
@@ -58,6 +59,22 @@ def map_batch_request(
             raise TypeError("Batch requests must contain HTML/CSS or URL requests")
         return cls.map_request(request, in_batch=True)
 
+    @classmethod
+    def map_templated_batch_options(
+        cls, request: TemplatedBatchImageOptions,
+    ) -> dict[str, Any]:
+        if not isinstance(request, TemplatedBatchImageOptions):
+            raise TypeError("Template batches require TemplatedBatchImageOptions")
+        return cls.without_none({
+            "template_id": request.template_id,
+            "template_version": request.template_version,
+            "template_values": (
+                dict(request.template_values)
+                if request.template_values is not None else None
+            ),
+            "format": request.format,
+        })
+
     @classmethod
     def common_payload(
         cls,

src/html_css_to_image/client.py

@@ -23,6 +23,7 @@
     CreateUrlImageRequest,
     DeleteImageResponse,
     RenderImageOptions,
+    TemplatedBatchImageOptions,
 )
 
 _ClientT = TypeVar("_ClientT", bound="HtmlCssToImageClient")
@@ -165,6 +166,31 @@ def create_image_batch(
         response = self._transport.post("/v1/image/batch", payload)
         return ResponseMapper.map_batch_response(response)
 
+    def create_templated_image_batch(
+        self,
+        variations: Sequence[TemplatedBatchImageOptions],
+        default_options: TemplatedBatchImageOptions | None = None,
+    ) -> CreateImageBatchResponse:
+        """Create a template batch with shared defaults and ordered results.
+
+        Merging and template resolution happen on the API. An empty variation
+        list succeeds locally. API errors use the existing batch response type.
+        """
+        if not variations:
+            return CreateImageBatchSuccessResponse(images=())
+        payload: dict[str, Any] = {
+            "variations": [
+                RequestMapper.map_templated_batch_options(item)
+                for item in variations
+            ],
+        }
+        if default_options is not None:
+            payload["default_options"] = RequestMapper.map_templated_batch_options(
+                default_options
+            )
+        response = self._transport.post("/v1/image/batch/templated", payload)
+        return ResponseMapper.map_batch_response(response)
+
     def delete_image(self, image_id: str) -> DeleteImageResponse:
         """Delete one generated image.
 

src/html_css_to_image/models.py

@@ -269,6 +269,21 @@ class CreateTemplatedImageRequest:
     format: ImageFormat | None = None
 
 
+@dataclass(slots=True, kw_only=True)
+class TemplatedBatchImageOptions:
+    """Shared defaults or one template batch variation.
+
+    Supplying template_id resets the inherited version. Objects in
+    template_values merge recursively; arrays, scalars and explicit None
+    values replace defaults. Omitted fields inherit defaults.
+    """
+
+    template_id: str | None = None
+    template_version: int | None = None
+    template_values: Mapping[str, Any] | None = None
+    format: ImageFormat | None = None
+
+
 CreateImageRequest: TypeAlias = (
     CreateHtmlCssImageRequest | CreateUrlImageRequest | CreateTemplatedImageRequest
 )

tests/test_client.py

@@ -14,6 +14,7 @@
     ApiErrorResponse,
     CreateHtmlCssImageRequest,
     CreateTemplatedImageRequest,
+    TemplatedBatchImageOptions,
     CreateUrlImageRequest,
     DeleteImageSuccessResponse,
     HtmlCssToImageClient,
@@ -48,6 +49,57 @@ def make_client(self, handler):
             http_client=http_client,
         )
 
+    def test_template_batch_preserves_inheritance_and_nested_null(self):
+        defaults = TemplatedBatchImageOptions(
+            template_id="t-card", template_version=3, format="webp",
+            template_values={"brand": {"name": "Acme", "color": "red"}},
+        )
+        variation = TemplatedBatchImageOptions(
+            template_id="t-other",
+            template_values={"brand": {"color": None}, "tags": [], "active": False},
+        )
+
+        def handler(request):
+            self.assertEqual(str(request.url), "https://hcti.io/v1/image/batch/templated")
+            self.assertEqual(request.method, "POST")
+            self.assertEqual(json.loads(request.content), {
+                "default_options": {
+                    "template_id": "t-card", "template_version": 3, "format": "webp",
+                    "template_values": {"brand": {"name": "Acme", "color": "red"}},
+                },
+                "variations": [{}, {
+                    "template_id": "t-other",
+                    "template_values": {"brand": {"color": None}, "tags": [], "active": False},
+                }],
+            })
+            return httpx.Response(200, json={"images": [
+                {"id": "two", "url": "two"}, {"id": "one", "url": "one"},
+            ]})
+
+        client = self.make_client(handler)
+        result = client.create_templated_image_batch([TemplatedBatchImageOptions(), variation], defaults)
+        self.assertTrue(result.success)
+        self.assertEqual([image.id for image in result.images], ["two", "one"])
+        self.assertEqual(variation.template_version, None)
+        self.assertEqual(defaults.template_values["brand"]["color"], "red")
+
+    def test_template_batch_empty_and_error(self):
+        calls = []
+
+        def handler(request):
+            calls.append(request)
+            self.assertNotIn("default_options", json.loads(request.content))
+            return httpx.Response(400, json={"error": "Bad Request", "message": "Invalid template"})
+
+        client = self.make_client(handler)
+        self.assertTrue(client.create_templated_image_batch([]).success)
+        self.assertEqual(calls, [])
+        result = client.create_templated_image_batch([TemplatedBatchImageOptions(template_id="t-missing")])
+        self.assertFalse(result.success)
+        self.assertEqual(result.message, "Invalid template")
+        with self.assertRaises(TypeError):
+            client.create_templated_image_batch([CreateUrlImageRequest(url="https://example.com")])
+
     def test_request_overrides_serialize_enums_and_stay_out_of_signed_urls(self):
         rules = [RequestOverride(
             action=RequestOverrideAction.BLOCK,