Conversion Matrix Reference¶
Availability note: this endpoint lives in the standalone Media service (
apis/media), which is written but not yet deployed (see the module docstring inapis/media/app/main.py). There is no live host serving/v1/media/converttoday, and the equivalent route in the Convert service (/v1/convert/media) is also no longer registered. Use this page as the contract reference for the service when it ships.
GET /v1/media/convert validates your source_format → target_format pair before downloading anything. This page is the authoritative reference for what passes that check, which encoder each target format uses, and how failures are reported.
For the task-oriented walkthrough, see Media Conversion. For a narrative overview of format coverage, see Format Matrix.
Endpoint¶
GET /v1/media/convert?url={source_url}&source_format={src}&target_format={tgt}
Base URL: https://media.toolkitapi.io
| Query parameter | Type | Required | Description |
|---|---|---|---|
url |
string | Yes | Public URL of the source media file. Must be reachable over HTTP(S). |
source_format |
string | Yes | Source container/extension, e.g. mp4. Case-insensitive, leading . allowed. |
target_format |
string | Yes | Target container/extension, e.g. mp3. Case-insensitive, leading . allowed. |
Both format values are normalised before validation: lowercased, whitespace-trimmed, and a leading dot is stripped. ?source_format=.MP4 is therefore equivalent to mp4.
The response body is the converted file (streaming binary download, not JSON):
| Response header | Value |
|---|---|
Content-Type |
MIME type for the target format (video/mp4, audio/mpeg, …) |
Content-Disposition |
attachment; filename="converted.{target_format}" |
Accepted video conversions¶
| 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, mpeg, mpg, mts, m2ts, 3gp, 3g2, ts, vob, m4v, ogv, wmv |
mp4, webm, gif, mp3, wav |
Everything in the last row maps to {mp4, webm, gif, mp3, wav} — the "core video targets" set.
Accepted audio conversions¶
Audio sources all share one target set: mp3, wav, ogg, flac, aac, m4a — minus the source itself.
| Source | Allowed 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, aif, ac3, amr, au, caf, weba, m4b, wma |
mp3, wav, ogg, flac, aac, m4a |
Video → audio (extraction)¶
Video sources may target audio formats; the video stream is dropped (-vn). Practical pairs:
| From | To | Notes |
|---|---|---|
mp4, mov, mkv |
mp3 |
Most common — soundtrack extraction |
mp4, webm |
wav |
Lossless PCM for further processing |
gif |
— | GIFs have no audio track; only mp4/webm targets are allowed |
flac, aac, and m4a are not reachable directly from video sources — convert to wav or mp3 first, then re-run with the audio source format.
Audio → video is not supported¶
There is no audio → video path. mp3 → mp4 returns 400.
Blocked formats¶
These are rejected in either position, with a specific reason in detail:
| Format | 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 |
exe, bat, sh, ps1, cmd, msi, dll, so |
Executable/script formats are never transcoded |
zip, tar, gz, 7z, rar |
Archives are never transcoded |
Encoder options per target format¶
The service applies fixed, opinionated FFmpeg flags per target. These are not configurable through the API — they are listed so you can predict output characteristics.
| Target | Video codec | Audio codec | Extra options |
|---|---|---|---|
mp4 |
libx264 |
aac |
movflags=+faststart (streams before full download) |
webm |
libvpx-vp9 |
libopus |
deadline=realtime, cpu-used=5 (fast, not archival quality) |
gif |
— | — | fps=12, scale=480:-1:flags=lanczos, infinite loop |
avi |
libx264 |
mp3 |
— |
mp3 |
— | libmp3lame |
q:a=2 (VBR, ~190 kbps) |
wav |
— | pcm_s16le |
16-bit PCM |
ogg |
— | libvorbis |
q:a=4 |
flac |
— | flac |
Lossless |
aac |
— | aac |
b:a=192k |
m4a |
— | aac |
b:a=192k |
aiff |
— | pcm_s16be |
— |
ac3 |
— | ac3 |
b:a=192k |
amr |
— | libopencore_amrnb |
ar=8000, ac=1 (narrowband mono) |
au |
— | pcm_mulaw |
ar=8000 |
caf |
— | pcm_s16le |
— |
weba |
— | libopus |
b:a=128k |
m4b |
— | aac |
b:a=64k (audiobook profile) |
Note
GIF output is always 12 fps, 480 px wide (height auto-scaled), and loops forever. If you need a different size or rate, transcode downstream from mp4/webm instead.
Fetch limits¶
The source URL is downloaded in full before transcoding begins.
| Limit | Value |
|---|---|
| Max file size | 100 MB |
| Download timeout | 60 s (connect + read) |
| Redirects followed | Up to 5 |
| TLS verification | Enforced |
Exceeding the size cap returns 400 with a message naming the 100 MB limit. A slow origin that does not finish within 60 s results in 502.
Error reference¶
| Status | Cause | detail shape |
|---|---|---|
400 |
source_format == target_format |
Source and target formats are the same: 'mp4' |
400 |
Source or target in the blocked list | Blocked-format reason from the table above |
400 |
Unknown source format | Unsupported source format: 'xyz'. Supported: [...] |
400 |
Pair not allowed | Cannot convert 'gif' → 'mp3'. Allowed targets for 'gif': ['mp4', 'webm'] |
400 |
Source file exceeds 100 MB | Size-limit message |
502 |
Origin download failed | Failed to download source file |
503 |
ffmpeg/ffprobe missing on the worker |
Availability error |
500 |
FFmpeg exited non-zero | FFmpeg conversion failed: <first 500 chars of stderr> |
Validation runs before the download, so a bad format pair fails instantly without wasting bandwidth.
Examples¶
Preview the pair before calling (pre-flight check)¶
There is no dry-run endpoint — replicate the rules client-side to fail fast:
VIDEO_TARGETS = {"mp4", "webm", "gif", "mp3", "wav", "ogg"}
AUDIO_TARGETS = {"mp3", "wav", "ogg", "flac", "aac", "m4a"}
CORE_VIDEO = {"mp4", "webm", "gif", "mp3", "wav"}
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"},
}
VIDEO.update({
s: CORE_VIDEO for s in
["flv", "mpeg", "mpg", "mts", "m2ts", "3gp", "3g2", "ts", "vob", "m4v", "ogv", "wmv"]
})
AUDIO = {
s: AUDIO_TARGETS - {s} for s in
["mp3", "wav", "ogg", "flac", "aac", "m4a"]
}
AUDIO.update({
s: AUDIO_TARGETS for s in
["aiff", "aif", "ac3", "amr", "au", "caf", "weba", "m4b", "wma"]
})
ALLOWED = {**VIDEO, **AUDIO}
def is_supported(src: str, tgt: str) -> bool:
src, tgt = src.lower().strip().lstrip("."), tgt.lower().strip().lstrip(".")
return src != tgt and tgt in ALLOWED.get(src, set())
print(is_supported("MP4", "mp3")) # True
print(is_supported("gif", "mp3")) # False (GIF has no audio)
print(is_supported("mp3", "mp4")) # False (no audio → video)
curl — extract audio from a video¶
curl -L "https://media.toolkitapi.io/v1/media/convert?url=https%3A%2F%2Fcdn.example.com%2Fpromo.mp4&source_format=mp4&target_format=mp3" \
-H "X-API-Key: YOUR_KEY" \
-o promo.mp3
JavaScript — handle the validation error body¶
const params = new URLSearchParams({
url: "https://cdn.example.com/clip.gif",
source_format: "gif",
target_format: "mp3",
});
const resp = await fetch(`https://media.toolkitapi.io/v1/media/convert?${params}`, {
headers: { "X-API-Key": "YOUR_KEY" },
});
if (!resp.ok) {
const { detail } = await resp.json(); // validation errors are JSON
throw new Error(`convert failed: ${detail}`);
}
// success is a binary stream, not JSON
const filename = "converted.mp3";
const bytes = new Uint8Array(await resp.arrayBuffer());
Python — probe a pair, then convert¶
import httpx
API = "https://media.toolkitapi.io/v1/media/convert"
HEADERS = {"X-API-Key": "tk_..."}
def convert(src_url: str, src_fmt: str, tgt_fmt: str, out_path: str) -> str:
with httpx.stream(
"GET", API, headers=HEADERS,
params={"url": src_url, "source_format": src_fmt, "target_format": tgt_fmt},
timeout=120, follow_redirects=True,
) as resp:
if resp.status_code != 200:
resp.read()
raise RuntimeError(resp.json().get("detail", resp.text))
with open(out_path, "wb") as fh:
for chunk in resp.iter_bytes(chunk_size=64 * 1024):
fh.write(chunk)
return resp.headers.get("content-disposition", out_path)
print(convert("https://cdn.example.com/demo.webm", "webm", "mp4", "demo.mp4"))
Operational notes¶
- Stream the response. Conversions can be large; use
stream/iter_bytesrather than buffering the whole body. - One request, one conversion. There is no batch endpoint — issue sequential requests, and keep concurrency modest since each job spawns an FFmpeg process.
- Cold-start FFmpeg. The first call after an idle period pays process-spawn cost; use a client timeout of at least 120 s.
- No range requests. The endpoint always converts the whole file;
Rangeheaders are ignored.
See also¶
- Media Conversion — task-oriented walkthrough with common recipes
- Format Matrix — supported formats at a glance
- Batch Transcripts — audio → text in bulk