Color Key

The colorkey parameter makes every pixel close to a chosen color transparent. Use it to drop a solid studio background, such as white behind a product shot, without the cost or latency of AI background removal.

Choosing the Key Color

colorkey accepts:

• A hex color, such as colorkey=fff or colorkey=4c7499. 3, 4, 6 and 8 digit forms are accepted; any alpha digits are ignored.
• A CSS color keyword, such as colorkey=white.
• auto, or no value at all (colorkey or colorkey=), which keys the color of the image’s top-left pixel. If that pixel is already transparent, nothing is keyed.

A value that is not a valid color is ignored and the image is returned unkeyed.

How close a pixel must be to the key is set by colorkey-tol, and how softly the edge fades by colorkey-feather. The defaults key pure white plus slightly off-white JPEG noise.

Edit in Sandbox

Edit in Sandbox

Output Format

Transparency needs an output format that carries alpha.

• No fm set: if any pixel was made transparent, the image is returned as PNG. If nothing matched the key, the image keeps its usual format, so a JPEG stays a JPEG.
• An explicit format with alpha (fm=png, fm=webp, fm=avif and others) keeps the transparency.
• fm=jpg cannot carry alpha, so keyed pixels are flattened onto white.
• fm=gif keeps the transparency, but GIF alpha is either on or off, so soft edges are dithered.

With fit=fill and a solid fill, the letterbox area is also transparent rather than white.

Order of Operations

Color keying runs before trimming, cropping and resizing. This means:

• trim=alpha crops to the keyed subject.
• Resizing blends the new transparent edges, so downscaled output has smooth edges.

On animated images, every frame is keyed with the color found on the first frame, so an automatic key does not flicker.

Color Key Compared to Background Removal