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 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 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_bytes rather 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; Range headers are ignored.

See also