The official Python client for the HTML/CSS to Image API. It provides typed request and response models, signed URL helpers, and an injectable HTTPX transport.
This README documents how the client behaves. The central API documentation is the source of truth for rendering features, parameter meanings, supported values, plan availability, and API limits. See the parameter reference when configuring a request.
pip install html-css-to-imagePython 3.10 or newer is required.
from html_css_to_image import (
CreateHtmlCssImageRequest,
HtmlCssToImageClient,
)
with HtmlCssToImageClient("your-api-id", "your-api-key") as client:
result = client.create_image(
CreateHtmlCssImageRequest(
html="<h1>Hello, world!</h1>",
css="h1 { color: royalblue; }",
)
)
if result.success:
print(result.id, result.url)
else:
print(result.status_code, result.error, result.message)Credentials are available in the HCTI dashboard. Keep the API key on a trusted server; never embed it in browser, desktop, or mobile application code.
Set HCTI_API_ID and HCTI_API_KEY, then use:
client = HtmlCssToImageClient.from_env()from_env() raises ValueError when either variable is missing.
Request fields use the API's snake_case names and are available as typed keyword arguments. None fields are omitted from JSON payloads; an explicit False is preserved for normal POST requests. Collection fields such as google_fonts and additional_header_origins accept lists or tuples of strings and reject a plain string rather than treating it as a sequence of characters.
| Request class | Use |
|---|---|
CreateHtmlCssImageRequest |
Create an image from HTML and CSS. |
CreateUrlImageRequest |
Capture a URL. |
CreateTemplatedImageRequest |
Render a saved template with values. |
All supported fields are documented by type hints and class docstrings. Their API behavior is documented in the parameter reference, URL screenshot guide, and template guide.
from html_css_to_image import (
CreateTemplatedImageRequest,
CreateUrlImageRequest,
)
url_result = client.create_image(
CreateUrlImageRequest(
url="https://example.com",
viewport_width=1200,
viewport_height=630,
transparent_background=True,
format="webp",
)
)
template_result = client.create_image(
CreateTemplatedImageRequest(
template_id="your-template-id",
template_version=3,
template_values={"title": "Hello from Python"},
)
)create_image() returns either CreateImageSuccessResponse or ApiErrorResponse, discriminated by result.success. API errors include the HTTP status_code. HTTP transport failures are raised by HTTPX rather than converted into API responses, while malformed successful responses raise UnexpectedResponseError instead of producing an incomplete success object.
result = client.create_image_batch(
variations=[
CreateHtmlCssImageRequest(css="h1 { color: crimson; }"),
CreateHtmlCssImageRequest(css="h1 { color: royalblue; }"),
],
default_options=CreateHtmlCssImageRequest(
html="<h1>Shared HTML</h1>",
viewport_width=600,
viewport_height=315,
),
)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.
Use create_recording with CreateHtmlCssRecordingRequest or CreateUrlRecordingRequest to record HTML/CSS or a public webpage as MP4, WebM, or GIF:
from html_css_to_image import (
CreateHtmlCssRecordingRequest,
CreateUrlRecordingRequest,
RecordingOutputOptions,
RecordingSimpleScrollAction,
)
result = client.create_recording(CreateUrlRecordingRequest(
url="https://example.com",
duration_ms=10000,
viewport_width=1280,
viewport_height=720,
actions=[RecordingSimpleScrollAction()],
output=RecordingOutputOptions(format="mp4"),
))
if result.success:
print(result.recording_url) # Embed or request directly; it waits until the recording is ready.
else:
print(result.error)
animation = client.create_recording(CreateHtmlCssRecordingRequest(
html="<h1>Hello</h1>",
css="@keyframes fade { from { opacity: 0; } to { opacity: 1; } } h1 { animation: fade 2s; }",
duration_ms=3000,
duration_mode="fixed",
output=RecordingOutputOptions(format="gif", scale=0.5),
))Both request types share browser settings, triggers, ordered actions, and output options. Actions and triggers are typed dataclasses, such as RecordingClickAction(selector="#start") and RecordingElementVisibleTrigger(selector="#ready"). For JavaScript actions, if_error=None fails on a script error; if_error=[] ignores errors. Empty branch lists are preserved in JSON.
deleted = client.delete_recording("recording-id")
batch_deleted = client.delete_recording_batch(["first-id", "second-id"])Deletion returns a success response when accepted. delete_recording_batch accepts a list or tuple of strings; an empty list returns a successful result without sending an HTTP request. All recording methods return the existing ApiErrorResponse on API errors and propagate HTTPX transport failures.
Optional settings use the API defaults. Recordings have no audio. Creation returns an ID, status URL, and recording URL. The recording_url can be embedded or requested directly; the request waits until the recording is ready, so checking status is optional.
status = client.fetch_recording_status("recording-id")
if status.success:
print(status.status)fetch_recording_status makes one request. HTTP 200 and 202 both return status information; ready, failed, and cancelled are terminal states. An error can describe an earlier, retryable attempt. A successful status fetch can report a failed recording. A status the client does not recognize, such as one added in a newer API version, is reported as unknown.
See the recording guide, actions reference, and trigger reference for the timeline, output options, and examples.
The signed URL helpers perform no network request. They create the exact query string, sign it with HMAC-SHA256 using the API key, and return a URL that can be shared without exposing that key.
template_url = client.generate_templated_image_url_from_values(
"your-template-id",
{"title": "Rendered on demand"},
template_version=2,
)
render_url = client.generate_create_and_render_url(
CreateUrlImageRequest(
url="https://example.com/card/42",
viewport_width=1200,
viewport_height=630,
)
)Use generate_templated_image_url() with a complete CreateTemplatedImageRequest, or generate_templated_image_url_from_values() when starting with separate values. Both methods accept render_options.
from html_css_to_image import CreateTemplatedImageRequest, RenderImageOptions
options = RenderImageOptions(format="webp", width=1200, height=630)
template_url = client.generate_templated_image_url(
CreateTemplatedImageRequest(
template_id="your-template-id",
template_values={"title": "Rendered on demand"},
),
render_options=options,
)Client behavior worth knowing:
- Render options are added before signing, so the signature covers the final query string.
- Template fields that collide with render-option query names are assigned the API's reserved
__ro_names automatically. - PDF layout options and deduplication options are omitted from create-and-render URLs because that endpoint does not support them.
- Custom URL headers become visible query parameters in a signed URL. Do not put secrets in them.
See the signed URL documentation for endpoint behavior and security considerations.
format accepts "png", "jpg", "webp", or "pdf" on creation requests and render options. image_url() builds a URL for an existing image without making a request:
url = client.image_url(
"image-id",
RenderImageOptions(format="jpg", dpi=96, width=1200),
)Cropping uses immutable value objects and explicit factory methods:
from html_css_to_image import (
RenderImageCrop,
RenderImageCropPosition,
RenderImageCropSpan,
)
crop = RenderImageCrop.rectangle(
horizontal=RenderImageCropSpan.between(
RenderImageCropPosition.percent(10),
RenderImageCropPosition.percent(90),
)
)
url = client.image_url("image-id", RenderImageOptions(crop=crop))The crop factories validate their inputs before generating a URL. Refer to the image URL and cropping documentation for transformation semantics and limits.
single = client.delete_image("image-id")
batch = client.delete_image_batch(["image-id-1", "image-id-2"])Every successful 2xx response maps to DeleteImageSuccessResponse. delete_image_batch accepts a list or tuple of strings; an empty list returns a successful result without sending an HTTP request. API errors use ApiErrorResponse, while network failures remain HTTPX exceptions.
The default transport is a persistent httpx.Client with a 30-second timeout and no automatic retries. Inject a client to configure timeouts, retries, proxies, certificates, connection limits, or test transports:
import httpx
http_client = httpx.Client(
transport=httpx.HTTPTransport(retries=2),
timeout=httpx.Timeout(90),
)
client = HtmlCssToImageClient(
"your-api-id",
"your-api-key",
http_client=http_client,
)An injected HTTP client remains caller-owned and is never closed or reconfigured by this package. Every API request includes HCTIPython/<version> as its User-Agent, including requests sent through an injected client. When the SDK creates the HTTP client, call close() or use HtmlCssToImageClient as a context manager.
Retry policy intentionally belongs to the application. HTTPX transport retries cover connection failures; status-code retries and backoff can be implemented around the injected transport or client call.
import httpx
from html_css_to_image import UnexpectedResponseError
try:
result = client.create_image(request)
except httpx.TimeoutException:
# Apply application-specific policy.
...
except httpx.NetworkError:
...
except UnexpectedResponseError as error:
# A 2xx response did not match the documented API shape.
print(error.status_code, error)
else:
if not result.success:
print(result.status_code, result.error, result.message)
for error in result.validation_errors or ():
print(error.path, error.message)| Method | Returns | Interaction |
|---|---|---|
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, unless the list is empty. |
image_url(image_id, render_options=None) |
str |
Builds an existing-image URL locally. |
generate_templated_image_url(request, render_options=None) |
str |
Builds and signs a template URL from a request locally. |
generate_templated_image_url_from_values(...) |
str |
Builds and signs a template URL from separate values locally. |
generate_create_and_render_url(...) |
str |
Builds and signs a URL screenshot locally. |
create_recording(request) |
CreateRecordingResponse |
Sends POST /v1/recording. |
fetch_recording_status(recording_id) |
RecordingStatusResponse |
Sends GET /v1/recordings/{id}/status. |
delete_recording(recording_id) |
DeleteRecordingResponse |
Sends DELETE /v1/recordings/{id}. |
delete_recording_batch(recording_ids) |
DeleteRecordingResponse |
Sends DELETE /v1/recordings/batch, unless the list is empty. |
close() |
None |
Closes only an SDK-owned HTTP client. |
The package exports typed request, response, PDF, and render/crop models from html_css_to_image. Public classes, constructor parameters, attributes, and methods include docstrings for IDE help and generated API documentation.
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
ruff check .
mypy
python -m unittest discover -s tests
python -m buildMIT
Create images from one or more templates with shared defaults and ordered variations:
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 for plan limits and examples.