> ## Documentation Index
> Fetch the complete documentation index at: https://docs.snipp.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Convert a File

Convert one image or video to another format and get the converted file back in the response. Nothing is stored, no post is created, and no upload quota is consumed.

## Headers

| Header           | Required | Description                                           |
| ---------------- | -------- | ----------------------------------------------------- |
| `api-key`        | Yes      | Your API key                                          |
| `convert-target` | Yes      | `png`, `jpeg`, `webp`, `avif`, `gif`, `mp4`, or `mp3` |

## Behavior

* Send the file as `multipart/form-data`. Only the first file in the request is read.
* The response body is the converted file itself, sent as an attachment, not JSON. Write it straight to disk.
* The source format is detected from the file's own bytes, not its name or the declared content type.
* **What can become what:** PNG, JPG and WebP convert to png, jpeg, webp, avif or gif. GIF converts to png, jpeg, webp, avif or mp4. MP4, MOV and MKV convert to mp4, gif or mp3.
* **Video to GIF requires Snipp+** and uses the first 10 seconds only, at 15fps and 480px wide.
* **MP4 output** is remuxed with `+faststart` when the source is already H.264, and transcoded otherwise.
* **Metadata is always stripped.** Images are re-encoded without it and videos are written with `-map_metadata -1`. JPG orientation is applied to the pixels first, so photos stay the right way up.
* Files are capped at 50 MB on the free plan. Snipp+ and Ultra have no per-file cap, the same as [`/upload`](/api-reference/endpoint/upload). Conversion runs inside the request, so a large video can take a while to come back.
* Rate limited to 10 conversions per minute. Converting does not count toward your weekly upload limit.
* To host the result, pipe it into [`POST /upload`](/api-reference/endpoint/upload). Note that avif and mp3 are not accepted upload types, so those two are download-only.

## Examples

Convert a screenshot to WebP:

```bash theme={null}
curl -X POST "https://api.snipp.gg/convert" \
  -H "api-key: YOUR_API_KEY" \
  -H "convert-target: webp" \
  -F "file=@screenshot.png" \
  -o screenshot.webp
```

Pull the audio out of a clip:

```bash theme={null}
curl -X POST "https://api.snipp.gg/convert" \
  -H "api-key: YOUR_API_KEY" \
  -H "convert-target: mp3" \
  -F "file=@clip.mp4" \
  -o clip.mp3
```

Convert, then host the result:

```bash theme={null}
curl -X POST "https://api.snipp.gg/convert" \
  -H "api-key: YOUR_API_KEY" \
  -H "convert-target: mp4" \
  -F "file=@loop.gif" \
  -o loop.mp4

curl -X POST "https://api.snipp.gg/upload" \
  -H "api-key: YOUR_API_KEY" \
  -F "file=@loop.mp4"
```

## Responses

On success the body is the converted file and the headers name it:

```
HTTP/1.1 200 OK
Content-Type: image/webp
Content-Disposition: attachment; filename="screenshot.webp"
Content-Length: 184320
```

On failure the body is JSON:

```json theme={null}
{
  "error": "That file cannot be converted to this format."
}
```