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-Type from a fixed map — video/mp4, video/webm, image/gif, audio/mpeg, audio/wav, audio/ogg, audio/flac, application/octet-stream for 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-Length guarantee. 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;
}