Reference

Options

The options conversions take. Each conversion takes only some of them, each with its own range and default. See them for one conversion in Conversions.

Pass an option

In cv, pass an option as --opt key=value. --pages, --password and --dpi are also flags of their own. In the API, options go in the job's options.

An option a conversion does not take, or a value outside its range, fails with invalid_options, and the message names the options the conversion takes. A switch set to false is the same as leaving it out. cv targets <file> --json lists each conversion's options with the range and default it uses.

Terminal

$ export CV_API_KEY=cv_sk_…

Set your key once. Every cv command reads it.

Terminal

$ cv convert photo.png web.webp --opt quality=80 --opt strip=true

stderrweb.webp (48120 bytes) -> web.webp

All options

Option	Takes
pages	Text	Page range to read, for example 1-3,7. Also `--pages`.
password	Text	Password for an encrypted input. Also `--password`.
dpi	Whole number from 36 to 600	Raster resolution in dots per inch. Also `--dpi`.
quality	Whole number from 1 to 100	Lossy compression quality.
page_size	`a4`, `letter`, `auto`	Output page size.
frame_duration	Number from 0.04 to 600	Seconds each image is shown when composing images into video.
fit	`pad`, `crop`, `scale`	How frames of different sizes are normalized.
compression	`screen`, `ebook`, `printer`	PDF size preset. screen is the smallest, printer keeps the most detail.
pdfa	`1`, `2`, `3`	PDF/A conformance level to produce.
encrypt_password	Text	Password that protects the output PDF.
rotate	`90`, `180`, `270`	Degrees to rotate clockwise.
width	Whole number from 1 to 20,000	Width in pixels. The height follows the aspect ratio unless height is also given.
height	Whole number from 1 to 20,000	Height in pixels. The width follows the aspect ratio unless width is also given.
max_width	Whole number from 1 to 20,000	Shrink to fit inside this width in pixels, keeping the aspect ratio. Smaller stays as it is.
max_height	Whole number from 1 to 20,000	Shrink to fit inside this height in pixels, keeping the aspect ratio. Smaller stays as it is.
strip	`true` or `false`	Remove metadata such as EXIF and color profiles.
trim_start	Number from 0 to 86,400	Seconds to cut from the start of audio or video.
trim_end	Number from 0 to 86,400	Second at which the audio or video stops.
frame_at	Number from 0 to 86,400	Seconds into the video to take the picture from. The first frame when left out.
audio.bitrate	Whole number from 32 to 320	Audio bitrate in kbit/s.
video.codec	`h264`, `h265`, `vp9`, `av1`, `copy`	Video codec to encode with. copy keeps the stream as it is when the container allows it.
video.fps	Number from 1 to 120	Frames per second to encode the video or animation at.
video.crf	Whole number from 0 to 63	Constant rate factor. Lower keeps more detail and makes a bigger file.
video.mute	`true` or `false`	Drop the audio track.
speed	Number from 0.25 to 4	Playback speed multiplier. 2 plays twice as fast.
audio.sample_rate	Whole number from 8,000 to 192,000	Audio sample rate in Hz.
audio.channels	Whole number from 1 to 8	Number of audio channels. 1 is mono, 2 is stereo.
audio.normalize	`true` or `false`	Normalize loudness to -16 LUFS as streaming services do.
audio.denoise	`true` or `false`	Reduce steady background noise.
audio.bit_depth	`16`, `24`	Bits per sample for uncompressed and lossless audio. Kept from the input when left out.
ocr	`auto`, `on`, `off`	How to read scanned pages and images: on recognizes their text, off reads only an existing text layer, auto recognizes it when language or deskew is set.
language	Text	Languages of the text to recognize, as comma-separated codes from en, ko, ja, zh, zh-TW.
deskew	`true` or `false`	Straighten pages that were scanned at a slight angle.
font.characters	Text	Keep only the glyphs needed for these characters when subsetting a font.
font.unicodes	Text	Unicode ranges to keep when subsetting a font, for example U+0020-007E,U+AC00-D7A3.
font.axes	Text	Pin variable font axes to make a static instance, for example wght=700,wdth=100.
lossless	`true` or `false`	Encode without loss where the format allows it.
linearize	`true` or `false`	Rearrange the PDF so the first page shows before the whole file has loaded.
flatten	`true` or `false`	Burn form fields and annotations into the page content.
grayscale	`true` or `false`	Convert colors to shades of gray.
watermark	Text	Text stamped diagonally across every page.
page_numbers	`true` or `false`	Print "page N of M" at the bottom of every page.
nup	`2`, `4`, `6`, `8`, `9`, `16`	Pages per sheet.
level	Whole number from 1 to 9	Compression level. Higher is smaller and slower.
slides	`true` or `false`	Write the HTML as a reveal.js slide deck, one slide per heading.
readable	`true` or `false`	Keep only the main article text of a web page, dropping menus, ads and footers.
optimize	`true` or `false`	Recompress losslessly to make the file smaller without changing the pixels or shapes.
repair	`true` or `false`	Fix holes, flipped normals and stray facets in a mesh.
sheet	Text	Name or number, counting from 1, of the one worksheet to convert. Every worksheet when left out.
delimiter	`comma`, `semicolon`, `tab`, `pipe`	Character between the fields. Guessed from the rows when left out.
header	`true` or `false`	Whether the first row holds the column names rather than data.
highlight_edits	`true` or `false`	Mark what the edits change so people can see it, such as a fill on the changed cells.
compare	`true` or `false`	With two Word documents, the original and then the revised one, write the original with the tracked changes that turn it into the revised one, instead of joining them.
track_changes	`true` or `false`	Write the edits' text changes as tracked changes, which a person accepts or rejects in Word, instead of changing the text directly.
author	Text	Name written as the author of the tracked changes and comments the edits make, such as a person or a team; convert.dev when left out.
date	Text	Date and time written on the tracked changes and comments the edits make, as YYYY-MM-DDThh:mm:ssZ in UTC; none when left out.
initials	Text	Initials written on the comments the edits make; the first letters of the author's name when left out.
background	Text	Color that fills transparent areas, written as #RRGGBB.
frames	`first`, `all`	Frames of an animation to convert: the first one, or every frame.

Updated 3 November 2026