API reference

The result object

Every field of the object that describes what the API did to a file, and where the object appears.

Where it appears

Request	Where	Form
Direct request (compress, convert, strip metadata)	The `Smol-Result` response header	Compact JSON on one line
Job	The `result` field of the job object, once the job has succeeded	A JSON object, with two more fields: `download_url` and `download_expires_at`
Webhook event	`data.job.result`	The same as on the job

The object has the same fields for every kind of file and every operation. A field that does not apply is null. It is never left out.

Example

a JPEG compressed to AVIF

{
  "kind": "image",
  "input_format": "jpg",
  "output_format": "avif",
  "original_size": 1614027,
  "output_size": 188406,
  "savings_percent": 88.3,
  "kept_original": false,
  "increased": false,
  "width": 1200,
  "height": 800,
  "pages": null,
  "duration_seconds": null,
  "video_codec": null,
  "warnings": []
}

Fields

Field	Type	Description
kind	string	What the input is, as detected from its content: `image`, `pdf`, `video`, `audio`, `word`, `sheet`, `presentation`, `table` or `font`.
input_format	string	The format of the input, as a lower-case file extension without the dot, for example jpg. It is detected from the content, so it can differ from the extension of the name you sent. One spelling is used per format: jpg, tiff, heic, html, md, ndjson, mpg.
output_format	string	The format of the returned file, in the same form. Use it as the file extension when you save the output.
original_size	integer	The size of the input in bytes.
output_size	integer	The size of the returned file in bytes.
savings_percent	number	The share of the original size that was saved: (1 − output_size ÷ original_size) × 100, rounded to one decimal. Negative when the output is larger than the input.
kept_original	boolean	`true` when a compress request could not make the file smaller and returned the input. Such a request is not billed. See Kept original.
increased	boolean	`true` when the returned file is larger than the input and is not the input itself. This happens when you asked for a conversion or a resize. Never `true` together with `kept_original`.
width	integer or null	The width of the returned image or video in pixels. Also set for a PDF page rendered to an image. null for other kinds.
height	integer or null	The height, under the same conditions as width.
pages	integer or null	The number of pages in the input PDF. null for other kinds.
duration_seconds	number or null	The length of the audio or video in seconds, with decimals. null for other kinds.
video_codec	string or null	The codec of the returned video: `h265`, `h264` or `vp9`. null for other kinds, and null when a video was returned unchanged with `kept_original: true`.
warnings	array of strings	Things you should know about a result that succeeded. Usually empty.

On a job, the result has two more fields:

Field	Type	Description
download_url	string or null	A signed link to the output. null when the output was sent to your own storage, and once the output has been deleted. See Download the output.
download_expires_at	string or null	When the link stops working and the output is deleted. null whenever download_url is null.

Which fields are set for each kind

Kind and operation	width, height	pages	duration_seconds	video_codec
Image: compress, convert, strip metadata	Set	null	null	null
Image converted to PDF	null	null	null	null
PDF: compress, strip metadata	null	Set	null	null
PDF page converted to an image	Set	Set	null	null
Video: compress, convert	Set	null	Set	Set
Audio: compress, convert	null	null	Set	null
Office document, table, font: convert	null	null	null	null

For a compressed image or video, width and height are those of the output, after any resize.
When kept_original is true, output_format is the input's format. output_size equals original_size, except for an image whose metadata was removed without re-encoding, which can be slightly smaller.

Warnings

A warning does not mean the request failed. It tells you that the result differs from what you might expect. Show warnings to a person or log them. Do not match on the exact text, which may be reworded.

Warning	When
The input is animated and avif is a still format, so only the first frame was kept.	An animated GIF or WebP was written as a format other than GIF or WebP. The message names the output format.
Some images inside the PDF could not be recompressed and were left as they were.	PDF compression finished, but skipped some embedded images.
BMP files carry no metadata, so the file is unchanged.	Strip metadata was asked for a BMP.

Reading it from a header

On a direct request the body is the file, so the result travels in the Smol-Result header. Parse the header value as JSON. Any character outside printable ASCII is replaced by ? in the header, which can only affect the text of a warning.

Node.js

const result = JSON.parse(response.headers.get("smol-result"));
if (result.kept_original) console.log("already as small as it gets");
for (const warning of result.warnings) console.warn(warning);

The most used values also have headers of their own: Smol-Original-Size, Smol-Output-Size, Smol-Savings-Percent, Smol-Output-Format and Smol-Kept-Original. Whether the request was charged is in Smol-Billed, which is not part of the result object.