Convert files

The convert endpoint

Send the file as the request body and name the target format with to. The converted file is the response body.

curl -X POST "https://api.smolmac.com/v1/convert?to=webp" \
  -H "Authorization: Bearer $SMOL_API_KEY" \
  --data-binary @diagram.png \
  -o diagram.webp

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

const response = await fetch("https://api.smolmac.com/v1/convert?to=webp", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SMOL_API_KEY}` },
  body: await readFile("diagram.png"),
});
if (!response.ok) throw new Error((await response.json()).error.message);

await writeFile("diagram.webp", Buffer.from(await response.arrayBuffer()));

import os, requests

with open("diagram.png", "rb") as f:
    response = requests.post(
        "https://api.smolmac.com/v1/convert",
        params={"to": "webp"},
        headers={"Authorization": f"Bearer {os.environ['SMOL_API_KEY']}"},
        data=f,
    )
response.raise_for_status()

with open("diagram.webp", "wb") as out:
    out.write(response.content)

to is the short form of the option convert.to. It is required: without it the request fails with 400 invalid_options and param set to convert.to. Common alternative spellings are accepted: jpeg, tif, heif, htm, markdown and jsonl. A preset named with ?preset= can supply the target in place of to.

Conversion aims to keep the content as it is in a new format. It uses fixed, high-quality encoder settings, and the image, audio and video options do not apply. The output can be larger than the input. If the goal is a smaller file, use POST /v1/compress with image.format or audio.format instead.

What converts to what

The API works out what kind of file it has from the content of the file. The kind decides which targets are allowed and whether the conversion runs as a direct request or as a job.

The same lists are available from GET /v1/capabilities, which needs no key. See Capabilities.

A target that is not in the row for the input fails, and the message lists what is allowed:

{
  "error": {
    "type": "invalid_request_error",
    "code": "unsupported_target",
    "message": "A pdf file can be converted to: png, jpg.",
    "param": null,
    "request_id": "req_Jb6Ys1MwD4kTq9ZfC2hA",
    "doc_url": "https://smolmac.com/docs/reference/errors#unsupported_target"
  }
}

Images

• JPEG, WebP, AVIF, HEIC and TIFF output is written at quality 95.
• Orientation is applied to the pixels, and wide-gamut images are converted to sRGB, so the picture looks the same in the new format.
• Transparency written to JPEG is flattened onto white.
• The image is not resized, and its metadata is not removed.
• An animated GIF or WebP stays animated when the target is gif or webp. For any other target the first frame is used and the result carries a warning.
• to=pdf produces a one-page PDF that holds the image. A JPEG is placed in the PDF as it is, without being re-encoded.
• to=heic is in limited preview. Unless HEIC output is enabled for the account, the request is refused with 403 feature_not_enabled. Converting from HEIC to another format works on every account.

Camera RAW files are not accepted by convert (415 unsupported_input). Send them to POST /v1/compress with image.format, which decodes RAW. See Compress images.

PDF pages to images

A PDF converts to PNG or JPEG one page at a time. Two more options apply:

curl -X POST "https://api.smolmac.com/v1/convert?to=png&page=3&dpi=200" \
  -H "Authorization: Bearer $SMOL_API_KEY" \
  --data-binary @report.pdf \
  -o report-page-3.png

The pixel size of the image is the page size in inches times the resolution. An A4 page (8.27 by 11.69 inches) at the default 144 dpi is about 1190 by 1684 pixels. At 72 dpi it is half that in each direction. JPEG output is written at quality 95.

The result object reports the size of the image in width and height, and the number of pages in the PDF in pages. To render a whole document, convert page 1, read pages from the Smol-Result header, then send one request for each remaining page.

A page number beyond the last page fails with 400 invalid_options. A PDF that needs a password fails with 422 encrypted_pdf.

Tables

Tabular data converts between CSV, TSV, JSON, NDJSON, HTML and Markdown, and to XLSX. The input must be UTF-8 text.

curl -X POST "https://api.smolmac.com/v1/convert?to=xlsx&filename=orders.csv" \
  -H "Authorization: Bearer $SMOL_API_KEY" \
  --data-binary @orders.csv \
  -o orders.xlsx

• Every cell is text. Numbers and dates are not interpreted, so 007 stays 007 and nothing is reformatted.
• JSON input is an array of objects or an array of arrays, or an object that holds such an array under data or rows. NDJSON input is one object or array per line. With objects, the keys become the columns.
• JSON and NDJSON output use the first row as the keys: an array of objects for JSON, one object per line for NDJSON. Every value is a string.
• HTML input is read from the first table in the document. Markdown input is read from its pipe table.
• In CSV and TSV input, rows that are entirely empty are dropped.

An Excel file (.xlsx, .xls) is a spreadsheet, not a table in this sense. It converts through a job, as described below.

Fonts

Font conversion changes the container: plain (TTF, OTF), WOFF or WOFF2. Every table in the font is kept and the glyph outlines are not converted.

curl -X POST "https://api.smolmac.com/v1/convert?to=woff2" \
  -H "Authorization: Bearer $SMOL_API_KEY" \
  --data-binary @Inter-Regular.ttf \
  -o Inter-Regular.woff2

The useful conversions are to WOFF2 or WOFF for the web, and back to TTF or OTF for desktop use. Converting between ttf and otf does not turn TrueType outlines into PostScript outlines or the reverse. The font data stays the same under a different extension.

Audio

Audio conversion uses one fixed setting for each target:

To choose the bitrate, channels or sample rate, use compress with audio.format. See Audio.

Office documents and video

Word documents, spreadsheets, presentations and video can take minutes to convert, so they do not run as direct requests. Sent to POST /v1/convert, they are refused:

{
  "error": {
    "type": "invalid_request_error",
    "code": "use_async_job",
    "message": "A word file cannot be processed in a direct request. Upload it and create a job instead.",
    "param": null,
    "request_id": "req_Lx3Tn7RvB0cWm5QdH8sE",
    "doc_url": "https://smolmac.com/docs/reference/errors#use_async_job"
  }
}

Upload the file and create a job with the operation convert. The target goes in options.convert.to:

curl -X POST "https://api.smolmac.com/v1/jobs" \
  -H "Authorization: Bearer $SMOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "convert",
    "input": { "upload": "upl_Zk3Vb9QeT1mXc7HsW0yN" },
    "options": { "convert": { "to": "pdf" } }
  }'

Large files and jobs covers the upload, waiting for the job, and the download. A document that is damaged or password protected fails with processing_failed.

Video conversion re-encodes to H.264 with AAC audio for mp4, mov and mkv, and to VP9 with Opus audio for webm. Video is in limited preview: unless it is enabled for the account, a video job fails with feature_not_enabled. See Video.

Billing

Failed requests are free. A PDF page rendered to an image counts as one image, not as PDF pages. More in Billing.