API reference

Capabilities

GET /v1/capabilities lists the operations, formats, option values and plan limits of the API, without a key.

Endpoint

GET/v1/capabilities

Returns a description of what the API can do: its operations, the formats it reads and writes, the values each option accepts, and the limits of each plan. It needs no API key. It describes the product, not your account, so the response is the same for every caller.

bash

curl "https://api.smolmac.com/v1/capabilities"

The response carries Cache-Control: public, max-age=300, so it may be cached for five minutes. Any method other than GET returns status 405.

Response

200 OK

{
  "object": "capabilities",
  "standard": "v1",
  "operations": ["compress", "convert", "strip_metadata"],
  "sync": {
    "max_bytes": 26214400,
    "kinds": ["image", "pdf", "audio", "table", "font"]
  },
  "compress": {
    "image": {
      "inputs": ["jpg", "png", "webp", "avif", "heic", "gif", "tiff", "bmp", "cr2", "nef", "arw", "dng", "orf", "rw2", "raf"],
      "formats": ["original", "jpg", "png", "webp", "avif", "heic", "gif"],
      "quality": { "min": 0, "max": 100, "default": 75 },
      "resize": {
        "modes": ["fit", "fill", "width", "height"],
        "default": { "mode": "fit", "width": 2000, "height": 2000 }
      }
    },
    "pdf": {
      "quality": ["tiny", "small", "medium", "large", "original"],
      "default": "medium"
    },
    "video": {
      "inputs": ["mp4", "mov", "avi", "mkv", "webm", "flv", "wmv", "m4v", "mpg", "3gp"],
      "formats": ["mp4", "mov", "webm", "mkv"],
      "codecs": ["h265", "h264", "vp9"],
      "quality": ["tiny", "low", "balanced", "high", "maximum", "web"],
      "resolution": ["original", "3840", "1920", "1280", "854"]
    },
    "audio": {
      "inputs": ["mp3", "aac", "wav", "flac", "m4a", "ogg", "opus", "wma"],
      "formats": ["aac", "m4a", "mp3", "ogg", "opus", "wav", "flac", "alac", "original"],
      "quality": ["tiny", "low", "balanced", "high", "maximum"]
    }
  },
  "convert": {
    "image": ["jpg", "png", "webp", "avif", "heic", "tiff", "bmp", "gif", "pdf"],
    "pdf": ["png", "jpg"],
    "word": ["pdf", "docx", "odt", "rtf", "txt", "html"],
    "sheet": ["pdf", "xlsx", "ods", "csv", "html"],
    "presentation": ["pdf", "pptx", "odp"],
    "video": ["mp4", "mov", "webm", "mkv"],
    "audio": ["m4a", "mp3", "wav", "flac", "ogg"],
    "table": ["csv", "tsv", "json", "ndjson", "html", "md", "xlsx"],
    "font": ["ttf", "otf", "woff", "woff2"]
  },
  "strip_metadata": { "kinds": ["image", "pdf"] },
  "plans": {
    "payg": {
      "requests_per_second": 5,
      "concurrent_jobs": 3,
      "max_sync_bytes": 26214400,
      "max_async_bytes": 524288000,
      "max_video_seconds": 600
    },
    "starter": {
      "requests_per_second": 20,
      "concurrent_jobs": 10,
      "max_sync_bytes": 26214400,
      "max_async_bytes": 2147483648,
      "max_video_seconds": 3600
    },
    "growth": {
      "requests_per_second": 50,
      "concurrent_jobs": 30,
      "max_sync_bytes": 26214400,
      "max_async_bytes": 5368709120,
      "max_video_seconds": 10800
    },
    "scale": {
      "requests_per_second": 150,
      "concurrent_jobs": 100,
      "max_sync_bytes": 26214400,
      "max_async_bytes": 5368709120,
      "max_video_seconds": 10800
    },
    "enterprise": {
      "requests_per_second": 500,
      "concurrent_jobs": 500,
      "max_sync_bytes": 26214400,
      "max_async_bytes": 5368709120,
      "max_video_seconds": 10800
    }
  }
}

The real response is compact JSON on one line. It is laid out here for reading.

Fields

Field	Type	Description
object	string	Always "capabilities".
standard	string	The version of the compression standard the API applies. "v1".
operations	array of strings	The operations, as named in a job. The direct endpoints are /v1/compress, /v1/convert and /v1/strip-metadata.
sync.max_bytes	integer	The largest file a direct request accepts, in bytes.
sync.kinds	array of strings	The kinds of file a direct request accepts. Any other kind needs a job.
compress.image	object	`inputs`: the image formats that can be compressed. `formats`: the values of `image.format`. `quality`: the range and default of `image.quality`. `resize`: the resize modes and the default box.
compress.pdf	object	`quality`: the values of `pdf.quality`. `default`: the default preset.
compress.video	object	The video formats that can be compressed, and the values of `video.format`, `video.codec`, `video.quality` and `video.resolution`.
compress.audio	object	The audio formats that can be compressed, and the values of `audio.format` and `audio.quality`.
convert	object	For each kind of input, the targets that `convert.to` accepts. The keys are the values of `kind` in the result object.
strip_metadata.kinds	array of strings	The kinds of file that strip metadata accepts.
plans	object	For each plan: sustained requests per second, the number of jobs that may be queued or processing at once, the largest direct file and the largest job file in bytes, and the longest video or audio in seconds. The full set of limits is in Limits.

How to use it

Build a format picker from the lists, so that it stays correct when formats are added.
Decide between a direct request and a job: use a job when the file is larger than sync.max_bytes or its kind is not in sync.kinds.
Check a request against the lists before you send it, to fail early with your own message.

The response does not say which plan your account is on. The dashboard shows your plan.