Media API Tools

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. Some work is async-only when it is likely to run longer than a normal request or produce large output. Convertly returns 422 with code: "async_required" when a request must be queued. This protects your users from browser timeouts and keeps large generated files in the job system where they can be retried, stored, and delivered through webhooks. Sync remains available for small previews and direct downloads. Queue requests with async=true for video/audio conversion, audio concatenation, video watermarking, large trims, large audio extraction, large GIF previews, large PDF previews, and frame-sequence exports above the direct-download safety limits.

Current tools

Tool	What it does
Format conversion	Converts images, video, audio, documents, and archives into supported output formats.
Compression	Reduces file size with quality-based or target-size compression.
Resize presets	Creates web, email, social, ecommerce, square, width-based, or height-based image outputs.
Archive extraction	Accepts ZIP uploads and processes the contained files when the output is not another archive.
Archive creation	Packages generated files into downloadable archives for delivery workflows.
Async jobs	Processes larger batches through background workers.
Optional storage	Saves files only when the workflow needs stored outputs or async processing.
Image metadata removal	Strip EXIF/GPS/device metadata before publishing user uploads.
Background removal	Remove simple studio backgrounds, preserve existing transparent cutouts, or segment complex subjects with ML-powered edge refinement.
Thumbnail generation	Create thumbnails, previews, and poster images for dashboards, galleries, and video libraries.
Watermarking	Add brand, creator, or marketplace watermarks to images, short videos, and PDFs.
PDF to image	Turn PDF pages into PNG or JPG previews for document workflows.
Image to PDF	Package uploaded images into a single PDF for delivery, receipts, or client review.
Video thumbnail and poster frames	Extract a frame at a timestamp for upload previews and content libraries.
Video frame sequence export	Export numbered video frames into a downloadable ZIP folder with a manifest.
Audio extraction	Pull audio from video files for podcasts, clips, transcripts, and review workflows.
Media inspection	Return dimensions, duration, codecs, file size, color space, and format metadata before processing.
Remote source input	Process files from `sourceUrl` without forcing your app to re-upload bytes.
Async media tools	Queue thumbnail, watermark, PDF preview, poster-frame, frame sequence, audio extraction, metadata stripping, image-to-PDF, and inspection jobs.

API endpoints

Endpoint	Purpose
`POST /api/media/thumbnail`	Generate image or video thumbnails.
`POST /api/media/pdf-preview`	Render a PDF page preview.
`POST /api/media/image-to-pdf`	Create a PDF from one or more images.
`POST /api/media/strip-metadata`	Remove metadata from images, video, and audio files.
`POST /api/media/poster-frame`	Extract a video poster frame.
`POST /api/media/extract-audio`	Extract audio from video.
`POST /api/media/watermark`	Apply text or logo watermarks to images, videos, and every PDF page.
`POST /api/media/inspect`	Return media metadata, streams, dimensions, duration, and codecs.
`POST /api/media/trim`	Cut video or audio by start time and duration.
`POST /api/media/gif`	Create an animated GIF preview from a video.
`POST /api/media/storyboard`	Generate a tiled frame contact sheet from a video.
`POST /api/media/video-frames`	Export sampled or source-rate video frames as a ZIP of numbered images.
`POST /api/media/transform`	Resize, crop, rotate, flip, and re-encode images. Supports CDN-style `gravity`, `crop=smart`, and `fp` focal points.
`POST /api/media/adjust`	Apply brightness, saturation, hue, contrast, grayscale, or invert to images and video; volume, normalize, and fade in/out to audio.
`POST /api/media/convert`	Re-encode a single video or audio file (use `/api/convert` for image batches).
`POST /api/media/concat-audio`	Merge two or more audio files end-to-end.
`POST /api/media/remove-background`	Remove image backgrounds with Convertly’s managed ML segmentation service.
`POST /api/media/signed-transform`	Generate CDN-style signed transform URLs for cacheable image derivatives.

Common request options

Field	Type	Applies to	Description
`file`	file	All single-file tools	Multipart upload input.
`files`	file[]	Image to PDF	Multipart image uploads.
`sourceUrl`	string	All tools	Remote HTTP(S) file input.
`async`	boolean	All tools	Queue the tool as a background job.
`download`	boolean	Single-file sync results	Return the generated file as an HTTP attachment instead of JSON.
`force`	boolean	Background removal	Re-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.

Transform chains and presets

The transform endpoint can resize, crop, change format, and set quality in one request. Pass gravity, crop=smart, or fp=x,y for the same smart-crop behaviour as the image CDN. 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:

Preset	Output
`ecommerce`	1600px product image, WebP, quality 84.
`avatar`	512x512 cover crop, WebP, quality 86.
`blog-hero`	1600x900 cover crop, WebP, quality 84.
`social-preview`	1200x630 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. Convertly runs background removal on our infrastructure — you do not install or configure an ML runtime. Use the model parameter (small, medium, or large) to balance speed and edge quality; see Media tool options for details. This endpoint counts as one Media API operation and does not consume Forma AI units. The file-lightbox Remove BG preview is a separate convenience flow that displays and consumes its Forma AI unit estimate before processing. 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.

Getting Started

Image CDN

Media Platform

SDKs & Integrations

Resources

Current tools

API endpoints

Common request options

Build with media tools

Transform chains and presets

Background removal

Signed transform URLs

CDN image URLs for stored files

​Current tools

​API endpoints

​Common request options

Build with media tools

​Transform chains and presets

​Background removal

​Signed transform URLs

​CDN image URLs for stored files

Current tools

API endpoints

Common request options

Transform chains and presets

Background removal

Signed transform URLs

CDN image URLs for stored files