HTML/CSS to Image Image Generation API
The Image Generation API from HTML/CSS to Image — 5 operation(s) for image generation.
OpenAPI Specification
openapi: 3.0.1
info:
title: HTML/CSS to Image Image Generation API
description: REST API for rendering HTML, CSS, and JavaScript (or a URL) into high quality images (PNG, JPG, WebP, PDF). Supports single and batch image creation, image retrieval with resize/crop options, reusable templates with variable substitution, and HMAC-signed URLs for GET-based templated image generation. Authentication is HTTP Basic using your User ID as the username and your API Key as the password.
termsOfService: https://htmlcsstoimage.com/terms
contact:
name: HTML/CSS to Image Support
email: support@htmlcsstoimage.com
url: https://htmlcsstoimage.com
version: '1.0'
servers:
- url: https://hcti.io/v1
security:
- basicAuth: []
tags:
- name: Image Generation
paths:
/image:
post:
operationId: createImage
tags:
- Image Generation
summary: Create an image from HTML/CSS or a URL.
description: Render HTML, CSS, and JavaScript into an image and return its ID and a permanent hosted URL. Provide either `html` or `url` (not both).
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateImageRequest'
responses:
'200':
description: The created image, with its ID and permanent URL.
content:
application/json:
schema:
$ref: '#/components/schemas/Image'
'401':
description: Missing or invalid authentication.
'422':
description: Validation error (e.g. neither or both of html and url provided).
/image/batch:
post:
operationId: createImageBatch
tags:
- Image Generation
summary: Create multiple images in a single request.
description: Render up to 25 image variations in one request. Shared options are provided in `default_options` and merged into each `variations` entry.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateImageBatchRequest'
responses:
'200':
description: The created images.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Image'
'401':
description: Missing or invalid authentication.
delete:
operationId: deleteImageBatch
tags:
- Image Generation
summary: Delete multiple images in a single request.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- ids
properties:
ids:
type: array
items:
type: string
description: Array of image IDs to delete.
responses:
'202':
description: Accepted; the images will be deleted.
'401':
description: Missing or invalid authentication.
/image/{image_id}:
get:
operationId: getImage
tags:
- Image Generation
summary: Retrieve a rendered image.
description: Fetch a previously created image. Append a format extension (.png, .jpg, .webp, .pdf) to control the output format; PNG is the default. Query parameters allow on-the-fly resize and crop.
parameters:
- name: image_id
in: path
required: true
schema:
type: string
- name: width
in: query
schema:
type: integer
description: Resize width in pixels.
- name: height
in: query
schema:
type: integer
description: Resize height in pixels.
- name: dpi
in: query
schema:
type: integer
description: Output DPI.
- name: aspect_ratio
in: query
schema:
type: string
description: Aspect ratio to apply, e.g. "16:9".
- name: crop_width
in: query
schema:
type: integer
- name: crop_height
in: query
schema:
type: integer
- name: dl
in: query
schema:
type: integer
description: Set to 1 to force a download response.
responses:
'200':
description: The rendered image binary.
content:
image/png:
schema:
type: string
format: binary
image/jpeg:
schema:
type: string
format: binary
image/webp:
schema:
type: string
format: binary
application/pdf:
schema:
type: string
format: binary
'404':
description: Image not found.
delete:
operationId: deleteImage
tags:
- Image Generation
summary: Delete an image.
parameters:
- name: image_id
in: path
required: true
schema:
type: string
responses:
'202':
description: Accepted; the image will be deleted.
'401':
description: Missing or invalid authentication.
/images:
get:
operationId: listImages
tags:
- Image Generation
summary: List images.
description: Return a paginated list of images created on the account.
parameters:
- name: count
in: query
schema:
type: integer
maximum: 50
description: Number of images to return (max 50).
- name: page_token
in: query
schema:
type: string
description: Pagination token returned by a previous call.
responses:
'200':
description: A paginated list of images.
content:
application/json:
schema:
$ref: '#/components/schemas/ImageList'
'401':
description: Missing or invalid authentication.
/usage:
get:
operationId: getUsage
tags:
- Image Generation
summary: Check account usage.
description: Return hourly, daily, and monthly image usage statistics plus billing period totals for the account.
responses:
'200':
description: Account usage statistics.
content:
application/json:
schema:
$ref: '#/components/schemas/Usage'
'401':
description: Missing or invalid authentication.
components:
schemas:
ImageList:
type: object
properties:
images:
type: array
items:
$ref: '#/components/schemas/Image'
page_token:
type: string
description: Token to retrieve the next page of results.
Image:
type: object
properties:
url:
type: string
description: Permanent hosted URL of the rendered image.
viewBox:
type: string
description: The view box used to render the image.
CreateImageRequest:
type: object
description: One of `html` or `url` is required (not both).
properties:
html:
type: string
description: The HTML markup to render.
url:
type: string
description: A URL to render instead of inline HTML.
css:
type: string
description: CSS to apply to the HTML.
google_fonts:
type: string
description: Comma-separated Google Fonts to load, e.g. "Roboto".
selector:
type: string
description: CSS selector of the element to capture.
ms_delay:
type: integer
description: Milliseconds to wait before capturing.
max_wait_ms:
type: integer
description: Maximum milliseconds to wait for the page.
device_scale:
type: number
description: Device scale factor for higher resolution output.
render_when_ready:
type: boolean
description: Wait for a window.renderWhenReady() signal before capturing.
full_screen:
type: boolean
description: Capture the full screen rather than the content size.
block_consent_banners:
type: boolean
description: Attempt to hide cookie/consent banners.
viewport_width:
type: integer
viewport_height:
type: integer
viewport_mobile:
type: boolean
viewport_landscape:
type: boolean
viewport_touch:
type: boolean
color_scheme:
type: string
description: Emulated color scheme, e.g. "light" or "dark".
timezone:
type: string
disable_twemoji:
type: boolean
proxy_id:
type: string
Usage:
type: object
properties:
hourly:
type: integer
daily:
type: integer
monthly:
type: integer
billing_period_total:
type: integer
CreateImageBatchRequest:
type: object
required:
- variations
properties:
default_options:
$ref: '#/components/schemas/CreateImageRequest'
variations:
type: array
maxItems: 25
items:
$ref: '#/components/schemas/CreateImageRequest'
securitySchemes:
basicAuth:
type: http
scheme: basic
description: HTTP Basic authentication using your User ID as the username and your API Key as the password, both from the HTML/CSS to Image dashboard.