Documentation

SmallConvert API

Convert PNG, JPEG, WebP, and AVIF with one straightforward API. Files upload directly to Cloudflare, so they never pass through your application server.

QuickstartGet an API key

Quickstart

Create a job with the source file metadata and the format you want back. Authentication is optional for the free tier.

curl
curl -X POST https://www.smallconvert.com/api/v1/convert \
  -H "content-type: application/json" \
  -H "authorization: Bearer $SMALLCONVERT_API_KEY" \
  -d '{
    "filename": "photo.png",
    "bytes": 1842310,
    "contentType": "image/png",
    "targetFormat": "webp",
    "quality": 82
  }'
No key yet? Remove the authorization header to use the anonymous free tier.

How it works

01

Create

Send metadata and choose an output format.

02

Upload

PUT the file directly to the returned upload URL.

03

Complete

Tell SmallConvert the upload has finished.

04

Download

Poll the job until the download URL is ready.

POST/api/v1/convert

Creates a conversion job and returns the URLs needed to upload, complete, and poll it.

filename

string · required

Original filename with its extension.

bytes

number · required

Exact source file size in bytes.

contentType

string · required

Source image MIME type.

targetFormat

string · required

png, jpeg, webp, or avif.

quality

number · optional

Output quality from 1–100.

201 response
{
  "id": "job_7fq2m4x9",
  "status": "uploading",
  "upload_url": "https://cdn.smallconvert.cloud/...",
  "upload_method": "PUT",
  "complete_url": "/api/v1/jobs/job_7fq2m4x9/complete",
  "poll_url": "/api/v1/jobs/job_7fq2m4x9"
}

POST/api/v1/jobs/:id/complete

Call this after the direct upload succeeds. The image is then queued for conversion.

202 response
{
  "id": "job_7fq2m4x9",
  "status": "queued",
  "poll_url": "/api/v1/jobs/job_7fq2m4x9"
}

GET/api/v1/jobs/:id

Poll until the status is done. A finished job includes its download URL.

200 response
{
  "id": "job_7fq2m4x9",
  "status": "done",
  "source_format": "png",
  "target_format": "webp",
  "output_bytes": 428416,
  "took_ms": 1904,
  "download_url": "/api/v1/jobs/job_7fq2m4x9/download"
}

Supported formats

PNGLossless images and transparency
JPEGCompact photography
WebPEfficient web images
AVIFNext-generation compression

Errors

400Malformed or unsupported request.
401Invalid or deleted API key.
402Monthly conversion quota exhausted.
403Missing scope or suspended account.
413File exceeds the plan size limit.
429Rate limit exceeded.
503Conversion service unavailable.

Rate limits

Limits use fixed one-hour windows. Anonymous requests are counted by IP; authenticated requests are counted by API key.

response headers
x-ratelimit-limit: 2000
x-ratelimit-remaining: 1994
x-ratelimit-reset: 1788400800