Formats

Image formats for the web

Set the output format with image.format on a compress request.

A common setup is AVIF first, WebP second and JPEG last, offered with the HTML <picture> element. Send the same source file three times with three values of image.format.

heic and gif are also accepted as output formats. Browsers other than Safari do not display HEIC. GIF is limited to 256 colours and has no quality setting.

What "original" resolves to

image.format defaults to original, which keeps the input's format where that format is a sensible output, and picks the nearest one where it is not.

For audio, audio.format=original keeps MP3, OGG, Opus, WAV and FLAC inputs in their own format. Any other input becomes AAC in an .m4a file. The audio default is aac, not original.

The response always states the format that was written: the Smol-Output-Format header on a direct request, and output_format in the result object.

What the API changes in an image

• Orientation. A rotation stored as a tag is applied to the pixels, so the image displays the right way up in every viewer.
• Colour. An image with a wide-gamut profile, such as Display P3 or Adobe RGB, is converted to sRGB through its profile.
• Transparency. Kept in formats that support it. Flattened onto white when the output is JPEG.
• Animation. Kept when an animated GIF or WebP is written as GIF or WebP. For any other output format the first frame is used, and the result carries a warning.
• Size. By default an image larger than 2000 by 2000 pixels is shrunk to fit inside that box. Smaller images are not enlarged. Turn this off with image.resize=false.
• Metadata. Removed by default. image.strip_metadata=false skips the removal. PNG output is the exception in both directions. See Metadata.

How the file type is detected

The type is read from the file's content, not from its name. A PNG named photo.jpg is handled as a PNG. The file name is used in two cases:

• To tell apart formats that share a container. A DNG and a TIFF start with the same bytes, as do a DOCX and a DOCM.
• For text formats, which have no signature: CSV, TSV, JSON, NDJSON, HTML and Markdown. These need a file name with the right extension.

Send the name with ?filename= or a Content-Disposition header on a direct request, or with input.filename on a job. A file that cannot be identified is refused with unsupported_input.

Compress: inputs and outputs

aac and m4a both write AAC audio in an .m4a file. ogg and opus both write Opus audio, in an .ogg or an .opus file. alac writes lossless audio in an .m4a file.

Office documents, tables and fonts cannot be compressed. They can be converted.

Convert: inputs and outputs

Set the target with convert.to, or ?to= in a query string.

• Camera RAW files cannot be converted. Use compress, which decodes them to JPEG, PNG, WebP, AVIF or HEIC.
• A font conversion changes the container only. The outlines and tables inside the font are kept.
• In a table conversion every cell is text.
• A target outside the list for the file's kind is refused with unsupported_target.

Strip metadata: inputs

Strip metadata accepts images and PDFs. The output has the same format as the input. Any other kind is refused with unsupported_input.

Direct request or job

A video or an office document sent to a direct endpoint is refused with use_async_job. See Large files and jobs for the job flow. The same lists are available to code at GET /v1/capabilities.