Using format

Choose the file extension included in the image URL returned by the API.

How it works

Set format in the request body sent to POST /v1/image. The API appends the selected format to the image URL in its response.

The parameter only changes the URL returned by the creation request. It does not change the stored image definition or lock the image to one format. You can request the same image ID later with a different supported extension.

The parameter works with:

• HTML/CSS image requests.
• URL screenshot requests.
• Images created from saved templates.
• Image batches, as either a variation or a default option.

When format is omitted, the API returns its default extensionless URL, which serves the image as PNG.

Format values are case-insensitive. The examples use lowercase values as the canonical form.

How files are handled

Raster images are rendered and stored as PNGs. The extension in the URL determines how the image is served:

• A .png URL serves the stored PNG.
• A .jpg or .webp URL converts the stored PNG to that format.

PDFs are handled separately. When a .pdf URL is requested, the API creates and saves a separate PDF render rather than converting the stored PNG.

Values

HTML/CSS example

{
  "html": "<h1>Product launch</h1>",
  "css": "h1 { color: navy; }",
  "format": "webp"
}

The response URL includes the requested extension:

{
  "id": "image-id",
  "url": "https://hcti.io/v1/image/image-id.webp"
}

URL screenshot with a PDF URL

{
  "url": "https://example.com/report",
  "format": "pdf",
  "pdf_options": {
    "page_width": "210mm",
    "page_height": "297mm",
    "margins": ["20mm", "15mm", "20mm", "15mm"],
    "print_background": true
  }
}

The creation response includes a URL ending in .pdf. The PDF is rendered and saved separately when that URL is requested.

Saved template image

{
  "template_id": "template-id",
  "template_values": {
    "title": "Weekly summary"
  },
  "format": "jpg"
}

Image batch

Set a default format for the batch or override it on an individual variation:

{
  "default_options": {
    "html": "<h1>Default content</h1>",
    "format": "webp"
  },
  "variations": [
    {
      "html": "<h1>WebP image</h1>"
    },
    {
      "html": "<h1>PNG image</h1>",
      "format": "png"
    }
  ]
}

Signed URLs

For signed create-and-render URLs, the format is a path component after the token rather than a request-body or query-string parameter:

https://hcti.io/v1/image/create-and-render/:api_id/:token/webp?url=...
https://hcti.io/v1/image/:template_id/:token/pdf?title=...

See the signed image URL guide for URL construction and HMAC details.

Official clients

For choosing a format and retrieving an existing image with a different extension, see the file formats guide.

Need help?

Talk to a human. Please email us support@htmlcsstoimage.com with any questions and we’ll gladly help you get started.