HDR to PDF API
Send a .hdr to /v2/convert/hdr/to/pdf and get a one-page PDF with the image stored at 16 bits per channel. The sample asks for PageSize=letter and PageOrientation=landscape, so the 300 × 150 pt panorama sits centered on a 792 × 612 pt sheet.
- Endpoint
- POST /v2/
convert/ hdr/ to/ pdf - Accepts
- hdr
- Sample timing
- 28 ms median of 5 runsHow we measure
- Request size
- Up to 10 MB on the Free plan or 100 MB on paid plans, all files together
Request and response
Every sample below ran against the API before this page was published. Set PDFCONVERSIONAPI_KEY to your key and run it as is.
curl -sS -X POST \
https://api.pdfconversionapi.com/v2/convert/hdr/to/pdf \
-H "Authorization: Bearer $PDFCONVERSIONAPI_KEY" \
-F File=@lakeside-sunset-sky.hdr \
--form-string PageSize=letter \
--form-string PageOrientation=landscape \
-o response.json
# FileData is base64. Save the first file in converted/,
# or print the JSON error.
if jq -e '.Files' response.json > /dev/null; then
mkdir -p converted
name=$(jq -r '.Files[0].FileName' response.json)
jq -r '.Files[0].FileData' response.json \
| base64 --decode > "converted/$name"
else
cat response.json
fiimport base64
import os
import requests
key = os.environ["PDFCONVERSIONAPI_KEY"]
response = requests.post(
"https://api.pdfconversionapi.com/v2/convert/hdr/to/pdf",
headers={"Authorization": f"Bearer {key}"},
files=[("File", open("lakeside-sunset-sky.hdr", "rb"))],
data={
"PageSize": "letter",
"PageOrientation": "landscape",
},
timeout=180,
)
result = response.json()
if not response.ok:
raise SystemExit(f"{result['Code']}: {result['Message']}")
os.makedirs("converted", exist_ok=True)
for file in result["Files"]:
path = os.path.join("converted", file["FileName"])
with open(path, "wb") as out:
out.write(base64.b64decode(file["FileData"]))
print(path, file["FileSize"], "bytes")
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { join } from "node:path";
const form = new FormData();
const file = "lakeside-sunset-sky.hdr";
form.append("File", new Blob([await readFile(file)]), file);
form.append("PageSize", "letter");
form.append("PageOrientation", "landscape");
const url = "https://api.pdfconversionapi.com/v2/convert/hdr/to/pdf";
const key = process.env.PDFCONVERSIONAPI_KEY;
const response = await fetch(url, {
method: "POST",
headers: { Authorization: `Bearer ${key}` },
body: form,
});
const result = await response.json();
if (!response.ok) {
throw new Error(`${result.Code}: ${result.Message}`);
}
await mkdir("converted", { recursive: true });
for (const file of result.Files) {
const path = join("converted", file.FileName);
await writeFile(path, Buffer.from(file.FileData, "base64"));
console.log(path, file.FileSize, "bytes");
}
{
"ConversionCost": 1,
"ConversionTime": 0.028,
"Files": [
{
"FileName": "lakeside-sunset-sky.pdf",
"FileExt": "pdf",
"FileSize": 68592,
"FileData": "JVBERi0xLjcKJYCAgIAKMSAw…"
}
]
}Response from our test run on 2026-11-03. ConversionTime shows the median of 5 runs. FileData is shortened here; the real response carries the whole file as base64.
The sample, converted
The same file the code sends. Download the input and the output and compare them yourself.

- Input
- lakeside-sunset-sky.hdr (90 KB)
- Output
- lakeside-sunset-sky.pdf (67 KB)
- Source
- A sunset sky panorama we drew in code and saved as a 400 × 200 Radiance RGBE file with run-length scanlines; the sun disc is 60.0. (CC0-1.0). How it was made
- Made by
- 2026-11-04, API build
9eeeb0640aba
Parameters
Send these as form fields next to the file. Names are case-insensitive. If you set one of the documented options below that we don't support yet, the request fails with a 400 that names it instead of returning a file made without it.
| Parameter | What it does |
|---|---|
PageSizeenum, default default | Without it, the page is the image at 96 px per inch: 300 × 150 pt for the 400 × 200 sky. A named sheet keeps the picture at that size or smaller and centers it, as on the sample's Letter page.Values: default, auto, a3, a4, a5, letter, legal |
PageOrientationenum, default default | landscape swaps the sheet to 792 × 612 pt for Letter, which suits a wide panorama. No effect when the page follows the image.Values: default, portrait, landscape |
Rotateinteger | Clockwise degrees. 90 stood the panorama upright on a 150 × 300 pt page; 45 needed a 318.2 pt square.Values: -360 to 360 |
MarginHorizontalinteger, default 0 | Left and right margin in millimetres; 6 mm on each side made the image-sized page 334.02 pt wide.Values: 0–500 (mm) |
MarginVerticalinteger, default 0 | Top and bottom margin in millimetres. Margins that leave no room on a fixed sheet return 400.Values: 0–500 (mm) |
FileNamestring | Base name of the PDF file. |
StoreFileboolean, default false | Keeps the file 3 hours behind Files[].Url. |
What carries over, and what doesn't
Kept
- 16 bits per channel in the embedded image, with the same values as the PNG route
- The panorama's pixels unscaled: a Letter sheet is larger than 300 × 150 pt, so nothing shrinks
- An opaque image with no soft mask, since the .hdr has no alpha
Lost or not yet supported
- Color management: the image is DeviceRGB with no ICC profile, and the linear values are shown as if they were sRGB.
- Everything above 1.0; the sun is stored at the 16-bit maximum.
- Raster options such as
ImageWidth,ImageQualityandColorSpace, which do nothing on this route.
Limits
- One .hdr becomes one page.
/v2/convert/images/to/pdfdoes not take .hdr files: it answered 422 'image 1 (lakeside-sunset-sky.hdr) could not be read: this HDR image can't be read yet'. - Requests of up to 10 MB on the Free plan or 100 MB on paid plans.
- 100,000,000 pixels per image.
- Rotate from -360 to 360; margins from 0 to 500 mm.
- 120 seconds per conversion.
Where teams use it
Daylight study reports
Lighting simulations can produce .hdr renderings. Each can become a Letter or A4 page for a report that clients open in any PDF reader.
Printable HDRI contact pages
A studio can print or archive its environment maps one per page, landscape, with margins for notes.
Questions
Where does the image sit on a Letter page?
Centered, at 96 pixels per inch. In the sample the 300 × 150 pt panorama is drawn at x 246, y 231 on the 792 × 612 pt landscape sheet. Larger images are shrunk to fit; smaller ones are never enlarged.
Can I combine several .hdr images in one PDF?
Not in one request. Convert each .hdr to its own PDF, then join them with the merge route.
Why do the colors look darker than in my HDR viewer?
The page stores the linear values, clipped at 1.0, with no exposure and no profile, and PDF readers draw them as ordinary RGB. Midtones come out darker than a viewer that applies a display curve.
Convert your first HDR file in a minute.