Skip to main content
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. For web delivery of images and video (responsive sizing, format negotiation, edge caching), use the Image CDN instead of converting files on every page load — especially when assets already live on your site or in Convertly Storage.
Use synchronous convert/compress when the user waits on the result. For web pages, prefer the Image CDN. For large batches, 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, image 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, if the source is video or audio, 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

For synchronous /api/convert, use image, document, and archive outputs such as jpg, png, webp, avif, tiff, gif, heif, svg, pdf, zip, tar, tgz, 7z, rar, gz, bz2, and xz. Use /api/jobs for video and audio outputs such as mp4, webm, mov, mp3, wav, ogg, m4a, and flac.

​
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"