ICO to JPG API
POST an icon to /v2/convert/ico/to/jpg and get a baseline JPEG back. JPEG has no transparency, so the icon's best entry is first blended onto a solid color: white by default, or the AlphaColor you pass, as in the sample.
- Endpoint
- POST /v2/
convert/ ico/ to/ jpg - Accepts
- ico
- Sample timing
- 1 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/ico/to/jpg \
-H "Authorization: Bearer $PDFCONVERSIONAPI_KEY" \
-F File=@paper-plane-app-icon.ico \
--form-string 'AlphaColor=#F4F1EA' \
--form-string ImageQuality=90 \
-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/ico/to/jpg",
headers={"Authorization": f"Bearer {key}"},
files=[("File", open("paper-plane-app-icon.ico", "rb"))],
data={
"AlphaColor": "#F4F1EA",
"ImageQuality": "90",
},
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 = "paper-plane-app-icon.ico";
form.append("File", new Blob([await readFile(file)]), file);
form.append("AlphaColor", "#F4F1EA");
form.append("ImageQuality", "90");
const url = "https://api.pdfconversionapi.com/v2/convert/ico/to/jpg";
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.001,
"Files": [
{
"FileName": "paper-plane-app-icon.jpg",
"FileExt": "jpg",
"FileSize": 12764,
"FileData": "/9j/4AAQSkZJRgABAgAAAQAB…"
}
]
}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
- paper-plane-app-icon.ico (34 KB)
- Output
- paper-plane-app-icon.jpg (12 KB)
- Source
- A four-size app icon we drew and assembled ourselves: 16, 32 and 48 px entries stored as 32-bit bitmaps with a 1-bit mask, and a 256 px entry stored as PNG. The paper plane design is fictional. (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 |
|---|---|
AlphaColorstring, default white | Background the transparent parts are blended onto. The sample sends #F4F1EA, and its clear corners come back as exactly (244, 241, 234).Values: A color name (white, black, red, green, blue, gray), #RRGGBB or R,G,B |
BackgroundColorstring, default white | Used as the background only when AlphaColor is missing. BackgroundColor=black gave a 10,292-byte JPEG of the sample.Values: Same as AlphaColor |
ImageQualityinteger, default 85 | JPEG quality. We use 85 when it's left out; ConvertAPI documents 75 for this pair. The sample at 90 is 12,764 bytes; with no options it is 10,602, and at 50 it is 6,187.Values: 1–100 |
ImageWidthinteger | Width in pixels. ImageWidth=128 returned a 5,011-byte 128 × 128 JPEG of the icon.Values: 1–20000 |
ImageHeightinteger | Height in pixels, or with a width, the box the icon must fit in.Values: 1–20000 |
ScaleProportionsboolean, default true | false lets a non-square box stretch the icon to fill it. |
ScaleIfLargerboolean, default false | true keeps a 256 px icon at 256 px when you ask for something bigger. |
ScaleImageboolean, default true | false crops to the requested size from the top-left corner without resampling. |
ColorSpaceenum, default default | gray and monochrome write a one-channel JPEG (5,588 and 5,311 bytes for the sample). cmyk is refused with a 400.Values: default, rgb, gray, monochrome |
ImageResolutioninteger | Stored as the JFIF density in dots per inch. Without it the JPEG only records a 1:1 pixel aspect.Values: 10–800 |
ImageInterpolationboolean, default false | Accepted, true or false; resampling is Lanczos either way. |
FileNamestring | Output name without extension; the icon's own name is used otherwise. |
StoreFileboolean, default false | Keeps the JPEG on our side for 3 hours and answers with its URL. |
What carries over, and what doesn't
Kept
- The look of the icon on the chosen background: at quality 90, the largest difference from the icon blended onto #F4F1EA was 40 levels, the average below 1
- Soft edges and the drop shadow as smooth blends into the background color
- Full color detail: the JPEG is written without chroma subsampling (4:4:4)
- The 256 × 256 size of the icon's largest entry
Lost or not yet supported
- Transparency. The sample's 10,690 clear pixels and 12,009 partly clear ones are mixed with
AlphaColorand stored as solid color. - Exact pixels, because JPEG is lossy at every quality setting.
- The 16, 32 and 48 px entries of the sample; one image is converted.
Limits
- One icon per request; two files return 400.
- Requests up to 10 MB on the Free plan or 100 MB on paid plans, all files and fields together.
ImageWidthandImageHeightup to 20,000 px; output at most 100,000,000 pixels.- 120 seconds per conversion, then 504.
Where teams use it
Fields and services that accept only JPEG
Some upload forms, print services and listing feeds take JPEG and nothing else. Send AlphaColor set to the background the icon will sit on, so its rounded corners and shadow blend into the page instead of showing a white square.
Thumbnails for an icon library
A grid of icons on a fixed background can be built from JPEG thumbnails. At quality 75 the sample icon is 8,259 bytes at full 256 px size, and less if you set ImageWidth.
Questions
What color do the transparent parts of the icon get?
White unless you say otherwise. AlphaColor sets it (#F4F1EA in the sample, black, or R,G,B); BackgroundColor is read when AlphaColor is absent. An unknown name such as teal returns 400.
Why does the shadow look gray on a white JPEG?
The shadow in the icon is dark pixels that are partly transparent. Blending them onto white produces light gray, the same result as drawing the PNG version on a white page.
Which quality is used if I don't send ImageQuality?
85. ConvertAPI's documentation gives 75 for ICO to JPG, so send ImageQuality=75 if you need the same setting. For the sample, 75 gives 8,259 bytes and 85 gives 10,602.
Can I keep the transparency?
Not in a JPEG. Use /v2/convert/ico/to/png or /v2/convert/ico/to/webp; both keep the icon's alpha channel exactly.
Convert your first ICO file in a minute.