Skip to content
pdfconversionapi

HEIF to BMP API

POST a .heif file to /v2/convert/heif/to/bmp and get a 32-bit bitmap whose fourth byte holds the HEIF's alpha plane. The sample sticker keeps its clear background and soft shadow, and its 11,269 bytes become 409,722.

Endpoint
POST /v2/convert/heif/to/bmp
Accepts
heif
Sample timing
23 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/heif/to/bmp \
  -H "Authorization: Bearer $PDFCONVERSIONAPI_KEY" \
  -F File=@succulent-sticker.heif \
  -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
fi
200 OK23 ms median1 file, 400 KB
{
  "ConversionCost": 1,
  "ConversionTime": 0.023,
  "Files": [
    {
      "FileName": "succulent-sticker.bmp",
      "FileExt": "bmp",
      "FileSize": 409722,
      "FileData": "Qk16QAYAAAAAAHoAAABsAAAA…"
    }
  ]
}

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.

First page of succulent-sticker.bmp, rendered by the API
Input
succulent-sticker.heif (11 KB)
Output
succulent-sticker.bmp (400 KB)
Source
A potted succulent sticker that we drew ourselves, with a transparent background and a soft shadow, saved as a 320 x 320 HEIF with an alpha plane. (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.

ParameterWhat it does
ImageWidthintegerScales the image, alpha included: 200 gives a 200 × 200 bitmap of 160,122 bytes.Values: 1–20000
ImageHeightintegerTarget height, or with ImageWidth a box to fit into.Values: 1–20000
ScaleProportionsboolean, default truefalse stretches to both sizes.
ScaleIfLargerboolean, default falsetrue keeps images smaller than the box at their own size.
ScaleImageboolean, default truefalse cuts the top-left area at the given size.
ImageResolutionintegerDots per inch for the header, stored in pixels per meter. Without it, the header says 0.Values: 10–800
ColorSpaceenum, default defaultgray turns the colors gray and keeps the alpha bytes; the file size stays 409,722 bytes.Values: default, rgb, gray, monochrome
FileNamestringBase name of the bitmap; succulent-sticker otherwise.
StoreFileboolean, default falsetrue returns a link valid for 3 hours instead of base64 data.

What carries over, and what doesn't

Kept

  • The alpha plane, value for value: 72,482 clear, 11,811 partly clear and 18,107 opaque pixels, exactly as decoded
  • Every RGBA value: the bitmap matched our HEIF to PNG output on all 102,400 pixels
  • The soft shadow under the pot, with alpha 112 of 255 at its center
  • The 320 × 320 size
  • Acceptance by both readers we tried, which returned the same RGBA values as the PNG, partly clear pixels included

Lost or not yet supported

  • Compression: 409,722 bytes against 11,269 for the HEIF, since every pixel takes four bytes.
  • A background choice: AlphaColor is not read on this route, so clear areas stay clear.
  • Tones of HEIF files that carry an embedded Display P3 profile, which the decoder stretches (16 became 0, 235 became 255).

Limits

  • One HEIF per request, at most 100,000,000 pixels.
  • Requests up to 10 MB on the Free plan or 100 MB on paid plans; 120 seconds per conversion.
  • HEIF files whose picture is coded as AV1 (AVIF) return 422 'Avif: decoding is not available for this format'.
  • A HEIF saved at one desktop encoder's top quality setting returned 422 'malformed data'.

Where teams use it

Overlays for Windows programs

Signage players, kiosk software and older Windows tools that draw 32-bit bitmaps with alpha can place a cut-out graphic over other content. A HEIF sticker or logo converts with its transparent background intact.

Sprites for small game and UI toolkits

Some toolkits load BMP sprites and read the fourth byte as alpha. The bitmap's fixed 122-byte header and raw rows keep the loading code short.

Questions

Will the transparent background show as transparent?

The alpha is in the file: each pixel's fourth byte comes from the HEIF's alpha plane, and the header has an alpha mask. Whether it shows depends on the program reading the BMP, since some draw bitmaps as opaque. A HEIF with no see-through pixels gets a 24-bit bitmap without the fourth byte instead: our harbor photo sent as .heif came back that way.

How do I get a white background instead?

This route doesn't flatten. Convert with /v2/convert/heif/to/pnm and AlphaColor=#FFFFFF, then send that file to /v2/convert/pnm/to/bmp. We did this with the sample and got a 24-bit bitmap of 307,254 bytes with white corners and a soft gray shadow.

Is a .heif file treated differently from .heic?

No. Both go to the same decoder, which reads the file's content. The sample is HEVC-coded with an alpha plane, the same structure the desktop encoder we used writes for .heic files. HEIF files coded with AV1 are refused.

Convert your first HEIF file in a minute.