> ## 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. # Media Tools > Media capabilities that Convertly can provide through the API and dashboard. 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 | 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 and short videos. | | 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. | | 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, 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 and videos. | | `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/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 the built-in solid remover or a configured ML segmentation backend. | | `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. | | `force` | boolean | Background removal | Re-segment an image even when it already has transparency. | ```bash theme={"system"} 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" ``` ```json theme={"system"} { "jobId": "65f3a673-69d6-42cc-8f6b-fc5a21fb5a8e", "status": "pending", "tool": "poster-frame" } ``` 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](/docs/image-cdn/transforms). Use this for upload pipelines where a single source image needs a production-ready derivative. ```bash theme={"system"} 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. | ```bash theme={"system"} 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 any local ML runtime. Use the `model` parameter (`small`, `medium`, or `large`) to balance speed and edge quality; see [Media tool options](/docs/media-tool-options#background-removal) for details. 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. ```bash theme={"system"} 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. ```bash theme={"system"} 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: ```bash theme={"system"} 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.