Skip to main content
Quickstart
Convertly is a media platform for products that ingest, process, deliver, and automate files. Most teams start in one of four places: a direct API call, edge delivery through the Image CDN, the hosted dashboard, or a background job with webhooks.
API keys are shown once when created. Store yours in a server environment variable, never in client-side browser code.

​
Platform at a glance

LayerWhat you getDashboardDocs
DeliverOn-the-fly image and video transforms at the edge, smart cropping, signed URLsImage CDN · Transform LabImage CDN
ProcessConvert, compress, thumbnails, trim, GIFs, background removal, inspectionConvert · Compress · Forma AIMedia conversion · Media tools · Forma AI
IngestWorkspace storage, folders, imports, origin sources for the CDNAssets · SourcesFiles & storage · Transfer API
AutomateAsync batches, visual workflows, signed webhooksWorkflows · HistoryAsync jobs · Webhooks
Video streaming (adaptive HLS/DASH playback) lives under Streams in the dashboard. See Video streaming.

​
Create an API key

Open API keys in the dashboard

Sign in to convertly.sh/app, open your account menu (top right), choose Settings, then scroll to API keys.Workspace owners and admins can create and revoke keys. Other members can use existing keys.
cvly_...

Store the key on your server

export CONVERTLY_API_KEY="<paste-your-key-here>"
Send it on every API request:
Authorization: Bearer $CONVERTLY_API_KEY
x-api-key is also supported. See Authentication.
Image CDN signing keys are separate from API keys. Manage delivery namespaces and signing keys under Image CDN → Delivery in the dashboard.

​
Choose your first path

Convert a file (API)

Best when you need a processed file back immediately in your backend.

Deliver through Image CDN

Best when images or video already live on your site or in storage and you want transform URLs.

Use the dashboard

Best for manual batches, Forma AI, and testing transforms before you wire an integration.

Queue background work

Best for large batches that should finish after the upload request returns.

​
Convert a file with the API

Send multipart/form-data to POST /api/convert. Convertly validates your plan limits, processes the file, and returns metadata plus a downloadUrl. 
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 a files array. Each item has the output filename, MIME type, size savings, and downloadUrl.
OptionBehavior
saveToStorage=trueAlso store the upload and output in your Convertly workspace
format=svgRaster-to-SVG tracing (color by default; add mono=true for black-and-transparent)
POST /api/compressSame upload shape, optimized for compression instead of format conversion

Media conversion reference

Supported formats, resize modes, archives, and production patterns.

​
Deliver with the Image CDN

The Image CDN transforms images and video at request time. responsive sizes, format negotiation (format=auto), poster frames, trimmed clips, and smart cropping. You do not pre-generate variant files. 
https://cdn.convertly.sh/{namespace}/{fileIdOrSlug}?w=1200&format=auto&q=auto
https://cdn.convertly.sh/{namespace}/{videoId}?format=mp4&w=1280&so=0&du=30
https://cdn.convertly.sh/{namespace}/o/{originSlug}/products/hero.jpg?w=800&format=webp

Pick a delivery namespace

Open Image CDN → Delivery and copy your default namespace, or create one for each site or product surface.

Connect a source

Choose where Convertly fetches originals from:
  • Origin source. a deployed public HTTPS site, bucket, or CDN folder (Sources)
  • Convertly Storage. upload files in Assets and use the file UUID or CDN slug in URLs

Preview transforms

Use Image CDN → Transform Lab to preview posters, clips, and image transforms and copy a production-ready URL before you ship it.

Install the SDK (optional)

npm install @convertly-sh/image
Drop in <ConvertlyImage> or a framework loader so your app builds CDN URLs automatically.
Installing @convertly-sh/image only rewrites URLs. You still need an origin source or stored file before CDN URLs resolve. The SDK does not upload your repo or sync local folders.

End-to-end CDN setup guide

Origin vs storage, framework wiring, and verification checklist.

​
Use the dashboard without code

You can run most of the platform from convertly.sh/app before writing integration code:
AreaWhat to do
AssetsUpload files, organize folders, share read-only links, import from cloud connections
Convert / CompressRun one-off batches with the same options as the API
Forma AIGenerate, edit, upscale, and restyle images in the studio
Image CDNManage delivery namespaces, origins, presets, custom domains, cache purge, and Transform Lab
StreamsUpload source video and publish adaptive HLS playback
WorkflowsChain convert, compress, tools, and storage steps; test runs before going live
IntegrationsConnect WordPress sites with scoped storage and CDN provisioning
HistoryReview past jobs and workflow runs

Dashboard workflows

Build repeatable pipelines without deploying your own workers.

​
Queue a background job

Use POST /api/jobs when files should upload once, process on Convertly workers, and be polled later. 
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"]'
Poll status: 
curl "https://convertly.sh/api/jobs/{jobId}" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY"
Add webhooks when your app should react as soon as a job or workflow finishes.

​
API endpoint map

NeedEndpoint
Convert immediatelyPOST /api/convert
Compress immediatelyPOST /api/compress
Run a media tool (thumbnail, trim, GIF, watermark, …)POST /api/media/{tool}
Forma AI transformsPOST /api/ai/transform
Queue a batchPOST /api/jobs
Check job statusGET /api/jobs/{id}
Upload into storagePOST /api/files or POST /api/uploads (+ POST /api/uploads/complete)
Browse files and foldersGET /api/files · GET /api/folders
Import from URL, ZIP, or cloudPOST /api/transfer
Edge image/video transformsGET /cdn/v1/{namespace}/…
Manage CDN keys, origins, presets/api/delivery-keys · /api/cdn-origins · /api/cdn-presets
Adaptive video playbackPOST /api/video/streams · GET /video/v1/{playbackId}/…

​
Next steps

Dashboard workflows

Use the hosted app for files, Image CDN tabs, Forma AI, and repeatable workflows.

Authentication & limits

Headers, WordPress site tokens, and plan quotas.

Plan limits

Full quota tables for every plan tier.

SDKs

@convertly-sh/sdk, @convertly-sh/image, and PHP client.

API reference

Interactive schemas and playground examples.

Use cases

SaaS uploads, marketplaces, ecommerce, and agency batches.

MCP for AI agents

Let Cursor, Claude, and Codex work with approved local folders.

Image CDN setup

Wire origins, namespaces, and the SDK on your site.