Supported Media Formats

The File & Convert Toolkit converts video and audio using FFmpeg. This page is the authoritative reference for which source formats are accepted, which targets each one can reach, and which formats are explicitly blocked.

Base URL

https://convert.toolkitapi.io

Media conversion is exposed through:

Method Endpoint Purpose
POST /v1/convert/media Convert a media URL to another format
GET /v1/convert/media Convert a media URL and stream the result as a download

Both take a source_format and target_format. If the pair is not allowed, the API returns 400 with the list of valid targets for that source.


Video formats

Source Valid targets
mp4 webm, gif, mp3, wav, ogg, avi
webm mp4, gif, mp3, wav, ogg
mov mp4, webm, gif, mp3, wav
avi mp4, webm, gif, mp3
mkv mp4, webm, gif, mp3
gif mp4, webm
flv mp4, webm, gif, mp3, wav
mpeg mp4, webm, gif, mp3, wav
mpg mp4, webm, gif, mp3, wav (alias for MPEG)
mts mp4, webm, gif, mp3, wav
m2ts mp4, webm, gif, mp3, wav (alias for MTS)
3gp mp4, webm, gif, mp3, wav
3g2 mp4, webm, gif, mp3, wav
ts mp4, webm, gif, mp3, wav
vob mp4, webm, gif, mp3, wav
m4v mp4, webm, gif, mp3, wav
ogv mp4, webm, gif, mp3, wav
wmv mp4, webm, gif, mp3, wav (decode-only — source only)

The shared video target set is {mp4, webm, gif, mp3, wav}. Note that several video sources can be demodulated to audio (mp3, wav) — useful for extracting soundtracks.

Audio formats

Source Valid targets
mp3 wav, ogg, flac, aac, m4a
wav mp3, ogg, flac, aac, m4a
ogg mp3, wav, flac, aac, m4a
flac mp3, wav, ogg, aac, m4a
aac mp3, wav, ogg, flac, m4a
m4a mp3, wav, ogg, flac, aac
aiff mp3, wav, ogg, flac, aac, m4a
aif mp3, wav, ogg, flac, aac, m4a (alias for AIFF)
ac3 mp3, wav, ogg, flac, aac, m4a
amr mp3, wav, ogg, flac, aac, m4a
au mp3, wav, ogg, flac, aac, m4a
caf mp3, wav, ogg, flac, aac, m4a
weba mp3, wav, ogg, flac, aac, m4a
m4b mp3, wav, ogg, flac, aac, m4a
wma mp3, wav, ogg, flac, aac, m4a (decode-only — source only)

The shared audio target set is {mp3, wav, ogg, flac, aac, m4a}. Any audio source can reach any of those targets except its own format (converting a format to itself is rejected with 400).

Note

wmv and wma are decode-only. FFmpeg can read them, so you can convert away from them, but they can never be a target format.


Blocked formats

The following formats are explicitly rejected with 400 before any work happens:

Format(s) Reason
asf ASF container uses proprietary codecs — not supported
hevc, h265 H.265/HEVC encoding requires GPU acceleration — not supported
av1 AV1 encoding is too slow on CPU for API use — not supported
mxf MXF is a professional broadcast format — not supported
r3d RED RAW files require proprietary SDK — not supported
braw Blackmagic RAW files require proprietary SDK — not supported
arw, cr2, cr3, nef, dng Camera RAW stills — not media formats
exe, bat, sh, ps1, cmd, msi, dll, so Executables — rejected
zip, tar, gz, 7z, rar Archives — rejected

Validation rules

  1. Normalisation — format strings are lowercased and stripped of whitespace and leading dots, so ".MP4", " mp4 ", and "mp4" are all equivalent.
  2. Same-format guard — source == target returns 400 ("Nothing to convert").
  3. Blocked-format guard — both source and target are checked against the blocked list first, for media conversions specifically.
  4. Known-source guard — if the source isn't in the conversion table, the API returns 400 listing accepted sources.
  5. Known-target guard — if the target isn't valid for that source, the API returns 400 listing valid targets.

REST API Examples

Video → GIF

curl -X POST "https://convert.toolkitapi.io/v1/convert/media" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/clip.mp4",
    "source_format": "mp4",
    "target_format": "gif"
  }'

Get the valid targets for a source

Send an intentionally unsupported pair and read the error — the API echoes back the supported target list:

curl -X POST "https://convert.toolkitapi.io/v1/convert/media" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/a.mp4", "source_format": "mp4", "target_format": "av1"}'
{ "detail": "Format 'av1' is not supported by this API." }

JavaScript — pick a target from the source

const MATRIX = {
  mp4:  ["webm", "gif", "mp3", "wav", "ogg", "avi"],
  webm: ["mp4", "gif", "mp3", "wav", "ogg"],
  wmv:  ["mp4", "webm", "gif", "mp3", "wav"],
  mp3:  ["wav", "ogg", "flac", "aac", "m4a"],
};

async function convert(url, sourceFormat, targetFormat) {
  const resp = await fetch("https://convert.toolkitapi.io/v1/convert/media", {
    method: "POST",
    headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
    body: JSON.stringify({ url, source_format: sourceFormat, target_format: targetFormat }),
  });
  if (!resp.ok) throw new Error((await resp.json()).detail);
  return resp.json();
}

Python — batch validate a set of pairs

import requests

API = "https://convert.toolkitapi.io/v1/convert/media"
HEADERS = {"X-API-Key": "YOUR_KEY"}

targets = {"mp4": "gif", "wmv": "mp4", "mp3": "flac", "asf": "mp4"}

for src, tgt in targets.items():
    r = requests.post(
        API,
        headers=HEADERS,
        json={"url": "https://example.com/sample", "source_format": src, "target_format": tgt},
    )
    print(f"{src} -> {tgt}: ", "OK" if r.status_code == 200 else r.json().get("detail"))

Use Cases

  • Social exports — Convert mp4/mov uploads to gif or webm for the web.
  • Audio extraction — Pull mp3/wav soundtracks out of video files.
  • Format normalisation — Ingest flv, vob, mts, or legacy formats and standardise on mp4/mp3.

Errors

Status Meaning
400 Unsupported source, invalid target, same format, or blocked format
401 Missing or invalid API key
413 Source file exceeds the size limit
422 Request body failed schema validation
503 FFmpeg unavailable on the server