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

> How Convertly handles file conversion, compression, format changes, and output delivery.

Convertly is a media processing API and workspace. Your product sends files to Convertly, chooses an output format or optimization setting, and receives generated files back as download URLs. Storage is optional: synchronous API requests can return files without saving them, while async jobs and dashboard workflows can store files when your product needs a durable record.

<div className="convertly-callout">
  Synchronous endpoints return download URLs in the same request. Use async jobs when the batch is large or processing may exceed your request timeout.
</div>

## What media conversion solves

Most products eventually need media handling that goes beyond upload and download. Users upload the wrong format, oversized images, large videos, archive folders, or files that need to become something else before they are useful. Convertly handles that processing layer so your app does not need to run image libraries, video tools, worker queues, storage bookkeeping, and webhook delivery yourself.

## Main capabilities

| Capability         | Outcome                                                                                                                                           |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Format conversion  | Turn uploads into supported image, video, audio, document, or archive outputs.                                                                    |
| Compression        | Reduce file size with quality-based or target-size compression.                                                                                   |
| Image resizing     | Generate web, email, social, ecommerce, square, width-based, or height-based outputs.                                                             |
| SVG tracing        | Convert raster images into alpha-aware SVG vectors with color preserved by default, or opt into monochrome output.                                |
| SVG rasterization  | Render SVG inputs to PNG, JPG, WebP, AVIF, TIFF, GIF, or HEIF at the requested output size with high-DPI rasterization.                           |
| Background removal | Remove simple image backgrounds through the Media Tools API, preserve existing transparent cutouts, or call a configured ML segmentation backend. |
| Video streaming    | Generate HLS/DASH playback assets from stored videos with clipping, bitrate ladders, captions, analytics, signed playback, and plan-based quotas. |
| Archive handling   | Accept ZIP inputs and extract contents for processing when the output is not another archive.                                                     |
| Optional storage   | Save uploads and outputs only when your workflow needs stored files.                                                                              |
| Webhook delivery   | Notify your product when stored media workflows complete.                                                                                         |

## Synchronous vs async

Use synchronous conversion when the user is waiting on a small number of image, document, or archive files and you want the result immediately. Use async jobs for larger batches, video, audio, heavier media, or flows where the user can leave the page while Convertly workers process the files.

<Columns cols={3}>
  <Card title="Immediate results" icon="bolt" href="/guides/media-conversion">
    Use `POST /api/convert` or `POST /api/compress` for direct results.
  </Card>

  <Card title="Background batches" icon="list-check" href="/docs/async-processing">
    Use the jobs API when work should continue outside the request lifecycle.
  </Card>

  <Card title="Video streaming" icon="film" href="/docs/video-streaming">
    Create adaptive HLS playback from stored video files.
  </Card>
</Columns>

## Request lifecycle

1. Send files and settings to a conversion, compression, media tool, or jobs endpoint.
2. Convertly validates file type, file size, [plan limits](/limits), and requested output formats.
3. Convertly processes the files with the relevant media tooling.
4. The response includes generated file metadata and a `downloadUrl`.
5. If storage is enabled, the output also appears in the Convertly file manager and includes a `storedFileId`.

## Supported formats

Convertly supports image, video, audio, document, and archive outputs across the platform. The synchronous `/api/convert` endpoint is intended for immediate image, document, and archive work; use `/api/jobs` for video and audio conversion. Common outputs include `jpg`, `png`, `webp`, `avif`, `tiff`, `gif`, `heif`, `svg`, `pdf`, `mp4`, `webm`, `mov`, `mp3`, `wav`, `ogg`, `m4a`, `flac`, `zip`, `tar`, `tgz`, `7z`, `rar`, `gz`, `bz2`, and `xz`.

## Raster to SVG vectorization

Convertly can trace raster images into scalable SVG vectors. This is useful for logos, icons, marks, and flat artwork that needs to stay sharp at any size.

### How it works

The tracer analyzes color regions and generates SVG paths. By default it preserves the original colors and ignores low-alpha pixels so transparent edges around logos do not become unwanted traced artifacts.

### Vectorization options

| Option      | Type    | Default | Description                                                                                                                                                          |
| ----------- | ------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mono`      | boolean | `false` | When `true`, the output is monochrome black on transparent. Use this for single-color logos, stamps, and cut marks. When `false`, the original colors are preserved. |
| `vectorize` | string  | —       | For synchronous conversion via `POST /api/convert`, send `vectorize=gradient` to trigger SVG tracing.                                                                |

### Ideal source images

* **High contrast** works better than photos with gradients or fine detail.
* **Clean edges** produce cleaner paths. Heavy JPEG compression or noise can create extra path noise.
* **Logos and icons** are the best fit. Complex photographs or textures are not recommended.
* **Resolution** should be high enough that edges are clearly defined. The tracer downscales very large images automatically, but extremely small inputs may lose detail.

### Example requests

Preserve color:

```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 "vectorize=gradient"
```

Monochrome tracing:

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

## SVG to raster rasterization

Convertly can also do the reverse of vectorization: render an SVG into a high-quality raster format (PNG, JPG, WebP, AVIF, TIFF, GIF, or HEIF). This is useful when consumers of the asset need a fixed-size bitmap — social previews, email clients, thumbnails, or platforms that do not accept SVG.

### How it works

The rasterizer reads the SVG with librsvg at a density chosen to hit your target output dimensions, then encodes the result with the format and quality settings you pass. Because the source is a vector, you can request larger output dimensions than the SVG's declared `width`/`height` without upscaling artifacts. When no resize is specified, the longest side defaults to **1024 px** so icon-sized SVGs do not produce tiny rasters.

### Example requests

Render an SVG to a 1080×1080 PNG:

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

Render an SVG to a width-constrained WebP:

```bash theme={"system"}
curl -X POST "https://convertly.sh/api/convert" \
  -H "Authorization: Bearer $CONVERTLY_API_KEY" \
  -F "files=@./logo.svg" \
  -F "format=webp" \
  -F "resizeMode=width" \
  -F "resizeWidth=1600"
```

### Notes

* SVG resolution is unbounded — request whatever output size your downstream platform requires.
* The renderer ignores `withoutEnlargement` for vector inputs; resize targets are honored exactly.
* Embedded raster images inside an SVG are still bound by their own native resolution.
* SVG → SVG passes the file through unchanged unless you also request `vectorize=gradient`, in which case it is re-rasterized and re-traced.

## Common product flows

| Flow                   | How Convertly fits                                                                      |
| ---------------------- | --------------------------------------------------------------------------------------- |
| User-generated content | Accept uploads, normalize image or video formats, and return production-ready files.    |
| Creator exports        | Convert source assets into social, web, email, or ecommerce-ready sizes.                |
| Marketplace listings   | Compress product images and generate consistent output formats before publishing.       |
| Agency delivery        | Process client folders, create archives, and keep completed outputs easy to download.   |
| SaaS media pipelines   | Add conversion, compression, jobs, and webhooks without running your own media workers. |