Media Conversion¶
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.
Transcode a media file from a public URL and stream the result back. One endpoint, FFmpeg under the hood, no upload step required.
| Method | Endpoint | Purpose |
|---|---|---|
GET |
/v1/media/convert |
Download, transcode, and stream back a media file |
Base URL¶
https://media.toolkitapi.io
Requires an X-API-Key header. The response is the file - a streaming binary download, not JSON.
Quick start¶
curl¶
curl -L "https://media.toolkitapi.io/v1/media/convert?url=https%3A%2F%2Fcdn.example.com%2Fclip.mp4&source_format=mp4&target_format=mp3" \
-H "X-API-Key: YOUR_KEY" \
-o clip.mp3
Note the URL-encoded url parameter. Use -L so redirects (presigned S3 URLs, CDN hops) are followed.
import requests
resp = requests.get(
"https://media.toolkitapi.io/v1/media/convert",
headers={"X-API-Key": "YOUR_KEY"},
params={
"url": "https://cdn.example.com/clip.mp4",
"source_format": "mp4",
"target_format": "mp3",
},
stream=True,
timeout=300,
)
if resp.status_code == 200:
with open("clip.mp3", "wb") as fh:
for chunk in resp.iter_content(chunk_size=1 << 16):
fh.write(chunk)
else:
print(resp.status_code, resp.json())
const params = new URLSearchParams({
url: "https://cdn.example.com/clip.mp4",
source_format: "mp4",
target_format: "gif",
});
const resp = await fetch(`https://media.toolkitapi.io/v1/media/convert?${params}`, {
headers: { "X-API-Key": "YOUR_KEY" },
});
if (!resp.ok) throw new Error(`${resp.status} ${await resp.text()}`);
// Node: stream to disk
// import { createWriteStream } from "node:fs";
// import { Readable } from "node:stream";
// Readable.fromWeb(resp.body).pipe(createWriteStream("clip.gif"));
// Browser: blob URL for <video>/<img>
const blob = await resp.blob();
const objectUrl = URL.createObjectURL(blob);
Query parameters¶
| Parameter | Type | Description |
|---|---|---|
url |
string | Public http(s) URL of the source media file |
source_format |
string | Source container/extension, e.g. mp4 |
target_format |
string | Target container/extension, e.g. mp3 |
All three are required. Formats are case-insensitive and a leading dot is tolerated (.MP4 → mp4).
Supported conversions¶
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 |
Blocked formats¶
| Format | Reason |
|---|---|
asf |
Proprietary container codecs |
hevc, h265 |
Requires GPU encoding |
av1 |
Too slow on CPU for API use |
mxf |
Broadcast format, not supported |
r3d, braw |
Proprietary camera RAW requiring vendor SDKs |
exe, bat, sh, ps1, cmd, msi, dll, so |
Executables |
zip, tar, gz, 7z, rar |
Archives |
Same-format conversions (mp4 → mp4) are rejected - there is nothing to transcode.
Response¶
Success is a 200 with the transcoded file:
Content-Type: audio/mpeg
Content-Disposition: attachment; filename="converted.mp3"
The filename is always converted.{target} - set your own name when saving. Video formats return video/mp4, video/webm, image/gif, and so on; audio returns audio/mpeg, audio/wav, audio/flac, etc.
Practical patterns¶
Podcast to portable audio¶
def to_mp3(source_url: str, out_path: str) -> None:
resp = requests.get(
"https://media.toolkitapi.io/v1/media/convert",
headers={"X-API-Key": KEY},
params={"url": source_url, "source_format": "m4a", "target_format": "mp3"},
stream=True,
timeout=600,
)
resp.raise_for_status()
with open(out_path, "wb") as fh:
for chunk in resp.iter_content(1 << 16):
fh.write(chunk)
Video to animated GIF for docs¶
curl -L "https://media.toolkitapi.io/v1/media/convert?url=$(python3 -c 'import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=""))' 'https://cdn.example.com/demo.webm')&source_format=webm&target_format=gif" \
-H "X-API-Key: YOUR_KEY" \
-o demo.gif
Always URL-encode source URLs - presigned CDN links contain ?, &, and = that will otherwise be parsed as part of your query string.
Extract audio from a large upload¶
If the source is not publicly reachable, upload it somewhere with a signed URL first (S3, R2, GCS). The fetcher follows up to 5 redirects and allows up to 100 MB per download, with a 60-second download timeout.
Errors¶
Errors return JSON with a detail field:
| Status | Meaning |
|---|---|
400 |
Unsupported or blocked format pair, same source/target, or an invalid/private source URL |
401 |
Missing or invalid X-API-Key |
422 |
Missing required query parameter |
502 |
The source file could not be downloaded (404, TLS failure, oversized file) |
503 |
FFmpeg is unavailable on the worker |
500 |
Transcoding failed (corrupt input, unsupported codec inside the container) |
{"detail": "Cannot convert 'mp4' → 'flac'. Allowed targets for 'mp4': ['avi', 'gif', 'mp3', 'ogg', 'wav', 'webm']"}
Related¶
- YouTube Transcripts - fetch captions and video metadata before transcoding
- Rate Limits - conversions are long-running and count against concurrency
- Error Handling - retry guidance for
502/503