Convert

Endpoint

Converts one file to the format you name and returns the result as the response body. Nothing is stored. The endpoint accepts images, PDFs, audio, tables and fonts. Video and office documents must be sent as a job with operation: "convert".

A conversion aims to keep quality, not to save bytes. It uses fixed, high settings (see quality when converting), and it returns the converted file even when that file is larger than the input. To change the format and control the size, use compress with a format option.

Request

Authenticate with Authorization: Bearer $SMOL_API_KEY. Send the file in one of two forms. The file can be up to 25 MB (26,214,400 bytes), or 10 MB with a test key.

Raw body

The request body is the bytes of the file. Options go in the query string. Give the file's name with ?filename= or with a Content-Disposition request header. If both are present, the query parameter is used.

POST /v1/convert?to=webp&filename=photo.jpg HTTP/1.1
Host: api.smolmac.com
Authorization: Bearer $SMOL_API_KEY
Content-Length: 1614027

<the bytes of the file>

• Any Content-Type other than multipart/form-data is treated as a raw body. The header's value is not used to detect the file type.
• Send a Content-Length header. It is required with a test key. With a live key a body without it is accepted and streamed.

Multipart form

Send multipart/form-data with these parts:

Options may also be given in the query string of a multipart request. Where an option appears in both places, the query string wins, field by field.

The file name

The name is optional for most files. It is used for two things: to tell apart formats that share a container or have no signature (see type detection), and to name the file that comes back. Only the last path component is used.

Options

In a multipart request the same options go in the options part as {"convert":{"to":"webp"}}. These spellings of a target are also accepted: jpeg for jpg, tif for tiff, heif for heic, htm for html, markdown for md, and jsonl for ndjson.

Targets

The targets allowed depend on the kind of file you send.

• A target outside the list for the file's kind is refused with unsupported_target. The message lists the targets that are allowed.
• Camera RAW files are refused with unsupported_input. Use compress, which decodes them.
• An animated GIF or WebP keeps its frames when the target is GIF or WebP. For any other target the first frame is used, and the result carries a warning.
• A font conversion changes the container only. In a table conversion every cell is text.
• A JSON table input is an array of objects, an array of arrays, or an object that holds such an array under data or rows. NDJSON input has one such value per line. JSON and NDJSON output is one object per row, keyed by the cells of the first row.

Response

Status 200. The body is the converted file. The details are in the headers. Smol-Kept-Original is always false on this endpoint.

Errors

An error has a JSON body in place of the file. See Errors for the format and for what to do about each code.

Examples

Convert a PNG to WebP:

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&filename=diagram.png", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SMOL_API_KEY}` },
  body: await readFile("diagram.png"),
});
if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.code}: ${error.message}`);
}

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

import os
import requests

with open("diagram.png", "rb") as f:
    response = requests.post(
        "https://api.smolmac.com/v1/convert",
        params={"to": "webp", "filename": "diagram.png"},
        headers={"Authorization": f"Bearer {os.environ['SMOL_API_KEY']}"},
        data=f.read(),
    )
if not response.ok:
    error = response.json()["error"]
    raise RuntimeError(f"{error['code']}: {error['message']}")

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

Render page 2 of a PDF as a PNG at 200 dpi:

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

Convert a CSV file to a spreadsheet. The file name is needed so that the CSV is recognised:

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

Example response

HTTP/1.1 200 OK
Content-Type: image/webp
Content-Length: 96274
Content-Disposition: attachment; filename="diagram.webp"; filename*=UTF-8''diagram.webp
Cache-Control: no-store
Smol-Version: 2026-10-01
RateLimit-Limit: 40
RateLimit-Remaining: 39
RateLimit-Reset: 1
Smol-Request-Id: req_Bv2Kq9XtL0mZs4Wd7HcR
Smol-Original-Size: 842113
Smol-Output-Size: 96274
Smol-Savings-Percent: 88.6
Smol-Output-Format: webp
Smol-Kept-Original: false
Smol-Billed: true
Smol-Result: {"kind":"image","input_format":"png","output_format":"webp","original_size":842113,"output_size":96274,"savings_percent":88.6,"kept_original":false,"increased":false,"width":1600,"height":900,"pages":null,"duration_seconds":null,"video_codec":null,"warnings":[]}

<the bytes of diagram.webp>