> ## 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 Tool Options > Complete field reference for every Convertly media tool endpoint. Every media tool accepts `file` (multipart upload) or `sourceUrl` (remote URL) as input. Add `async=true` to queue heavier work as a background job. ## Common fields These fields are accepted by most tools: | Field | Type | Default | Description | | ---------------- | ------- | ------- | --------------------------------------------------- | | `file` | file | — | Multipart file upload. | | `files` | file\[] | — | Multiple file uploads (image-to-PDF only). | | `sourceUrl` | string | — | Remote HTTP(S) URL to process without re-uploading. | | `async` | boolean | `false` | Queue as a background job. Returns a `jobId`. | | `callbackUrl` | string | — | HTTPS URL to call when an async job completes. | | `callbackSecret` | string | — | Secret included in async callback signatures. | *** ## Transform `POST /api/media/transform` Resize, crop, rotate, flip, and re-encode images. | Field | Type | Default | Description | | ------------ | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `preset` | string | — | Built-in: `thumb`, `hero`, `og-card`, `product`, `email`, `gallery` (legacy aliases: `ecommerce`, `avatar`, `blog-hero`, `social-preview`). Also available on the CDN as `?preset=`. Overrides width, height, fit, format, and quality. | | `format` | string | `webp` | `jpg`, `png`, `webp`, `avif`. | | `width` | number | `0` | Output width in pixels. `0` means no resize. | | `height` | number | `0` | Output height in pixels. `0` means no resize. | | `fit` | string | `cover` | `cover`, `contain`, `fill`, `inside`, `outside`. | | `quality` | number | `86` | `1`–`100`. Ignored for PNG unless lossy WebP/AVIF. | | `rotate` | number | `0` | Rotation in degrees. | | `flip` | boolean | `false` | Flip vertically. | | `flop` | boolean | `false` | Flip horizontally. | | `cropLeft` | number | `0` | Crop origin X in pixels. | | `cropTop` | number | `0` | Crop origin Y in pixels. | | `cropWidth` | number | `0` | Crop width in pixels. | | `cropHeight` | number | `0` | Crop height in pixels. | | `gravity` | string | `auto` | Same values as the [CDN](/docs/image-cdn/transforms): `auto`, `smart`, `face`, `entropy`, compass directions. | | `crop` | string | — | Set to `smart` for content-aware crop (same as `gravity=smart`). | | `fp` | string | — | Manual focal point `x,y` in `[0,1]` or percentages. | ### Preset defaults Built-in presets are shared between the Media API and Image CDN. Legacy API names remain aliases. | Preset | Aliases | Width | Height | Fit | Format | Quality | | --------- | ---------------- | ------ | ------ | -------- | ------ | ------- | | `thumb` | `avatar` | `512` | `512` | `cover` | `webp` | `86` | | `hero` | `blog-hero` | `1600` | `900` | `cover` | `webp` | `84` | | `og-card` | `social-preview` | `1200` | `630` | `cover` | `jpg` | `88` | | `product` | `ecommerce` | `1600` | `1600` | `inside` | `webp` | `84` | | `email` | — | `600` | — | `inside` | `jpg` | `82` | | `gallery` | — | `1200` | `1200` | `inside` | `webp` | `84` | *** ## Adjust `POST /api/media/adjust` Change brightness, contrast, saturation, hue, and apply filters. | Field | Type | Default | Description | | --------------------------- | ----------------- | ----------- | --------------------------------------------------------------------------------------------------- | | `format` | string | `webp` | `jpg`, `png`, `webp` for images. `mp4`, `webm`, `mov` for video. `mp3`, `m4a`, `wav` for audio. | | `quality` | number | `86` | `1`–`100`. | | `brightness` / `bri` | number | `1` / `100` | Multiplier (`1` = no change) or absolute scale `0`–`200` (`100` = no change). Image and video only. | | `contrast` / `con` | number | `1` / `100` | Same scale as brightness. Image and video only. | | `saturation` / `sat` | number | `1` / `100` | Same scale as brightness. Image and video only. | | `hue` | number | `0` | Degrees. Image and video only. | | `blur` | number | — | `0`–`100`. Image only (same scale as CDN). | | `grayscale` | boolean | `false` | Convert to grayscale. | | `sharpen` / `sharp` / `usm` | boolean or number | `false` | Boolean sharpen, or amount `0`–`100`. Image only. | | `invert` | boolean | `false` | Invert colors. Image and video only. | | `volume` | number | `1` | `0`–`4`. Audio only. | | `normalize` | boolean | `false` | Normalize audio levels. Audio only. | | `fadeIn` | number | `0` | Fade-in duration in seconds. Audio only. | | `fadeOut` | number | `0` | Fade-out duration in seconds. Audio only. | *** ## Compress `POST /api/compress` Reduce file size with quality-based or target-size compression. | Field | Type | Default | Description | | --------------- | ------- | --------- | -------------------------------------------------------- | | `mode` | string | `quality` | `quality` or `target-size`. | | `quality` | number | `82` | `1`–`100`. Used when `mode=quality`. | | `targetBytes` | number | — | Target file size in bytes. Used when `mode=target-size`. | | `lossless` | boolean | `false` | Lossless compression where the format supports it. | | `stripMetadata` | boolean | `true` | Remove EXIF and container metadata. | *** ## Watermark `POST /api/media/watermark` Add text or logo watermarks to images, short videos, and every page of a PDF. PDF pages retain their original vector and text content beneath the watermark. | Field | Type | Default | Description | | --------------- | ------ | -------------- | ---------------------------------------------------------------------------------------------- | | `text` | string | `Convertly` | Watermark text when no `watermarkFile` is supplied. | | `watermarkFile` | file | — | Optional PNG, JPEG, WebP, or SVG logo watermark. | | `position` | string | `bottom-right` | `top-left`, `top-right`, `bottom-left`, `bottom-right`, `center`. | | `opacity` | number | `0.72` | `0`–`1`. | | `margin` | number | `32` | Padding from the edge in pixels. | | `rotation` | number | `0` | Counter-clockwise rotation from `-359` to `359` degrees. Alias: `watermarkRotation`. | | `tile` | string | — | Set to `grid` to repeat the watermark across the output. Alias: `watermarkTile`. | | `tilePadding` | number | `48` | Horizontal and vertical spacing in pixels between tiled watermarks. Alias: `watermarkPadding`. | Each request consumes one Media API operation and processed-transfer allowance. PDF watermarking does not consume Forma AI units. *** ## Thumbnail `POST /api/media/thumbnail` Generate thumbnails from images or videos. | Field | Type | Default | Description | | --------- | ------ | ------- | ----------------------------- | | `format` | string | `webp` | `jpg`, `png`, `webp`, `avif`. | | `width` | number | `512` | Thumbnail width. | | `height` | number | `512` | Thumbnail height. | | `fit` | string | `cover` | `cover`, `contain`, `inside`. | | `quality` | number | `82` | `1`–`100`. | *** ## Background removal `POST /api/media/remove-background` Remove simple studio or solid-color backgrounds and return a transparent image. For complex subjects — hair, glass, busy scenes — use `model=medium` or `model=large` for stronger segmentation. | Field | Type | Default | Description | | -------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `format` | string | `png` | `png`, `webp`, `jpg`. Use `png` or `webp` for transparency. | | `model` | string | `medium` | `small`, `medium`, `large`. Higher tiers improve edge quality on hair, glass, and busy backgrounds at the cost of longer processing time. | | `force` | boolean | `false` | Re-segment even if the image already has transparency. | *** ## Poster frame `POST /api/media/poster-frame` Extract a single frame from a video at a timestamp. | Field | Type | Default | Description | | ----------- | ------ | ------- | ---------------------------------- | | `timestamp` | number | `0` | Frame time in seconds. | | `format` | string | `jpg` | `jpg`, `png`, `webp`. | | `quality` | number | `82` | `1`–`100`. | | `width` | number | `0` | Max width. `0` means source width. | *** ## Extract audio `POST /api/media/extract-audio` Pull the audio track from a video file. | Field | Type | Default | Description | | -------- | ------ | ------- | ----------------------------------- | | `format` | string | `mp3` | `mp3`, `m4a`, `wav`, `ogg`, `flac`. | *** ## Trim `POST /api/media/trim` Cut a video or audio clip by start time and duration. | Field | Type | Default | Description | | ---------- | ------ | ------- | -------------------------------------------------- | | `start` | number | `0` | Start time in seconds. | | `duration` | number | — | Duration in seconds. If omitted, trims to the end. | | `format` | string | — | Output format. Inherits source format if omitted. | *** ## Storyboard `POST /api/media/storyboard` Generate a tiled contact sheet of video frames. | Field | Type | Default | Description | | ---------- | ------ | ------- | ------------------------------------------------------------------- | | `columns` | number | `4` | Frames per row. | | `rows` | number | `4` | Rows in the grid. | | `interval` | number | — | Seconds between frames. Defaults to evenly spaced across the video. | | `format` | string | `jpg` | `jpg`, `png`, `webp`. | | `quality` | number | `82` | `1`–`100`. | | `width` | number | `0` | Max width of the final sheet. `0` means auto. | *** ## Video frame sequence `POST /api/media/video-frames` Export video frames into a ZIP archive. The archive contains a named folder, numbered image frames, and `manifest.json`. Convertly returns a downloadable ZIP payload by default and does not create one library file per frame. Add `download=true` for a direct HTTP attachment, or use `async=true` when you want the generated ZIP saved to Convertly Storage as a job result. | Field | Type | Default | Description | | ----------- | ------------------ | ------- | ------------------------------------------------------------------------------------------------------ | | `fps` | number or `source` | `1` | Frames per second to export. Use `source` or `native` to export source video frames up to `maxFrames`. | | `interval` | number | - | Seconds between sampled frames. Used when `fps` is omitted. | | `maxFrames` | number | `300` | Maximum frames to include. Hard-capped for safety. Alias: `frames`. | | `start` | number | `0` | Start time in seconds. | | `duration` | number | - | Optional clip duration in seconds. If omitted, export continues until EOF or `maxFrames`. | | `format` | string | `jpg` | `jpg`, `png`, `webp`, `avif`. | | `quality` | number | `86` | `1`-`100`. | | `width` | number | `1280` | Max frame width. Use `0` to keep source width. | | `height` | number | `0` | Max frame height. `0` means auto height. | | `download` | boolean | `false` | Return the ZIP as a direct attachment for synchronous requests. | *** ## Video to GIF `POST /api/media/gif` Create an animated GIF preview from a video. | Field | Type | Default | Description | | ---------- | ------ | ------- | ----------------------- | | `start` | number | `0` | Start time in seconds. | | `duration` | number | `3` | Duration in seconds. | | `fps` | number | `10` | Frames per second. | | `width` | number | `480` | Output width in pixels. | | `quality` | number | `82` | `1`–`100`. | *** ## PDF preview `POST /api/media/pdf-preview` Render a PDF page to an image. | Field | Type | Default | Description | | --------- | ------ | ------- | ---------------------------------- | | `page` | number | `1` | Page number to render. | | `format` | string | `jpg` | `jpg`, `png`, `webp`, `avif`. | | `quality` | number | `82` | `1`–`100`. | | `width` | number | `0` | Max width. `0` means source width. | *** ## Image to PDF `POST /api/media/image-to-pdf` Package one or more images into a single PDF. | Field | Type | Default | Description | | --------- | ------ | ------- | -------------------------------------------- | | `title` | string | — | PDF document title. | | `quality` | number | `82` | `1`–`100`. JPEG quality for embedded images. | *** ## Inspect `POST /api/media/inspect` Return metadata without modifying the file. | Field | Type | Default | Description | | ----------- | ------ | ------- | ---------------------- | | `file` | file | — | The file to inspect. | | `sourceUrl` | string | — | Remote URL to inspect. | Returns dimensions, duration, codecs, streams, file size, color space, format, and EXIF flags. *** ## Strip metadata `POST /api/media/strip-metadata` Remove EXIF, GPS, and container metadata. | Field | Type | Default | Description | | ----------- | ------ | ------- | ---------------------- | | `file` | file | — | The file to process. | | `sourceUrl` | string | — | Remote URL to process. | No configurable options. The output is a cleaned copy of the same format. *** ## Vectorization (raster to SVG) `POST /api/convert` with `format=svg` Trace raster images into scalable SVG vectors. | Field | Type | Default | Description | | ----------- | ------- | ------- | ------------------------------------------------------------------------------------- | | `vectorize` | string | — | `gradient` to trigger SVG tracing. | | `mono` | boolean | `false` | `true` for monochrome black-on-transparent output. `false` preserves original colors. | See [Media Conversion](/docs/media-conversion) for more on ideal source images and tracing behavior.