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.

Convertly is a media toolkit, not just a format switcher. The API can power upload cleanup, optimization, batch processing, file packaging, and delivery workflows for products that receive user media. Media tool endpoints accept multipart uploads or sourceUrl remote input. Add async=true to queue heavier work such as video watermarking, PDF previews, poster frames, audio extraction, or large thumbnails. Queued media tools return a jobId and complete through the same GET /api/jobs/{id} endpoint as conversion jobs.

​
Current tools

ToolWhat it does
Format conversionConverts images, video, audio, documents, and archives into supported output formats.
CompressionReduces file size with quality-based or target-size compression.
Resize presetsCreates web, email, social, ecommerce, square, width-based, or height-based image outputs.
Archive extractionAccepts ZIP uploads and processes the contained files when the output is not another archive.
Archive creationPackages generated files into downloadable archives for delivery workflows.
Async jobsProcesses larger batches through background workers.
Optional storageSaves files only when the workflow needs stored outputs or async processing.
Image metadata removalStrip EXIF/GPS/device metadata before publishing user uploads.
Background removalSegment foreground subjects and return transparent product or creator images.
Thumbnail generationCreate thumbnails, previews, and poster images for dashboards, galleries, and video libraries.
WatermarkingAdd brand, creator, or marketplace watermarks to images and short videos.
PDF to imageTurn PDF pages into PNG or JPG previews for document workflows.
Image to PDFPackage uploaded images into a single PDF for delivery, receipts, or client review.
Video thumbnail and poster framesExtract a frame at a timestamp for upload previews and content libraries.
Audio extractionPull audio from video files for podcasts, clips, transcripts, and review workflows.
Media inspectionReturn dimensions, duration, codecs, file size, color space, and format metadata before processing.
Remote source inputProcess files from sourceUrl without forcing your app to re-upload bytes.
Async media toolsQueue thumbnail, watermark, PDF preview, poster-frame, audio extraction, metadata stripping, image-to-PDF, and inspection jobs.

​
API endpoints

EndpointPurpose
POST /api/media/thumbnailGenerate image or video thumbnails.
POST /api/media/pdf-previewRender a PDF page preview.
POST /api/media/image-to-pdfCreate a PDF from one or more images.
POST /api/media/strip-metadataRemove metadata from images, video, and audio files.
POST /api/media/poster-frameExtract a video poster frame.
POST /api/media/extract-audioExtract audio from video.
POST /api/media/watermarkApply text or logo watermarks to images and videos.
POST /api/media/inspectReturn media metadata, streams, dimensions, duration, and codecs.
POST /api/media/trimCut video or audio by start time and duration.
POST /api/media/gifCreate an animated GIF preview from a video.
POST /api/media/storyboardGenerate a tiled frame contact sheet from a video.
POST /api/media/transformResize, crop, rotate, flip, and re-encode images.
POST /api/media/remove-backgroundRemove an image background and return a transparent foreground.
POST /api/media/signed-transformGenerate CDN-style signed transform URLs for cacheable image derivatives.

​
Common request options

FieldTypeApplies toDescription
filefileAll single-file toolsMultipart upload input.
filesfile[]Image to PDFMultipart image uploads.
sourceUrlstringAll toolsRemote HTTP(S) file input.
asyncbooleanAll toolsQueue the tool as a background job.
forcebooleanBackground removalRe-segment an image even when it already has transparency.
curl -X POST "https://convertly.sh/api/media/poster-frame" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "sourceUrl=https://cdn.example.com/video.mp4" \
  -F "timestamp=4" \
  -F "async=true"

{
  "jobId": "65f3a673-69d6-42cc-8f6b-fc5a21fb5a8e",
  "status": "pending",
  "tool": "poster-frame"
}

Build with media tools

See request examples and response shapes for the Media Tools API.
These tools are easy for customers to understand, easy to document, and naturally increase usage without changing Convertly’s core positioning.

​
Transform chains and presets

The transform endpoint can resize, crop, change format, and set quality in one request. Use this for upload pipelines where a single source image needs a production-ready derivative. 
curl -X POST "https://convertly.sh/api/media/transform" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "sourceUrl=https://cdn.example.com/photo.jpg" \
  -F "cropWidth=1600" \
  -F "cropHeight=900" \
  -F "width=1200" \
  -F "height=630" \
  -F "fit=cover" \
  -F "format=webp" \
  -F "quality=84"
Smart presets are shortcuts for common business outputs:
PresetOutput
ecommerce1600px product image, WebP, quality 84.
avatar512x512 cover crop, WebP, quality 86.
blog-hero1600x900 cover crop, WebP, quality 84.
social-preview1200x630 cover crop, JPG, quality 88.
curl -X POST "https://convertly.sh/api/media/transform" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "sourceUrl=https://cdn.example.com/product.png" \
  -F "preset=ecommerce"

​
Background removal

Use POST /api/media/remove-background for product images, profile photos, thumbnails, and marketplace uploads where the foreground subject should stay and the background should become transparent. PNG is the default recommendation because it preserves transparency. For high-resolution images or batches, send async=true. If the source image already has meaningful transparency, Convertly preserves the existing cutout instead of running segmentation again. Send force=true only when you intentionally want to re-segment an already-transparent image. 
curl -X POST "https://convertly.sh/api/media/remove-background" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "file=@./product.jpg" \
  -F "format=png" \
  -F "model=medium" \
  -F "async=true"
Supported output formats are png, webp, and jpg. Use png or webp when you need transparency.

​
Signed transform URLs

Create a signed URL when your app wants cacheable, CDN-style derivatives without exposing API keys to browsers. 
curl -X POST "https://convertly.sh/api/media/signed-transform" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceUrl": "https://cdn.example.com/product.jpg",
    "preset": "ecommerce",
    "expiresIn": 3600
  }'
The response returns a URL that can be used directly in an image tag until it expires.

​
CDN image URLs for stored files

For files already in Convertly Storage, create a signed CDN-style transform URL: 
curl -X POST "https://convertly.sh/api/cdn/image" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileId": "stored-file-id",
    "width": 800,
    "format": "webp",
    "quality": 86
  }'
The returned URL has a browser-friendly shape such as /api/cdn/image/{fileId}?w=800&format=webp&q=86&... and can be used in image tags or cached by a CDN until it expires.