Media Tool Options

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: `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 for more on ideal source images and tracing behavior.

Getting Started

Image CDN

Media Platform

SDKs & Integrations

Resources

Common fields

Transform

Preset defaults

Adjust

Compress

Watermark

Thumbnail

Background removal

Poster frame

Extract audio

Trim

Storyboard

Video frame sequence

Video to GIF

PDF preview

Image to PDF

Inspect

Strip metadata

Vectorization (raster to SVG)

​Common fields

​Transform

​Preset defaults

​Adjust

​Compress

​Watermark

​Thumbnail

​Background removal

​Poster frame

​Extract audio

​Trim

​Storyboard

​Video frame sequence

​Video to GIF

​PDF preview

​Image to PDF

​Inspect

​Strip metadata

​Vectorization (raster to SVG)

Common fields

Transform

Preset defaults

Adjust

Compress

Watermark

Thumbnail

Background removal

Poster frame

Extract audio

Trim

Storyboard

Video frame sequence

Video to GIF

PDF preview

Image to PDF

Inspect

Strip metadata

Vectorization (raster to SVG)