Media Toolkit¶
Transcode audio and video between the formats people actually use — and pull the YouTube data (search results, playlists, transcripts) you need to feed it. Conversion is a single GET that streams the converted file straight back on the same connection: no job ID, no polling, no object storage.
Availability note: the conversion service (
apis/media) is written and tested but not yet deployed — see the module docstring inapis/media/app/main.py. The pages linked below are the contract reference for the service when it ships. The YouTube endpoints in this toolkit are documented under their own host (see Base URLs).
Base URLs¶
The toolkit's endpoints live on two hosts:
| Host | Serves |
|---|---|
https://media.toolkitapi.io |
/v1/media/convert — media transcoding |
https://youtube.toolkitapi.io |
/v1/youtube/* — search, playlists, transcripts |
Quick Start¶
Convert an MP4 fetched from a public URL to MP3:
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
import requests
with 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,
) as r:
r.raise_for_status()
with open("clip.mp3", "wb") as fh:
for chunk in r.iter_content(64 * 1024):
fh.write(chunk)
// Node 18+ — stream straight to disk
import { createWriteStream } from "node:fs";
import { Readable } from "node:stream";
import { pipeline } from "node:stream/promises";
const qs = new URLSearchParams({
url: "https://cdn.example.com/clip.mp4",
source_format: "mp4",
target_format: "mp3",
});
const res = await fetch(`https://media.toolkitapi.io/v1/media/convert?${qs}`, {
headers: { "X-API-Key": "YOUR_KEY" },
});
if (!res.ok) throw new Error(`convert failed: ${res.status}`);
await pipeline(Readable.fromWeb(res.body), createWriteStream("clip.mp3"));
Search YouTube and transcribe the top hit:
curl -G "https://youtube.toolkitapi.io/v1/youtube/search" \
-H "X-API-Key: YOUR_KEY" \
--data-urlencode "query=ffmpeg tutorial" \
--data-urlencode "limit=3"
Endpoints¶
Conversion — media.toolkitapi.io¶
| Method | Endpoint | Returns |
|---|---|---|
GET |
/v1/media/convert |
Streaming file download |
Parameters url, source_format and target_format are all required query-string values. Format strings are normalised before validation — lower-cased, whitespace-stripped, and a leading . removed — so ".MP4 " and mp4 are equivalent. To convert bytes you already hold, see Converting Your Own Bytes.
YouTube — youtube.toolkitapi.io¶
| Method | Endpoint | Returns |
|---|---|---|
GET |
/v1/youtube/search |
Video IDs, titles, thumbnails, channel, duration, views |
GET |
/v1/youtube/playlist |
Playlist metadata — title, counts, owner channel |
GET |
/v1/youtube/playlist/videos |
Ordered, de-duplicated video IDs |
GET/POST |
/v1/youtube/transcript |
Transcript for one video |
GET/POST |
/v1/youtube/transcript/batch |
Up to 20 videos at once, job-based |
Reference Pages¶
- Media Conversion Overview — what the endpoint does and when to use it
- Convert Endpoint Reference — every parameter, response header and limit
- Supported Formats & Conversion Matrix — allowed source→target pairs and output codecs
- Conversion Matrix Reference — per-target FFmpeg encoder options
- Conversion Matrix & Error Messages — the
400bodies, decoded - Format Validation Internals — normalisation order and blocked formats
- Conversion Errors & Troubleshooting — every failure mode and its cause
- Converting Your Own Bytes — patterns for data you already hold
- Transcript Errors & Retries — status codes and retry policy
- Batch Transcripts — submit-and-poll flow
- YouTube Search — query parameters and response shape
- YouTube Playlist — playlist metadata from an ID or URL
- YouTube Playlist Videos — ordered video IDs
Choosing a Source Format¶
source_format must match the container you actually link to — it is validated against the target, not probed from the file. If you are unsure of the container, take it from the URL extension and keep query strings off the url value. A mismatched pair fails fast with a 400 rather than producing a broken file.