Media Convert 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.

One endpoint does all media conversion: fetch a file from a public URL, transcode it with FFmpeg, stream the result straight back as a download. No job IDs, no polling, no object storage — the bytes come back on the same connection.

For the format matrix see Conversion Matrix; for failure modes see Conversion Errors & Troubleshooting.

Base URL

https://media.toolkitapi.io

Endpoint

Method Endpoint Auth Returns
GET /v1/media/convert X-API-Key Streaming file download

Parameters

All three are required query-string parameters. There is no JSON body variant.

Parameter Type Description
url string (URL) Public HTTP(S) URL of the source media file
source_format string Extension of the source, e.g. mp4, mov, wav
target_format string Desired output extension, e.g. mp3, webm, gif

Both format values are normalised before validation: lower-cased, whitespace-stripped, and a leading . is removed — so ".MP4 " and mp4 are equivalent.

Validation order, and what each failure returns:

  1. source_format == target_format → 400 Source and target formats are the same: 'mp4'
  2. Source or target in the blocked list → 400 with a specific reason (H.265/HEVC encoding requires GPU acceleration — not supported)
  3. Unknown source → 400 Unsupported source format: 'xyz'. Supported: [...]
  4. Pair not in the allow-list → 400 Cannot convert 'mp4' → 'flac'. Allowed targets for 'mp4': [...]

Tip

Because validation happens before the download, you can use a deliberately wrong pair as a cheap, zero-bandwidth way to discover the allow-list for a source — the 400 message lists every permitted target.


Response

On success: 200 OK with the transcoded bytes as the body.

Header Value
Content-Type MIME type of the target format (e.g. audio/mpeg, video/mp4, image/gif)
Content-Disposition attachment; filename="converted.<target_format>"

There is no Content-Length — the response is streamed from an in-memory buffer, and the filename is always literally converted.<ext>; there is no parameter to rename it. If you need a meaningful name, set it client-side from your own metadata.

Limits

Limit Value
Source download size 100 MB (MAX_DOWNLOAD_SIZE)
Source fetch timeout 60 s (_FETCH_TIMEOUT)
Transcode synchronous, in-process, whole file buffered

Media files are large, so the caps here are far more generous than the 5–10 MB limits on the convert endpoints. Anything above 100 MB returns 400 Downloaded content exceeds maximum size of 100 MB.

URLs are passed through an SSRF guard: only http/https are accepted (file:, ftp:, data: → 400), the hostname must resolve, and private/internal/reserved addresses (127.0.0.1, 10.x, 169.254.x, ::1, …) are rejected with 400. The check runs on the hostname as written — redirects are followed (up to 5) without re-validating each hop, so do not rely on this guard alone if you proxy untrusted URLs.


Exact output options

Conversions are not parameter-tunable — each target has a fixed FFmpeg profile. Practical consequences:

Target Encoder Notes
mp4 libx264 + aac, +faststart Web-optimised; streamable before full download
webm libvpx-vp9 + libopus, deadline=realtime, cpu-used=5 Faster-than-best-quality VP9; larger files than a 2-pass encode
gif fps=12, scale=480:-1, lanczos, infinite loop Always resized to 480 px wide at 12 fps — you cannot request a larger GIF
avi libx264 + mp3 H.264 inside AVI for legacy players
mp3 libmp3lame, q:a=2 VBR ~190 kbps, video stream dropped
wav pcm_s16le Uncompressed 16-bit — expect ~10 MB/min
ogg libvorbis, q:a=4 ~128 kbps VBR
flac flac Lossless
aac / m4a aac, 192 kbps m4a is the same encode in an MP4 container
m4b aac, 64 kbps Audiobook profile
weba libopus, 128 kbps
aiff pcm_s16be
ac3 ac3, 192 kbps
amr libopencore_amrnb, 8 kHz mono Narrowband speech only
au pcm_mulaw, 8 kHz

All audio targets include -vn, so video streams are dropped rather than copied.

Warning

