Options reference

Pass conversion options under the options[...] namespace:

-F "options[resize][width]=800" \
-F "options[resize][height]=600" \
-F "options[resize][mode]=fit" \
-F "options[quality]=90"

Booleans accept true/false or 1/0.

The set of options that apply depends on the input → output combination. Options outside that set are accepted but ignored.

Resize (image and video pipelines)

Option	Type	Values	Default
resize.width	integer	pixels	,
resize.height	integer	pixels	,
resize.mode	string	fit, fill, stretch, exact	fit (image pipeline)

• fit, preserve aspect ratio, fit within the box.
• fill, preserve aspect ratio, cover the box (crops overflow).
• stretch, distort to exactly the given dimensions.
• exact, same as stretch but unconditional (used when both dimensions are required to match exactly).

If only one of width or height is supplied, the other scales proportionally.

Image options (image → image)

Option	Type	Values	Notes
quality	integer	1–100	For lossy outputs (jpg, webp, avif, heic). JPEG defaults to 85.
dpi	integer	pixels per inch	Sets output -density.
strip_metadata	boolean		Default true.
background_color	string	#RRGGBB or #RGB	Used when flattening transparency.
colorspace	string	sRGB, CMYK, grayscale
lossless	boolean		webp and avif only.
tiff_compression	string	lzw, zip, none	TIFF only.
resize	object	(see Resize)

ico outputs are clamped to 256×256.

Video → video options

These options also apply to animated image → video conversions (gif/webp → mp4, webm, etc.).

Option	Type	Values	Notes
video_codec	string	auto, h264, h265, vp9, av1, prores, copy	auto picks a codec appropriate for the container.
audio_codec	string	auto, aac, mp3, opus, vorbis, pcm, copy	auto picks per container.
video_quality	string	low, medium, high, lossless	Maps to libx264 CRF 28 / 23 / 18.
bitrate_video	string	2M, 800k, etc.	Number with optional k/M suffix.
bitrate_audio	string	same syntax
fps	integer
trim_start	number	seconds
trim_end	number	seconds
strip_audio	boolean		Default false.
strip_metadata	boolean		Default true.
watermark_image	string	path to an image	Overlays the image on the rendered video.
resize	object	(see Resize)

auto codec defaults by container:

Container	Video	Audio
mp4	h264	aac
mkv	h264	aac
mov	h264	aac
flv	h264	aac
3gp	h264	aac
avi	h264	mp3
webm	vp9	opus
wmv	wmv2	wmav2
mpeg/mpg	mpeg2video	mp2
ogg	theora	vorbis

Video → audio options

Apply to mp4 / mpeg → mp3, the only video-to-audio pair the API supports.

Option	Type	Values	Notes
audio_codec	string	mp3, copy	Default mp3 (re-encode). copy remuxes the existing audio stream without re-encoding.
audio_qscale	integer	0–9	VBR quality, 0 = best. Ignored if audio_bitrate is set.
audio_bitrate	integer	≥ 1	CBR bitrate; takes precedence over audio_qscale.
volume	number	≥ 0	Volume multiplier.
channels	integer	≥ 1	e.g. 1 for mono.
sample_rate	integer	≥ 1	e.g. 44100.
trim_start	number	seconds	Timestamps are reset after trimming.
trim_end	number	seconds
strip_metadata	boolean		Default true.

⚠️ audio_codec: copy only produces a valid MP3 if the source’s audio stream is already MP3. Most MP4 files carry AAC audio, and copy writes that stream into the .mp3 container unchanged, producing a file that many players reject. The API does not block the combination, so use the default mp3 codec unless you know the source stream is MP3.

Video → GIF options

Option	Type	Notes
resize	object	(see Resize)
fps	number
max_colors	integer	Palette size (2–256).
keyframe_interval	number	Seconds between palette resets.
trim_start	integer	Seconds.
trim_end	integer	Seconds.

Every video source format can produce a GIF.

Video → image (still frame)

Option	Type	Notes
timestamp	string	Seconds (5, 1.5) or timecode (00:01:23).
resize	object
quality	integer	For lossy image outputs.
strip_metadata	boolean	Default true.
tiff_compression	string	lzw, zip, none.
lossless	boolean	webp / avif.

PDF → image

Option	Type	Default	Notes
page	integer	1	Page number to render.
dpi	integer	300
quality	integer	85	For lossy outputs.
strip_metadata	boolean	true

Office documents (docx / xlsx / pptx / etc.)

Option	Type	Default	Notes
page	integer	1	For image outputs only.
dpi	integer	300	For image outputs only.
quality	integer	85	For lossy image outputs.