> ## 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 Conversion

> Convert and compress files with Convertly's synchronous media endpoints.

Use synchronous endpoints when your app needs converted files in the same request. Convertly handles upload intake, format validation, resizing, compression, optional storage records, and download URL generation. For larger batches or long-running work, use [Async Jobs](/guides/async-jobs).

For **web delivery** of images and video (responsive sizing, format negotiation, edge caching), use the [Image CDN](/docs/image-cdn) instead of converting files on every page load — especially when assets already live on your site or in Convertly Storage.

<div className="convertly-callout">
  Use synchronous convert/compress when the user waits on the result. For web pages, prefer the Image CDN. For large batches, use [async jobs](/guides/async-jobs).
</div>

<Columns cols={2}>
  <Card title="Convert" icon="file-gear">
    Change the output format, resize images, normalize orientation, and control output quality.
  </Card>

  <Card title="Compress" icon="box-archive">
    Keep the file format compatible while reducing size by quality or target byte size.
  </Card>
</Columns>

## When to use it

Use synchronous conversion for profile uploads, image optimization, document export tools, admin dashboards, and user-facing forms where the file count is modest and the user is waiting for the result.

If your user can leave the page, if the file is large, if the source is video or audio, or if you are processing many files at once, prefer async jobs. Jobs return a `jobId` immediately and let Convertly workers finish the media processing in the background.

## Convert files

`POST /api/convert` accepts one or more `files` fields and conversion settings.

```bash theme={"system"}
curl -X POST "https://convertly.sh/api/convert" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "files=@./hero.png" \
  -F "format=webp" \
  -F "compression=82" \
  -F "resize=website" \
  -F "autoOrient=true"
```

Raster-to-SVG conversion preserves flat color layers by default. Add `mono=true` only when you want the older black-and-transparent tracing behavior:

```bash theme={"system"}
curl -X POST "https://convertly.sh/api/convert" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "files=@./logo.png" \
  -F "format=svg" \
  -F "compression=82" \
  -F "resize=original" \
  -F "mono=true"
```

For per-file settings, send JSON arrays:

```bash theme={"system"}
curl -X POST "https://convertly.sh/api/convert" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "files=@./hero.png" \
  -F "files=@./avatar.jpg" \
  -F 'formats=["webp","avif"]' \
  -F 'compressions=[82,76]' \
  -F 'resizes=["website","instagram"]' \
  -F 'resizeWidths=[null,null]' \
  -F 'resizeHeights=[null,null]' \
  -F 'autoOrients=[true,true]' \
  -F 'monos=[false,false]'
```

## Compress files

`POST /api/compress` keeps the output format compatible with the original file.

```bash theme={"system"}
curl -X POST "https://convertly.sh/api/compress" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "files=@./photo.jpg" \
  -F "mode=quality" \
  -F "quality=76" \
  -F "lossless=false" \
  -F "stripMetadata=true"
```

For target-size compression:

```bash theme={"system"}
curl -X POST "https://convertly.sh/api/compress" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "files=@./photo.jpg" \
  -F "mode=target-size" \
  -F "targetBytes=250000"
```

## Per-file settings

When you upload multiple files, you can either send one setting for the full batch or JSON arrays with one value per file. Convertly validates that every uploaded file has matching settings before processing starts.

For example, if you upload two files and send `formats`, `compressions`, or `monos`, each array must contain two values.

## Supported output formats

For synchronous `/api/convert`, use image, document, and archive outputs such as `jpg`, `png`, `webp`, `avif`, `tiff`, `gif`, `heif`, `svg`, `pdf`, `zip`, `tar`, `tgz`, `7z`, `rar`, `gz`, `bz2`, and `xz`. Use `/api/jobs` for video and audio outputs such as `mp4`, `webm`, `mov`, `mp3`, `wav`, `ogg`, `m4a`, and `flac`.

## Resize modes

`original`, `website`, `email`, `instagram`, `linkedin`, `ecommerce`, `square`, `width`, `height`.

## SVG tracing

When `format=svg`, Convertly traces raster images into layered vector paths. Color is preserved by default. Use `mono=true` or per-file `monos=[true,false]` for monochrome tracing.

## Response fields

| Field          | Description                                                          |
| -------------- | -------------------------------------------------------------------- |
| `filename`     | Converted or compressed output filename.                             |
| `originalSize` | Input file size in bytes.                                            |
| `finalSize`    | Output file size in bytes.                                           |
| `savedPercent` | Size reduction percentage.                                           |
| `mimeType`     | Output MIME type.                                                    |
| `downloadUrl`  | Data URL or signed storage URL for the generated file.               |
| `storedFileId` | Stored file ID when the user is authenticated and the file is saved. |

## Storage behavior

API-key requests return downloadable results without saving files by default. Add `saveToStorage=true` when your product needs Convertly to persist uploads and outputs.

```bash theme={"system"}
curl -X POST "https://convertly.sh/api/convert" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "files=@./hero.png" \
  -F "format=webp" \
  -F "resize=website" \
  -F "saveToStorage=true"
```