The fixed gif profile is the most common surprise: asking for mp4 → gif on a 1080p source gives you a 480 px, 12 fps GIF. For higher-fidelity GIFs, transcode elsewhere; for previews, this is usually exactly right.


Examples

Video → audio (extract the soundtrack)

curl -L "https://media.toolkitapi.io/v1/media/convert?url=https%3A%2F%2Fexample.com%2Ftalk.mp4&source_format=mp4&target_format=mp3" \
  -H "X-API-Key: $MEDIA_API_KEY" \
  -o talk.mp3
import httpx

with httpx.stream(
    "GET",
    "https://media.toolkitapi.io/v1/media/convert",
    headers={"X-API-Key": MEDIA_API_KEY},
    params={
        "url": "https://example.com/talk.mp4",
        "source_format": "mp4",
        "target_format": "mp3",
    },
    follow_redirects=True,
    timeout=httpx.Timeout(60.0, read=300.0),   # long read: transcode happens inline
) as resp:
    resp.raise_for_status()
    with open("talk.mp3", "wb") as fh:
        for chunk in resp.iter_bytes(1 << 16):
            fh.write(chunk)

print(resp.headers["content-type"])    # audio/mpeg
import { createWriteStream } from "node:fs";
import { Readable } from "node:stream";
import { pipeline } from "node:stream/promises";

const url = new URL("https://media.toolkitapi.io/v1/media/convert");
url.searchParams.set("url", "https://example.com/talk.mp4");
url.searchParams.set("source_format", "mp4");
url.searchParams.set("target_format", "mp3");

const res = await fetch(url, { headers: { "X-API-Key": process.env.MEDIA_API_KEY } });
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);

await pipeline(Readable.fromWeb(res.body), createWriteStream("talk.mp3"));

Short clip → GIF preview

curl -L "https://media.toolkitapi.io/v1/media/convert?url=https%3A%2F%2Fexample.com%2Fdemo.webm&source_format=webm&target_format=gif" \
  -H "X-API-Key: $MEDIA_API_KEY" \
  -o preview.gif
r = httpx.get(
    "https://media.toolkitapi.io/v1/media/convert",
    headers={"X-API-Key": MEDIA_API_KEY},
    params={"url": "https://example.com/demo.webm", "source_format": "webm", "target_format": "gif"},
    follow_redirects=True,
    timeout=httpx.Timeout(60.0, read=300.0),
)
r.raise_for_status()
open("preview.gif", "wb").write(r.content)

Discover valid targets for a source

Send a deliberately invalid target; validation runs before any download, so the 400 lists every allowed target for free:

curl -s "https://media.toolkitapi.io/v1/media/convert?url=https%3A%2F%2Fexample.com%2Fx.mp4&source_format=mp4&target_format=__probe__" \
  -H "X-API-Key: $MEDIA_API_KEY" | jq -r '.detail'
# Cannot convert 'mp4' → '__probe__'. Allowed targets for 'mp4': ['avi', 'gif', 'mp3', 'ogg', 'wav', 'webm']
import httpx

resp = httpx.get(
    "https://media.toolkitapi.io/v1/media/convert",
    headers={"X-API-Key": MEDIA_API_KEY},
    params={"url": "https://example.com/x.mp4", "source_format": "mp4", "target_format": "__probe__"},
    timeout=10,
)
print(resp.status_code)        # 400
print(resp.json()["detail"])   # ... Allowed targets for 'mp4': [...]

Errors

Status Meaning Retry?
400 Bad pair, blocked format, SSRF-refused URL, source > 100 MB, unreachable URL No — fix the request
401 Missing / invalid API key No
422 A required query parameter is missing No
500 FFmpeg failed on the input (corrupt or mislabelled file) No — the source is bad
502 The source download failed (non-2xx/3xx response, connection error, TLS failure, redirect loop > 5) Yes for transient errors; no for a 404 on the source
503 FFmpeg binary not present on the host No — transient platform issue, retry later

The 500 case is the one that trips people up: a file whose extension says mp4 but whose contents are something else will pass validation (which looks only at the strings) and then fail in FFmpeg. Verify the container with ffprobe before blaming the API.