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 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.
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:
source_format == target_format→400 Source and target formats are the same: 'mp4'- Source or target in the blocked list →
400with a specific reason (H.265/HEVC encoding requires GPU acceleration — not supported) - Unknown source →
400 Unsupported source format: 'xyz'. Supported: [...] - 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.
Related¶
- Media Toolkit Overview — quick start
- Conversion Matrix — every allowed pair and blocked format
- Format Matrix — MIME types per format
- Conversion Errors & Troubleshooting — diagnosing failures