Options

The options object

Options are grouped into five sections. This is the whole object, with every field set to its default. The defaults are the defaults of the Smol Mac app.

{
  "image": {
    "format": "original",
    "quality": 75,
    "resize": { "mode": "fit", "width": 2000, "height": 2000 },
    "strip_metadata": true
  },
  "pdf": { "quality": "medium" },
  "video": {
    "format": "mp4",
    "codec": "h265",
    "quality": "high",
    "resolution": "original",
    "strip_audio": false,
    "slow": false,
    "crf": null,
    "preset": null,
    "audio_quality": "high"
  },
  "audio": {
    "format": "aac",
    "quality": "high",
    "channels": "stereo",
    "strip_metadata": false,
    "bitrate_kbps": null,
    "sample_rate_hz": null
  },
  "convert": { "to": null, "page": 1, "dpi": 144 }
}

Every field is optional. Send only the fields you want to change.

Which section is used depends on the operation and on what the file is:

Sections that do not apply are still validated, then ignored. This lets you send one options object with a mixed set of files: the image settings apply to the images, the PDF setting to the PDFs.

Sending options

As query parameters

On the direct endpoints, write each field as a query parameter. The name is the path to the field, joined with dots.

curl -X POST "https://api.smolmac.com/v1/compress?image.format=avif&image.quality=60&image.resize.width=1200" \
  -H "Authorization: Bearer $SMOL_API_KEY" \
  --data-binary @photo.jpg \
  -o photo.avif

• Booleans are written true or false. Numbers are written in decimal.
• to, page and dpi are short forms of convert.to, convert.page and convert.dpi.
• Two query parameters are not options. filename names the file you are sending, and preset names a saved set of options. Every other query parameter is read as an option, so an unknown one is an error.

As JSON

On the direct endpoints, send the request as multipart/form-data with the file in a part named file and the options, as a JSON string, in a part named options.

curl -X POST "https://api.smolmac.com/v1/compress" \
  -H "Authorization: Bearer $SMOL_API_KEY" \
  -F "[email protected]" \
  -F 'options={"image":{"format":"avif","quality":60,"resize":{"width":1200}}}' \
  -o photo.avif

For a job, put the same object in the options property of the request body. Jobs take options as JSON only.

{
  "operation": "compress",
  "input": { "upload": "upl_Zk3Vb9QeT1mXc7HsW0yN" },
  "options": { "pdf": { "quality": "small" } }
}

From a preset

A preset is an options object stored on your account under a name. A direct request names it with ?preset=, and a job with the preset field of its body. Options sent with the request are applied on top.

curl -X POST "https://api.smolmac.com/v1/compress?preset=web-hero&image.quality=80" \
  -H "Authorization: Bearer $SMOL_API_KEY" \
  --data-binary @photo.jpg \
  -o photo.avif

Precedence

Three sources can set the same field. From weakest to strongest: the preset, the JSON options, the query string. The override is one field at a time, so fields that appear in only one source are kept. With the JSON above and ?image.quality=80, the request runs with format AVIF, width 1200 and quality 80.

image

Used when an image is compressed. See Compress images.

Turning resizing off

Resizing is on by default, so an image larger than 2000 by 2000 pixels is scaled down unless you say otherwise. To keep the pixel dimensions, set image.resize to false:

# query string
curl -X POST "https://api.smolmac.com/v1/compress?image.resize=false" ...

# JSON
{ "image": { "resize": false } }

In the query string, setting image.resize.width, image.resize.height or image.resize.mode turns resizing on. A dimension you leave out keeps its default of 2000.

pdf

Used when a PDF is compressed. See Compress PDFs.

video

Used when a video is compressed. Video runs as a job. See Video.

audio

Used when an audio file is compressed. See Audio.

convert

Used by the convert operation. See Convert files.

Validation

Options are checked before the file is processed. A field that does not exist, or a value outside the allowed set, fails the request with 400 invalid_options. The API never falls back to a default for a field it does not recognise, because a misspelled option would then pass unnoticed.

curl -X POST "https://api.smolmac.com/v1/compress?image.qualty=60" \
  -H "Authorization: Bearer $SMOL_API_KEY" \
  --data-binary @photo.jpg

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_options",
    "message": "Unknown option \"image.qualty\".",
    "param": "image.qualty",
    "request_id": "req_7pWc2LxR9dKf0aTnM4vB",
    "doc_url": "https://smolmac.com/docs/reference/errors#invalid_options"
  }
}

param is the dotted path of the field that caused the error, so you can point at it in your own logs or UI. The same applies to a bad value:

A few rules depend on the file and are checked during processing, for example a convert.page beyond the last page of the PDF, or a sample rate the output format does not support. These also fail with invalid_options, but param is null and the message names the field.