Convert

Change a file's format — webm → mp4, png → webp, or PDF pages to images. The file-first recipe takes the target format directly and lowers it to the wire for you.

Audio formats

Accepted
audio/aac · audio/flac · audio/mp4 · audio/mpeg · audio/ogg · audio/wav	Stable

⚠️ This list is specific to convert. Each operation accepts its own set — merge, for example, does not take audio/mp4. Do not carry a list from one page to another; call getSchema() for the authoritative set at runtime.

File-first

TypeScript

const result = await client
  .file('./clip.webm')
  .convert('mp4')
  .run({ maxWait: '10m' });

console.log(result.url);

PHP

$run = $client->file('./clip.webm')
    ->convert('mp4')
    ->run(maxWait: '10m');

echo $run->url;

Python

Not available: the Python SDK is not published and no release is scheduled — see Python.

Rust

Not an application SDK: Rust is internal contract types — see Rust.

convert(format, options) takes the per-media options below as its second argument; they are typed and validated before upload. The format argument owns the target, so do not also put output_format in the bag.

The single-operation form takes the same shape, with the input first: client.convert('./image.png', 'webp', { quality: 80 }) (PHP $client->convert('./image.png', 'webp', ['quality' => 80])). The target is the second argument; output_format in the bag is rejected.

For long conversions, run() takes an onProgress callback. Processing events carry phase: 'processing' and progress (0–100) — in PHP, a ProcessingProgressEvent with $progress.

Options by media type

Every option is optional unless marked; the default applies when you omit it.

Image

JPEG, PNG, WebP, TIFF, BMP, ICO, AVIF, HEIC/HEIF, GIF and SVG input. Targets: jpeg, png, webp, avif, gif, tiff.

Option	Values	Default	Notes
quality	1–100	85	jpeg, webp and avif targets.
background	#RRGGBB	—	jpeg target; fills transparency.
width / height	1–16384	—	Width × height ≤ 16 MP. Not for SVG input.
fit	max · crop · scale	max	When width or height is set.
color_profile	keep · srgb · strip	keep	Not for SVG input.
auto_orient	boolean	true	Not for SVG input.

metadata is planned on convert: metadata is not yet preserved across a format change.

Animated GIF to video. GIF input can also target mp4 (H.264) or webm (VP9): the animation becomes a silent video, usually far smaller than the GIF. The resize options do not apply to those targets: fit needs width or height, which only still-image targets accept.

Video

MP4, WebM and Ogg input. Targets: mp4, webm, ogg, mov, mkv, gif. The container fixes the codec — H.264 for mp4, mov and mkv, VP9 for webm, Theora for ogg — so there is no codec option. Input over 5 minutes (the long-form tier) is planned for convert.

Option	Values	Default	Notes
crf	0–51	23	Lower is higher quality. Not for gif.
trim_start / trim_end	seconds, ≥ 0	—	Seconds cut from the start / from the end.
fps	1–50	12	gif only.
width	1–4096	480	gif only — a downscale cap; narrower sources are untouched.
max_colors	2–256	256	gif only — palette size.
loop	≥ -1	0	gif only — 0 loops forever, N loops N times, -1 plays once.
dither	none · bayer · floyd_steinberg · sierra2 · sierra2_4a	bayer	gif only.

For a target file size, codec choice or encoder preset, use compress.

Audio

MP3, AAC, Ogg, FLAC, WAV and MP4 audio input. Targets: mp3, aac, ogg, opus, flac, wav.

Option	Values	Default	Notes
bitrate	64 · 96 · 128 · 192 · 256 · 320	128	kbps; mp3, aac, ogg and opus only.

PDF pages as images

PDF input. Targets: png, jpeg.

Option	Values	Default	Notes
pages	a page, range or list — '3', '1-5', '1-5,8'	'1'	At most 200 pages per request.
dpi	72–600	150	Render resolution.

Each selected page is a separate output, so one convert returns several artifacts. Read them from result.artifacts, or write them all with downloadTo():

TypeScript

const result = await client
  .file('./brochure.pdf')
  .convert('png', { pages: '1-5', dpi: 150 })
  .run({ maxWait: '5m' });

await result.downloadTo('./pages'); // one PNG per page

PHP

$result = $client->file('./brochure.pdf')
    ->convert('png', ['pages' => '1-5', 'dpi' => 150])
    ->run(maxWait: '5m');

$result->downloadTo('./pages'); // one PNG per page

Python

Not available: the Python SDK is not published and no release is scheduled — see Python.

Rust

Not an application SDK: Rust is internal contract types — see Rust.

Batch convert

TypeScript

const result = await client
  .files(['./a.png', './b.png', './c.png'])
  .convert('webp')
  .run({ maxWait: '10m' });

PHP

$run = $client->files(['./a.png', './b.png', './c.png'])
    ->convert('webp')
    ->run(maxWait: '10m');

Python

Not available: the Python SDK is not published and no release is scheduled — see Python.

Rust

Not an application SDK: Rust is internal contract types — see Rust.

See also

• Compress — reduce size without changing format.
• Thumbnail — generate a preview image.