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.

Async jobs let your app upload files once, receive a 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.

​
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

StatusMeaning
pendingThe job has been accepted and is waiting for a worker.
processingA worker is actively processing files.
completedProcessing finished and results are available.
failedThe job could not be completed. Check errorMessage.

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

​
Async media tools

Media tool endpoints can be queued directly: 
curl -X POST "https://convertly.sh/api/media/extract-audio" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "sourceUrl=https://cdn.example.com/interview.mp4" \
  -F "format=mp3" \
  -F "async=true"
The response contains the same job identifier used by conversion jobs: 
{
  "jobId": "65f3a673-69d6-42cc-8f6b-fc5a21fb5a8e",
  "status": "pending",
  "tool": "extract-audio"
}
Poll the job endpoint: 
curl "https://convertly.sh/api/jobs/65f3a673-69d6-42cc-8f6b-fc5a21fb5a8e" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY"

​
Idempotency and callbacks

Send an Idempotency-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 API request. 
curl -X POST "https://convertly.sh/api/jobs" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -H "Idempotency-Key: import-42-image-7" \
  -F "files=@./hero.jpg" \
  -F "saveToStorage=true" \
  -F "formats=[\"webp\"]"
For one-off integrations, pass callbackUrl and callbackSecret when creating the job. Convertly signs the callback as HMAC_SHA256(timestamp.body) and sends it in Convertly-Signature.