Presets

A preset stores a target format and its options under a name, for example "Web images" for JPG at quality 80 and at most 1600 px wide. Create and edit presets in the dashboard under Presets. An account can have up to 100 presets.

Use a preset#

Send the ID or the name of the preset in preset of POST /v1/convert or of each entry of a batch. Names are not case-sensitive, and repeated spaces count as one.

curl "https://api.switchfile.io/v1/convert?wait=30" \
  -H "Authorization: Bearer $SWITCHFILE_API_KEY" \
  -F [email protected] \
  --form-string preset='Web images'

import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("file", new Blob([await readFile("photo.png")]), "photo.png");
form.append("preset", "Web images");

const res = await fetch("https://api.switchfile.io/v1/convert?wait=30", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SWITCHFILE_API_KEY}` },
  body: form,
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
console.log((await res.json()).to);

With cURL, use --form-string for the name. With -F, cURL reads @ and < at the start of a value as a file and treats ;type= and commas in the value as options.

Rules#

• to can be left out. If you send it, it must match the target of the preset.
• Values in options override the same settings of the preset, the others stay. {"preset": "Web images", "options": {"quality": 90}} keeps the size of the preset and changes only the quality.
• A preset with an input format only takes files of that format. Other files fail with 422 INVALID_DATA and an error under preset. A preset without an input format works for every file that can be converted to its target.
• An unknown ID or name fails with 422 PRESET_NOT_FOUND.

Presets are part of the simple API. In jobs and tasks (v2), put the options on the convert task instead.