format

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

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.

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.

{
  "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": "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.

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

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"
    }
  ]
}

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.

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