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¶
- Normalisation — format strings are lowercased and stripped of whitespace and
leading dots, so
".MP4"," mp4 ", and"mp4"are all equivalent. - Same-format guard — source == target returns
400("Nothing to convert"). - Blocked-format guard — both source and target are checked against the blocked list first, for media conversions specifically.
- Known-source guard — if the source isn't in the conversion table, the API
returns
400listing accepted sources. - Known-target guard — if the target isn't valid for that source, the API
returns
400listing 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/movuploads togiforwebmfor the web. - Audio extraction — Pull
mp3/wavsoundtracks out of video files. - Format normalisation — Ingest
flv,vob,mts, or legacy formats and standardise onmp4/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 |