Skip to content

Commit aeb9d5c

Browse files
jsneedlesjsneedles
committed
add format docs
1 parent 26e085d commit aeb9d5c

6 files changed

Lines changed: 214 additions & 6 deletions

File tree

‎_data/parameters.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,14 @@
103103
"additional": true,
104104
"support": { "html": true, "url": true, "templates": true, "og_config": false, "create_and_render": true }
105105
},
106+
{
107+
"name": "format",
108+
"description": "Choose the file extension in the initially returned image URL: `png`, `jpg`, `webp`, or `pdf`.",
109+
"type": "String",
110+
"link": "/parameters/format/",
111+
"additional": true,
112+
"support": { "html": true, "url": true, "templates": false, "og_config": false, "create_and_render": false }
113+
},
106114
{
107115
"name": "full_screen",
108116
"description": "Generate an image of the entire height of a URL page.",

‎changelog.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,29 @@ Always improving. Updates to HTML/CSS to Image are posted here.
1616

1717
If you have feature requests, please send them to us: support@htmlcsstoimage.com.
1818

19+
### Choose the returned file format in image creation requests
20+
August 27, 2026
21+
{: .text-delta}
22+
23+
Image creation requests can now include `format` in the request body. This parameter selects the file extension included in the returned URL; it does not change the stored image definition.
24+
25+
- Set `format` to `png`, `jpg`, `webp`, or `pdf` for an HTML/CSS image, URL screenshot, saved-template image, or image batch.
26+
- Raster images are rendered and stored as PNGs. JPG and WebP URLs convert that stored PNG when requested.
27+
- PDFs are rendered and saved separately when a PDF URL is requested.
28+
- The same image ID can still be requested later with a different supported extension.
29+
- Batch requests can set `format` in `default_options` or override it in an individual variation.
30+
- When omitted, the API returns its default extensionless URL, which renders as PNG.
31+
32+
The official clients now expose the body parameter and apply it to generated signed URL paths:
33+
34+
- [.NET client v0.12.0](https://github.com/htmlcsstoimage/dotnet-client) with `RenderImageFormat.PDF` support.
35+
- [TypeScript client v0.9.0](https://github.com/htmlcsstoimage/ts-client).
36+
- [Ruby client v0.3.0](https://github.com/htmlcsstoimage/ruby-client).
37+
38+
[Read the `format` parameter documentation](/parameters/format/) or compare output types in the [file formats guide](/guides/styling/file-formats/).
39+
40+
<hr>
41+
1942
### Ruby client v0.2.0
2043
August 21, 2026
2144
{: .text-delta}

‎getting-started/using-the-api.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,8 @@ The API supports `jpg`, `png`, `webp`, and `pdf`. If no file extension is passed
119119
| webp | `https://hcti.io/v1/image/a3ab2ab2-906e-4b5c-a88d-41a1c3f3779e.webp` |
120120
| pdf | `https://hcti.io/v1/image/a3ab2ab2-906e-4b5c-a88d-41a1c3f3779e.pdf` |
121121

122+
{% include hint.md title="Tip" text="You can include the desired format as a parameter when creating your image. See [here](/parameters/format/) for more details." %}
123+
122124
{% include hint.md title="PNG by default" text="The API returns `png` by default. If no extension is on the URL, a png will be generated." %}
123125

124126
### Query parameters

‎guides/styling/file-formats.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,8 @@ To specify a format, add the appropriate file extension to your image URL:
3535
| WebP | `https://hcti.io/v1/image/abc123.webp` | Modern web applications, optimal compression |
3636
| PDF | `https://hcti.io/v1/image/abc123.pdf` | Documents, invoices, printable content |
3737

38+
{% include hint.md title="Tip" text="You can include the desired format as a parameter when creating your image. See [here](/parameters/format/) for more details." %}
39+
3840
{% include hint.md title="Default Format" text="If no extension is specified, the API will return a PNG image." %}
3941

4042
## Format Characteristics
@@ -125,4 +127,3 @@ Benefits:
125127

126128
{% include code_footer.md version=1 %}
127129

128-

‎parameters/format.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
layout: page
3+
title: format
4+
permalink: /parameters/format/
5+
parent: Parameters
6+
nav_order: 25
7+
description: >-
8+
Choose the file extension included in the URL returned by a create image request.
9+
---
10+
11+
# Using format
12+
{: .no_toc }
13+
{: .fs-9 }
14+
15+
Choose the file extension included in the image URL returned by the API.
16+
{: .fs-6 .fw-300 }
17+
18+
<hr>
19+
20+
## How it works
21+
22+
Set `format` in the request body sent to `POST /v1/image`. The API appends the selected format to the image URL in its response.
23+
24+
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.
25+
26+
The parameter works with:
27+
28+
- HTML/CSS image requests.
29+
- URL screenshot requests.
30+
- Images created from saved templates.
31+
- Image batches, as either a variation or a default option.
32+
33+
When `format` is omitted, the API returns its default extensionless URL, which serves the image as PNG.
34+
35+
Format values are case-insensitive. The examples use lowercase values as the canonical form.
36+
37+
## How files are handled
38+
39+
Raster images are rendered and stored as PNGs. The extension in the URL determines how the image is served:
40+
41+
- A `.png` URL serves the stored PNG.
42+
- A `.jpg` or `.webp` URL converts the stored PNG to that format.
43+
44+
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.
45+
46+
## Values
47+
48+
| Value | Description |
49+
|:------|:------------|
50+
| `png` | Return a URL ending in `.png`. The URL serves the stored PNG image. |
51+
| `jpg` | Return a URL ending in `.jpg`. The stored PNG is converted to JPG when requested. |
52+
| `webp` | Return a URL ending in `.webp`. The stored PNG is converted to WebP when requested. |
53+
| `pdf` | Return a URL ending in `.pdf`. The PDF is rendered and saved separately when requested. Use [`pdf_options`](/parameters/pdf_options/) to configure it. |
54+
55+
## HTML/CSS example
56+
57+
```json
58+
{
59+
"html": "<h1>Product launch</h1>",
60+
"css": "h1 { color: navy; }",
61+
"format": "webp"
62+
}
63+
```
64+
65+
The response URL includes the requested extension:
66+
67+
```json
68+
{
69+
"id": "image-id",
70+
"url": "https://hcti.io/v1/image/image-id.webp"
71+
}
72+
```
73+
74+
## URL screenshot with a PDF URL
75+
76+
```json
77+
{
78+
"url": "https://example.com/report",
79+
"format": "pdf",
80+
"pdf_options": {
81+
"page_width": "210mm",
82+
"page_height": "297mm",
83+
"margins": ["20mm", "15mm", "20mm", "15mm"],
84+
"print_background": true
85+
}
86+
}
87+
```
88+
89+
The creation response includes a URL ending in `.pdf`. The PDF is rendered and saved separately when that URL is requested.
90+
91+
## Saved template image
92+
93+
```json
94+
{
95+
"template_id": "template-id",
96+
"template_values": {
97+
"title": "Weekly summary"
98+
},
99+
"format": "jpg"
100+
}
101+
```
102+
103+
## Image batch
104+
105+
Set a default format for the batch or override it on an individual variation:
106+
107+
```json
108+
{
109+
"default_options": {
110+
"html": "<h1>Default content</h1>",
111+
"format": "webp"
112+
},
113+
"variations": [
114+
{
115+
"html": "<h1>WebP image</h1>"
116+
},
117+
{
118+
"html": "<h1>PNG image</h1>",
119+
"format": "png"
120+
}
121+
]
122+
}
123+
```
124+
125+
## Signed URLs
126+
127+
For signed create-and-render URLs, the format is a path component after the token rather than a request-body or query-string parameter:
128+
129+
```text
130+
https://hcti.io/v1/image/create-and-render/:api_id/:token/webp?url=...
131+
https://hcti.io/v1/image/:template_id/:token/pdf?title=...
132+
```
133+
134+
See the [signed image URL guide](/getting-started/create-and-render/) for URL construction and HMAC details.
135+
136+
## Official clients
137+
138+
| Client | Version | Example |
139+
|:-------|:--------|:--------|
140+
| [.NET](/example-code/c/) | `0.12.0` | `Format = RenderImageFormat.PDF` |
141+
| [TypeScript](/example-code/typescript/) | `0.9.0` | `format: 'pdf'` |
142+
| [Ruby](/example-code/ruby/) | `0.3.0` | `format: "pdf"` |
143+
144+
For choosing a format and retrieving an existing image with a different extension, see the [file formats guide](/guides/styling/file-formats/).
145+
146+
{% include code_footer.md version=1 %}

‎parameters/pdf_options.md‎

Lines changed: 33 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -21,11 +21,12 @@ Generate customized PDF documents from HTML
2121

2222
When generating PDFs, use the `pdf_options` parameter to control page size, margins, scaling, and background printing.
2323

24-
To get a PDF instead of an image, add `.pdf` to your image URL:
24+
You can use either of these flows:
2525

26-
```
27-
https://hcti.io/v1/image/abc123.pdf
28-
```
26+
- **Create an image, then render it as a PDF:** Create the image normally, then add `.pdf` to the returned image URL.
27+
- **Render it as a PDF directly:** Include [`format: "pdf"`](/parameters/format/) when creating the image. The URL in the creation response will already end in `.pdf`.
28+
29+
In both cases, the PDF is rendered and saved separately when its URL is requested. The `format` parameter only controls the URL returned by the creation request; it does not change the stored image definition.
2930

3031
## Parameters
3132

@@ -50,7 +51,7 @@ The `pdf_options` object accepts the following properties:
5051

5152
## Example usage
5253

53-
### Basic PDF generation
54+
### Create an image, then render it as a PDF
5455

5556
Create an image and access it as PDF:
5657

@@ -67,6 +68,33 @@ Then append `.pdf` to the returned URL:
6768
https://hcti.io/v1/image/abc123.pdf
6869
```
6970

71+
### Return a PDF URL directly
72+
73+
Set `format` to `pdf` when creating the image:
74+
75+
```bash
76+
curl -X POST https://hcti.io/v1/image -u 'UserID:APIKey' \
77+
-H "Content-Type: application/json" \
78+
-d '{
79+
"html": "<h1>Invoice #1234</h1><p>Thank you for your purchase.</p>",
80+
"format": "pdf",
81+
"pdf_options": {
82+
"print_background": true
83+
}
84+
}'
85+
```
86+
87+
The response URL already includes the PDF extension:
88+
89+
```json
90+
{
91+
"url": "https://hcti.io/v1/image/abc123.pdf",
92+
"id": "abc123"
93+
}
94+
```
95+
96+
Requesting that URL renders and returns the separately saved PDF.
97+
7098
### Letter size with margins
7199

72100
```json

0 commit comments

Comments
 (0)