Skip to content
pdfconversionapi

PSD to ICO API

POST a .psd to /v2/convert/psd/to/ico and get an .ico with one image inside, stored as PNG with full alpha. The sample sends ImageWidth=64, so the 4:3 sticker comes back as a 64 × 48 icon of 4,496 bytes.

Endpoint
POST /v2/convert/psd/to/ico
Accepts
psd
Sample timing
92 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/psd/to/ico \
  -H "Authorization: Bearer $PDFCONVERSIONAPI_KEY" \
  -F File=@night-market-sticker.psd \
  --form-string ImageWidth=64 \
  -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 OK92 ms median1 file, 4.4 KB
{
  "ConversionCost": 1,
  "ConversionTime": 0.092,
  "Files": [
    {
      "FileName": "night-market-sticker.ico",
      "FileExt": "ico",
      "FileSize": 4496,
      "FileData": "AAABAAEAQDAAAAAAIAB6EQAA…"
    }
  ]
}

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 night-market-sticker.ico, rendered by the API
Input
night-market-sticker.psd (173 KB)
Output
night-market-sticker.ico (4.4 KB)
Source
A layered event sticker we drew for this site: 400 x 300 pixels, 8 bits per channel, transparent around the sticker, with seven layers including a soft shadow, a Screen-blended moon, a two-layer text group and a hidden draft stamp. Written as a PSD by our own script from the published file format specification. (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 height follows the canvas, so the 400 × 300 sticker at 64 is 64 × 48. Widths above 256 are fitted back into 256 × 256: 512 gave 256 × 192.Values: 1–20000
ImageHeightintegerIcon height. With ImageWidth=48 and ImageHeight=48 the sticker keeps its shape and comes out 48 × 36.Values: 1–20000
ScaleProportionsboolean, default truefalse makes a square icon from a non-square PSD by stretching it: 32 × 32 gave a 2,008-byte icon.
ScaleImageboolean, default truefalse crops the canvas instead: 300 × 300 from the top left, then shrunk to fit 256 × 256.
ScaleIfLargerboolean, default falsetrue skips a resize that would enlarge the canvas; the 256 px cap still applies.
ColorSpaceenum, default defaultgray gives a gray icon that keeps its alpha (24,301 bytes at the default 256 × 192).Values: default, rgb, gray, monochrome; cmyk returns 400
FileNamestringBase name of the icon; night-market-sticker.ico by default.
StoreFileboolean, default falsetrue gives a 3-hour link in Files[].Url.

What carries over, and what doesn't

Kept

  • Alpha with soft edges: at 64 × 48 the icon has 161 clear and 775 partly clear pixels, from the corners and the shadow
  • The visible layers as the API merges them; the hidden DRAFT stamp is not drawn
  • The PSD's aspect ratio, unless you ask for another: 64 × 48, 48 × 36 or 256 × 192

Lost or not yet supported

  • Size above 256 px: without a size the icon is 256 × 192, the largest that keeps the 4:3 shape inside 256 × 256.
  • Multiple sizes. The file holds one image; for 16, 32 and 48 px versions, make one request each.
  • Detail at small sizes. At 64 × 48 the title is still legible, but the details line under it blurs into a gray stripe.
  • Layers, the 300 ppi setting and the color profile.

Limits

  • One PSD per request; one image per icon.
  • Requests up to 10 MB on the Free plan or 100 MB on paid plans, all files and fields together.
  • Icon sides of at most 256 px; larger results are fitted down.
  • Up to 100,000,000 pixels after flattening, or 413.
  • 120 seconds per conversion, then 504.
  • Type layers, smart objects and layer effects are not tested yet.

Where teams use it

Favicons and app icons from the design file

When the logo lives in a PSD, request the icon straight from it in a build step. Send ImageWidth and ImageHeight with ScaleProportions=false, or crop to a square, if the artwork is not square.

Shortcut and installer icons

Build tools that need an .ico can take this output. Its single entry is stored as PNG with 32 bits per pixel, so check that the tool reading it accepts PNG-compressed icon entries.

Questions

Does the icon have to be square?

No. The API keeps the PSD's proportions, so the 4:3 sample gives a 64 × 48 icon. If the place you use it expects squares, crop with ScaleImage=false or stretch with ScaleProportions=false.

Can one .ico contain several sizes?

Not from this route. Each request writes one entry. Request the sizes you need separately.

Is TransparentColor applied to icons?

No. The ICO route already keeps the PSD's own transparency, and TransparentColor is not used for it: #1E2A4A returned the same bytes as no value.

Convert your first PSD file in a minute.