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 in apis/media/app/main.py). There is no live host serving /v1/media/convert today, 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 no webm → avi; transcode via mp4 if you truly need it (two calls).
  • Audio → video is not supported. Audio sources never list video targets.
  • Same-format conversion is rejected (mp4 → mp4 returns 400), 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 webm or mp4.
  • 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