Supported Formats & Conversion Matrix¶
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 the source_format → target_format pair before it downloads anything. This page is the authoritative matrix, the exact encoders used for each target, and the list of formats we deliberately reject.
The matrix¶
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, mpeg, mpg, mts, m2ts, 3gp, 3g2, ts, vob, m4v, ogv, wmv |
mp4, webm, gif, mp3, wav |
Audio sources¶
| 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 |
Reading the matrix:
- Any video → audio produces an audio-only file. The common case,
mp4 → mp3, works. - Video → video is limited to
mp4,webm,gif. There is nowebm → avi; transcode viamp4if you truly need it (two calls). - Audio → video is not supported. Audio sources never list video targets.
- Same-format conversion is rejected (
mp4 → mp4returns400), even if you only wanted a re-encode.
Encoders used per target¶
These options are applied server-side; you do not control codec settings through the API.
| Target | Video codec | Audio codec | Notes |
|---|---|---|---|
mp4 |
libx264 |
aac |
+faststart – moov atom moved to the front, so HTML5 players start immediately |
webm |
libvpx-vp9 |
libopus |
-deadline realtime -cpu-used 5 – tuned for API latency, not smallest file |
gif |
– | – | fps=12, scaled to 480 px wide, lanczos, looped forever |
avi |
libx264 |
mp3 |
Legacy container, modern codecs inside |
mp3 |
– | libmp3lame |
VBR -q:a 2 (~190 kbps) |
wav |
– | pcm_s16le |
Uncompressed, 16-bit little-endian |
ogg |
– | libvorbis |
VBR -q:a 4 |
flac |
– | flac |
Lossless |
aac / m4a |
– | aac |
192 kbps |
m4b |
– | aac |
64 kbps – audiobook preset |
weba |
– | libopus |
128 kbps |
aiff / aif |
– | pcm_s16be |
Big-endian PCM |
ac3 |
– | ac3 |
192 kbps |
amr |
– | libopencore_amrnb |
Forced to 8 kHz mono |
au |
– | pcm_mulaw |
8 kHz μ-law |
caf |
– | pcm_s16le |
Apple container, PCM inside |
Practical consequences:
- GIFs are opinionated. 12 fps and 480 px wide means a GIF is not a faithful copy of a 1080p video – it is a lightweight preview. For high-quality clips use
webmormp4. - MP3 is VBR. File size scales with content complexity rather than duration.
- Every video target is H.264/VP9. If a downstream player needs H.265, this API is not the tool.
Blocked formats¶
| Format | Reason |
|---|---|
hevc, h265 |
H.265/HEVC encoding requires GPU acceleration – not supported |
av1 |
AV1 encoding is too slow on CPU for API use |
mxf |
Professional broadcast format |
r3d, braw |
Camera RAW requires a proprietary SDK |
asf |
Proprietary codecs |
exe, bat, sh, ps1, cmd, msi, dll, so |
Executables – rejected outright |
zip, tar, gz, 7z, rar |
Archives – rejected outright |
Both the source and target are checked against this list. Note hevc/av1 cannot even be a source – if you need to go from HEVC to H.264, convert locally first.
Limits that affect conversions¶
| Limit | Value | Behaviour |
|---|---|---|
| Max source download | 100 MB | 400 with Downloaded content exceeds maximum size of 100 MB |
| Redirects followed | 5 | More than 5 is an error |
| Private/internal network URLs | blocked | SSRF protection – 400 |
| Output delivery | streaming | The response body is the file; there is no JSON wrapper |
| Sync timeout | server-side | Very long transcodes can time out – prefer short clips or split first |
The 100 MB cap is on the input file, not the output. A 90 MB MP4 can produce a smaller MP3 or a larger wav. Because wav and flac are lossless, they are common ways to blow past output budgets.
Validating a pair cheaply¶
You can probe a pair without paying for a transcode: send an http://localhost/ URL with the pair you care about. Format validation runs before the download, so a valid pair fails later with 502 Failed to download source file while an invalid pair fails with 400 and a descriptive message.
# Valid pair, bad URL → 502
curl -s "https://media.toolkitapi.io/v1/media/convert?url=http://localhost/x&source_format=mp4&target_format=mp3" \
-H "X-API-Key: YOUR_KEY"
# Invalid pair → 400 with the allowed targets listed
curl -s "https://media.toolkitapi.io/v1/media/convert?url=http://localhost/x&source_format=mp3&target_format=mp4" \
-H "X-API-Key: YOUR_KEY"
The 400 body names every allowed target for the source, which is handy for building a UI dropdown:
{ "detail": "Cannot convert 'mp3' → 'mp4'. Allowed targets for 'mp3': ['aac', 'flac', 'm4a', 'ogg', 'wav']" }
Common conversions¶
Extract audio from a video¶
curl -L "https://media.toolkitapi.io/v1/media/convert?url=https%3A%2F%2Fcdn.example.com%2Ftalk.mp4&source_format=mp4&target_format=mp3" \
-H "X-API-Key: YOUR_KEY" -o talk.mp3
Make a web-friendly clip¶
curl -L "https://media.toolkitapi.io/v1/media/convert?url=https%3A%2F%2Fcdn.example.com%2Fdemo.mov&source_format=mov&target_format=webm" \
-H "X-API-Key: YOUR_KEY" -o demo.webm
Turn a screen recording into a looping GIF preview¶
import requests
resp = requests.get(
"https://media.toolkitapi.io/v1/media/convert",
headers={"X-API-Key": "YOUR_KEY"},
params={
"url": "https://cdn.example.com/screen.mp4",
"source_format": "mp4",
"target_format": "gif",
},
stream=True,
timeout=180,
)
resp.raise_for_status()
with open("screen.gif", "wb") as fh:
for chunk in resp.iter_content(1 << 16):
fh.write(chunk)
# Result is 480px wide, 12fps
Two-step: WebM → AVI¶
Not directly supported. Go through MP4:
async function convert(apiKey, url, source, target) {
const qs = new URLSearchParams({ url, source_format: source, target_format: target });
const resp = await fetch(`https://media.toolkitapi.io/v1/media/convert?${qs}`, {
headers: { "X-API-Key": apiKey },
});
if (!resp.ok) throw new Error(`${resp.status}: ${await resp.text()}`);
return Buffer.from(await resp.arrayBuffer());
}
// Hop 1: webm → mp4, upload the intermediate somewhere public
// Hop 2: mp4 → avi using the URL from hop 1
Each hop requires the intermediate to be reachable by URL – the API does not accept uploads, only public url inputs.
Error reference¶
| Status | Meaning |
|---|---|
400 |
Invalid or unsupported pair, same-format request, blocked format, SSRF-rejected URL, or source over 100 MB |
422 |
Missing required query param (url, source_format, target_format) |
503 |
FFmpeg unavailable on the host – retry later |
502 |
Source could not be downloaded (404, auth-protected, redirect loop) |
500 |
FFmpeg failed mid-transcode (corrupt input, undecodable stream) |
See also¶
- Media Conversion – request/response walkthrough and streaming patterns
- Batch Transcripts – YouTube transcript jobs on the same base URL