Skip to content
pdfconversionapi

HEIF to ICO API

POST a .heif to /v2/convert/heif/to/ico and get an icon with one 32-bit, PNG-compressed image. Transparency survives, soft edges included, and larger images are shrunk: the 320 × 320 sticker gives 256 × 256 by default and 128 × 128 at the sample's ImageWidth=128.

Endpoint
POST /v2/convert/heif/to/ico
Accepts
heif
Sample timing
25 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/ico \
  -H "Authorization: Bearer $PDFCONVERSIONAPI_KEY" \
  -F File=@succulent-sticker.heif \
  --form-string ImageWidth=128 \
  -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 OK25 ms median1 file, 11 KB
{
  "ConversionCost": 1,
  "ConversionTime": 0.025,
  "Files": [
    {
      "FileName": "succulent-sticker.ico",
      "FileExt": "ico",
      "FileSize": 11077,
      "FileData": "AAABAAEAgIAAAAAAIAAvKwAA…"
    }
  ]
}

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.ico, rendered by the API
Input
succulent-sticker.heif (11 KB)
Output
succulent-sticker.ico (11 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
ImageWidthintegerIcon width. The sample's 128 makes an 11,077-byte icon; 64 makes 3,848 bytes; 1000 is capped at 256.Values: 1–20000
ImageHeightintegerIcon height, or a fitting box together with ImageWidth.Values: 1–20000
ScaleProportionsboolean, default truefalse stretches a non-square image to the exact box.
ScaleIfLargerboolean, default falsetrue leaves small images at their own size.
ScaleImageboolean, default truefalse crops from the top-left corner.
ColorSpaceenum, default defaultgray makes a gray icon (33,474 bytes at 256 px), with transparency kept. monochrome is applied again after the shrink to 256 px, so all 19,212 visible pixels are black or white, and the alpha, soft shadow included, is kept (12,990 bytes).Values: default, rgb, gray, monochrome
FileNamestringName of the .ico without the extension.
StoreFileboolean, default falsetrue returns a 3-hour download link.

What carries over, and what doesn't

Kept

  • Partial transparency: at 128 px the icon has 11,410 clear, 2,256 partly clear and 2,718 opaque pixels
  • The square shape and the soft shadow under the pot
  • Lossless storage of the scaled pixels, as a 32-bit PNG inside the icon

Lost or not yet supported

  • Size above 256 pixels; the 320 px sticker becomes 256 × 256 even without ImageWidth.
  • Multiple resolutions: the icon holds a single image.
  • Fine detail at small sizes, since the image is shrunk with a Lanczos3 filter before writing.
  • Correct tones for HEIF files with an embedded Display P3 profile.

Limits

  • One HEIF per request, one image per icon.
  • Up to 100,000,000 decoded pixels, requests up to 10 MB on the Free plan or 100 MB on paid plans, 120 seconds per conversion.
  • AV1-coded HEIF files (AVIF) return 422.

Where teams use it

App and shortcut icons from design files

Cut-outs and stickers saved as HEIF with transparency can become .ico files for Windows shortcuts, installers and favicons in one call, without an image editor.

Favicons with soft edges

The icon keeps partial alpha, so rounded or shadowed artwork blends with any browser tab color instead of showing a hard fringe.

Questions

Does the icon include 16, 32 and 48 px versions?

No, one entry only. Request each size with ImageWidth and assemble a multi-size icon yourself if your platform needs one.

Is the soft shadow kept?

Yes. ICO entries here are 32-bit PNGs, which store 256 levels of transparency. At 128 px, 2,256 of the sample's pixels are partly transparent, mostly in the shadow and along the leaf edges.

What happens to options this route doesn't use?

They are accepted and ignored: ImageQuality=50 or TransparentColor returned the same icon. Only options the route reads are checked, so ImageWidth=0 still returns 400.

Convert your first HEIF file in a minute.