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 in apis/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

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.