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

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']"}