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 this path to make your first authenticated request. Convertly accepts a file, processes it on the server, and returns a result your app can download or pass to a user.

Create an API key

Open the Convertly dashboard, go to API settings, and create a key. The token is only shown once.
cvly_...

Store the key

Store it as an environment variable on your server.
export CONVERTLY_API_KEY="cvly_your_api_key"

Convert a file

Send a multipart/form-data request to /api/convert.
curl -X POST "https://convertly.sh/api/convert" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "files=@./input.png" \
  -F "format=webp" \
  -F "compression=82" \
  -F "resize=original" \
  -F "autoOrient=true"
The response includes converted file metadata and a downloadUrl. For raster-to-SVG, use format=svg. Convertly preserves color by default; add mono=true only when you want black-and-transparent tracing.

​
How Convertly works

  1. Your app sends media to Convertly with the output settings you want.
  2. Convertly validates the request against your account plan and file limits.
  3. Convertly processes the file and returns output metadata plus a downloadUrl.
  4. If you set saveToStorage=true, Convertly also stores the upload and output in your workspace.

​
Understand the result

For synchronous conversion and compression, Convertly returns a files array. Each item includes the output filename, original size, final size, MIME type, savings percentage, and a download URL. API-key requests do not save files by default. Add saveToStorage=true only when your workflow needs files stored in Convertly.

​
Queue a larger job

Use /api/jobs when files should be uploaded once, processed by Convertly workers, and checked later from your app. 
curl -X POST "https://convertly.sh/api/jobs" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "jobType=convert" \
  -F "saveToStorage=true" \
  -F "files=@./image-1.png" \
  -F "files=@./image-2.png" \
  -F 'formats=["webp","jpg"]'
Then poll the returned job: 
curl "https://convertly.sh/api/jobs/{jobId}" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY"

​
Choose an endpoint

NeedEndpoint
Convert immediatelyPOST /api/convert
Compress immediatelyPOST /api/compress
Queue a batchPOST /api/jobs
Check job statusGET /api/jobs/{id}
Convert currencyPOST /api/currency/convert