Media Conversion Matrix & Error Messages¶
GET /v1/media/convert is a streaming transcoder: you hand it a URL plus a source and target format, and it downloads, transcodes with FFmpeg, and streams the result back. There is no request body, no polling, and no job ID — the call is synchronous and the response is the file.
That makes the format pair the entire API surface. This page documents the exact allow-list the validator enforces and maps every failure message to a cause, so you can fail fast client-side instead of burning a download.
Endpoint: GET https://media.toolkitapi.io/v1/media/convert?url=...&source_format=...&target_format=... — requires X-API-Key.
For a first conversion walkthrough and response headers, see Convert Endpoint. For a narrative overview of the format families, see Format Matrix and Conversion Matrix Reference.
Parameters¶
| Param | Type | Required | Notes |
|---|---|---|---|
url |
string | Yes | Public URL of the source file. Must be fetchable by the service (SSRF-guarded). |
source_format |
string | Yes | e.g. mp4, mp3, .MOV. Normalised before checking. |
target_format |
string | Yes | e.g. mp3, webm. Normalised before checking. |
Normalisation¶
Both format strings are lowercased, stripped of surrounding whitespace, and have one leading dot removed. So .MP4, MP4, and mp4 are all the same. Extensions with internal dots or parameters (mp4?x=1) are not handled — pass the bare extension.
The allow-list¶
The matrix is not symmetric. Each source lists its own permitted targets, and several sources can produce formats that cannot convert back to the same place. mp4 → avi is allowed; avi → ogg is not.
Video sources¶
| Source | Allowed 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 |
mts |
mp4, webm, gif, mp3, wav |
m2ts |
mp4, webm, gif, mp3, wav |
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 |
The common set (mp4, webm, gif, mp3, wav) is what the long tail of container formats can reach. Note that ogg is only reachable from mp4 and webm, and avi only from mp4.
Audio sources¶
Audio sources can convert among mp3, wav, ogg, flac, aac, m4a — but never to themselves. Each of those six accepts the other five. The following convert to that same six:
aiff, aif, ac3, amr, au, caf, weba, m4b, wma
So wma → flac works, flac → wma does not (wma is not a target), and the same-format check fires before the allow-list is consulted.
Video → audio¶
Every video source except gif can reach at least mp3; most also reach wav. Extracting audio from a video is just a target of mp3 or wav — there's no separate endpoint.
Blocked formats¶
These are rejected outright, from either side of the pair, with a specific reason:
| Format(s) | Message |
|---|---|
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 |
exe, bat, sh, ps1, cmd, msi, dll, so |
Format not supported |
zip, tar, gz, 7z, rar |
Format not supported |
The executable and archive entries exist so that a URL ending in .zip can't be used to push a non-media payload through the transcoder. They're blocked on the format name, not sniffed from content, so a media file served from a .zip URL still has to declare a real media format.
Error messages and what they mean¶
All validation failures return HTTP 400 with a detail string. Match on the prefix, not the whole sentence — the supported-format lists embedded in some messages are long and change with the matrix.
| Status | detail pattern |
Cause |
|---|---|---|
| 400 | Source and target formats are the same: '<fmt>' |
src == tgt after normalisation |
| 400 | Unsupported source format: '<fmt>'. Supported: [...] |
Source isn't a key in the matrix |
| 400 | Cannot convert '<src>' → '<tgt>'. Allowed targets for '<src>': [...] |
Source is known, target isn't in its set |
| 400 | blocked-format reason (see table above) | Source or target is on the blocked list |
| 400 | download validation message | url rejected by the fetch guard (bad scheme, private address) |
| 502 | Failed to download source file |
Fetch failed for any other reason — 404, DNS, timeout, TLS |
| 500 | FFmpeg error text | Transcode failed (corrupt input, unsupported codec inside a supported container) |
| 503 | FFmpeg unavailable | Binary missing or ffmpeg -version check failed on the host |
The 500 path is the one you'll hit with inputs that look valid: an .mp4 whose stream is actually HEVC, or a truncated file. The detail carries the FFmpeg stderr, which is useful in logs and useless to end users.
Success response¶
On success you get the bytes, not JSON:
Content-Typefrom a fixed map —video/mp4,video/webm,image/gif,audio/mpeg,audio/wav,audio/ogg,audio/flac,application/octet-streamfor anything unlisted.Content-Disposition: attachment; filename="converted.<target>"— the filename is always this generic name, so set your own on the client if you're persisting the file.- The body is a stream; there's no
Content-Lengthguarantee. Don't preallocate based on a HEAD probe.
Examples¶
curl — matrix-safe conversion with a clear error print¶
curl -sS -D headers.txt \
-H "X-API-Key: $TOOLKIT_API_KEY" \
"https://media.toolkitapi.io/v1/media/convert?url=https%3A%2F%2Fcdn.example.com%2Fclip.mp4&source_format=mp4&target_format=webm" \
-o clip.webm
# Non-2xx responses are JSON, so check the content type before treating the body as media
grep -i '^content-type' headers.txt
[ -s clip.webm ] && file clip.webm
Python — validate locally, then convert¶
import requests
BASE = "https://media.toolkitapi.io/v1/media/convert"
H = {"X-API-Key": API_KEY}
VIDEO = {
"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"},
}
COMMON = {"mp4", "webm", "gif", "mp3", "wav"}
for src in ("flv", "mpeg", "mpg", "mts", "m2ts", "3gp", "3g2", "ts", "vob", "m4v", "ogv", "wmv"):
VIDEO[src] = COMMON
AUDIO_CORE = {"mp3", "wav", "ogg", "flac", "aac", "m4a"}
for src in AUDIO_CORE:
VIDEO[src] = AUDIO_CORE - {src}
for src in ("aiff", "aif", "ac3", "amr", "au", "caf", "weba", "m4b", "wma"):
VIDEO[src] = AUDIO_CORE
def can_convert(src: str, tgt: str) -> bool:
return tgt in VIDEO.get(src.lower().lstrip("."), set())
def convert(url: str, src: str, tgt: str, out_path: str) -> str | None:
# Fail fast — the API rejects these before downloading, so skip the round trip.
if not can_convert(src, tgt):
return f"unsupported pair {src} -> {tgt}"
with requests.get(
BASE,
headers=H,
params={"url": url, "source_format": src, "target_format": tgt},
stream=True,
timeout=300,
) as r:
if r.status_code != 200:
return f"{r.status_code}: {r.json().get('detail', 'unknown')}"
with open(out_path, "wb") as fh:
for chunk in r.iter_content(1 << 16):
fh.write(chunk)
return None
print(convert("https://cdn.example.com/clip.mp4", "mp4", "webm", "clip.webm"))
print(convert("https://cdn.example.com/clip.gif", "gif", "ogg", "x.ogg")) # gif→ogg is not allowed
JavaScript — stream to a file in Node¶
import { createWriteStream } from "node:fs";
import { Readable } from "node:stream";
import { pipeline } from "node:stream/promises";
async function convertMedia(url, sourceFormat, targetFormat, outPath) {
const qs = new URLSearchParams({
url,
source_format: sourceFormat,
target_format: targetFormat,
});
const res = await fetch(`https://media.toolkitapi.io/v1/media/convert?${qs}`, {
headers: { "X-API-Key": process.env.TOOLKIT_API_KEY },
});
if (!res.ok) {
// Errors are JSON; success is a binary stream.
const body = await res.json().catch(() => ({}));
throw new Error(`${res.status} ${body.detail ?? "conversion failed"}`);
}
await pipeline(Readable.fromWeb(res.body), createWriteStream(outPath));
return outPath;
}
Related¶
- Convert Endpoint — minimal request and response reference.
- Format Matrix — human-readable grouping of supported formats.
- Conversion Errors & Troubleshooting — diagnosing 500/502/503 responses.
- Format Validation Internals — deeper look at the validator and blocked-list rationale.