jobId, and let Convertly workers process the batch in the background. Jobs are useful when a conversion or media tool may take longer than a user should wait on a single request.
Jobs are storage-backed because workers need persisted source files. For storage-free processing, use synchronous
POST /api/convert or POST /api/compress.Why jobs exist
Synchronous APIs are convenient, but media processing can be slow when files are large, batches are wide, or outputs need heavier work. The jobs API moves that work into a queue so your app can stay responsive while Convertly handles processing.Job lifecycle
1
Upload and queue
Your app sends files and settings to
POST /api/jobs, or sends async=true to a media tool endpoint. Convertly stores the source files and creates a pending job.2
Worker processing
A worker picks up the job, processes each file, and updates progress as files complete or fail.
3
Result retrieval
Your app polls
GET /api/jobs/{id} or reacts to webhooks to retrieve completed results.Job statuses
When to use jobs
Use jobs for bulk imports, agency/client file batches, large video or audio files, workflow builders, user dashboards with progress states, or anything that should survive a browser refresh. Some media tools require a job when the request is too expensive for a normal HTTP response. If a synchronous media-tool request returns422 with code: "async_required", resend the same request with async=true. This applies to video/audio conversion, audio concatenation, video watermarking, large trims, large audio extraction, large GIF previews, large PDF previews, and frame-sequence exports beyond direct-download limits.
Async media tools
Media tool endpoints can be queued directly:Idempotency and callbacks
Send anIdempotency-Key header when creating jobs from retry-prone systems. If the same key is sent again for the same account, Convertly returns the existing job instead of creating duplicate work or charging another media operation.
callbackUrl and callbackSecret when creating the job. Convertly signs the callback as HMAC_SHA256(timestamp.body) and sends it in Convertly-Signature.