API 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

Layer	What you get	Dashboard	Docs
Deliver	On-the-fly image and video transforms at the edge, smart cropping, signed URLs	Image CDN · Transform Lab	Image CDN
Process	Convert, compress, thumbnails, trim, GIFs, background removal, inspection	Convert · Compress · Forma AI	Media conversion · Media tools · Forma AI
Ingest	Workspace storage, folders, imports, origin sources for the CDN	Assets · Sources	Files & storage · Transfer API
Automate	Async batches, visual workflows, signed webhooks	Workflows · History	Async 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.

Option	Behavior
`saveToStorage=true`	Also store the upload and output in your Convertly workspace
`format=svg`	Raster-to-SVG tracing (color by default; add `mono=true` for black-and-transparent)
`POST /api/compress`	Same 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:

Area	What to do
Assets	Upload files, organize folders, share read-only links, import from cloud connections
Convert / Compress	Run one-off batches with the same options as the API
Forma AI	Generate, edit, upscale, and restyle images in the studio
Image CDN	Manage delivery namespaces, origins, presets, custom domains, cache purge, and Transform Lab
Streams	Upload source video and publish adaptive HLS playback
Workflows	Chain convert, compress, tools, and storage steps; test runs before going live
Integrations	Connect WordPress sites with scoped storage and CDN provisioning
History	Review 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

Need	Endpoint
Convert immediately	`POST /api/convert`
Compress immediately	`POST /api/compress`
Run a media tool (thumbnail, trim, GIF, watermark, …)	`POST /api/media/{tool}`
Forma AI transforms	`POST /api/ai/transform`
Queue a batch	`POST /api/jobs`
Check job status	`GET /api/jobs/{id}`
Upload into storage	`POST /api/files` or `POST /api/uploads` (+ `POST /api/uploads/complete`)
Browse files and folders	`GET /api/files` · `GET /api/folders`
Import from URL, ZIP, or cloud	`POST /api/transfer`
Edge image/video transforms	`GET /cdn/v1/{namespace}/…`
Manage CDN keys, origins, presets	`/api/delivery-keys` · `/api/cdn-origins` · `/api/cdn-presets`
Adaptive video playback	`POST /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.

Getting Started

Image CDN

Media Platform

SDKs & Integrations

Resources

Platform at a glance

Create an API key

Choose your first path

Convert a file (API)

Deliver through Image CDN

Use the dashboard

Queue background work

Convert a file with the API

Media conversion reference

Deliver with the Image CDN

End-to-end CDN setup guide

Use the dashboard without code

Dashboard workflows

Queue a background job

API endpoint map

Next steps

Dashboard workflows

Authentication & limits

Plan limits

SDKs

API reference

Use cases

MCP for AI agents

Image CDN setup

​Platform at a glance

​Create an API key

​Choose your first path

Convert a file (API)

Deliver through Image CDN

Use the dashboard

Queue background work

​Convert a file with the API

Media conversion reference

​Deliver with the Image CDN

End-to-end CDN setup guide

​Use the dashboard without code

Dashboard workflows

​Queue a background job

​API endpoint map

​Next steps

Dashboard workflows

Authentication & limits

Plan limits

SDKs

API reference

Use cases

MCP for AI agents

Image CDN setup

Platform at a glance

Create an API key

Choose your first path

Convert a file with the API

Deliver with the Image CDN

Use the dashboard without code

Queue a background job

API endpoint map

Next steps