Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.convertly.sh/llms.txt

Use this file to discover all available pages before exploring further.

Use synchronous endpoints when your app needs converted files in the same request. Convertly handles upload intake, format validation, resizing, compression, optional storage records, and download URL generation. For larger batches or long-running work, use Async Jobs.

Convert

Change the output format, resize images, normalize orientation, and control output quality.

Compress

Keep the file format compatible while reducing size by quality or target byte size.

​
When to use it

Use synchronous conversion for profile uploads, asset optimization, document export tools, admin dashboards, and user-facing forms where the file count is modest and the user is waiting for the result. If your user can leave the page, if the file is large, or if you are processing many files at once, prefer async jobs. Jobs return a jobId immediately and let Convertly workers finish the media processing in the background.

​
Convert files

POST /api/convert accepts one or more files fields and conversion settings. 
curl -X POST "https://convertly.sh/api/convert" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "files=@./hero.png" \
  -F "format=webp" \
  -F "compression=82" \
  -F "resize=website" \
  -F "autoOrient=true"
Raster-to-SVG conversion preserves flat color layers by default. Add mono=true only when you want the older black-and-transparent tracing behavior: 
curl -X POST "https://convertly.sh/api/convert" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "files=@./logo.png" \
  -F "format=svg" \
  -F "compression=82" \
  -F "resize=original" \
  -F "mono=true"
For per-file settings, send JSON arrays: 
curl -X POST "https://convertly.sh/api/convert" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "files=@./hero.png" \
  -F "files=@./avatar.jpg" \
  -F 'formats=["webp","avif"]' \
  -F 'compressions=[82,76]' \
  -F 'resizes=["website","instagram"]' \
  -F 'resizeWidths=[null,null]' \
  -F 'resizeHeights=[null,null]' \
  -F 'autoOrients=[true,true]' \
  -F 'monos=[false,false]'

​
Compress files

POST /api/compress keeps the output format compatible with the original file. 
curl -X POST "https://convertly.sh/api/compress" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "files=@./photo.jpg" \
  -F "mode=quality" \
  -F "quality=76" \
  -F "lossless=false" \
  -F "stripMetadata=true"
For target-size compression: 
curl -X POST "https://convertly.sh/api/compress" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "files=@./photo.jpg" \
  -F "mode=target-size" \
  -F "targetBytes=250000"

​
Per-file settings

When you upload multiple files, you can either send one setting for the full batch or JSON arrays with one value per file. Convertly validates that every uploaded file has matching settings before processing starts. For example, if you upload two files and send formats, compressions, or monos, each array must contain two values.

​
Supported output formats

jpg, png, webp, avif, tiff, gif, heif, svg, pdf, mp4, webm, mov, mp3, wav, ogg, m4a, flac, zip, tar, tgz, 7z, rar, gz, bz2, xz.

​
Resize modes

original, website, email, instagram, linkedin, ecommerce, square, width, height.

​
SVG tracing

When format=svg, Convertly traces raster images into layered vector paths. Color is preserved by default. Use mono=true or per-file monos=[true,false] for monochrome tracing.

​
Response fields

FieldDescription
filenameConverted or compressed output filename.
originalSizeInput file size in bytes.
finalSizeOutput file size in bytes.
savedPercentSize reduction percentage.
mimeTypeOutput MIME type.
downloadUrlData URL or signed storage URL for the generated file.
storedFileIdStored file ID when the user is authenticated and the file is saved.

​
Storage behavior

API-key requests return downloadable results without saving files by default. Add saveToStorage=true when your product needs Convertly to persist uploads and outputs. 
curl -X POST "https://convertly.sh/api/convert" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "files=@./hero.png" \
  -F "format=webp" \
  -F "resize=website" \
  -F "saveToStorage=true"