Media Convert¶

Convert a video or audio file between container/codec formats. The synchronous endpoint fetches a media file from a public URL, transcodes it with FFmpeg, and streams the result back as a file download.

Base URL¶

https://convert.toolkitapi.io

Endpoints¶

Authentication is via the X-API-Key header (or Authorization: Bearer).

GET /v1/convert/media¶

Download a media file from url, transcode it, and stream the result back.

Query parameters¶

Response¶

200 OK with Content-Type reflecting the target container (e.g. video/webm, audio/mpeg) and a Content-Disposition: attachment; filename="converted.<ext>" header. The body is the transcoded binary stream.

Example — curl (MP4 → WebM)¶

curl -L "https://convert.toolkitapi.io/v1/convert/media?url=https://example.com/clip.mp4&source_format=mp4&target_format=webm" \
  -H "X-API-Key: $CONVERT_API_KEY" \
  -o clip.webm

Example — curl (video → animated GIF)¶

curl -L "https://convert.toolkitapi.io/v1/convert/media?url=https://example.com/clip.mp4&source_format=mp4&target_format=gif" \
  -H "X-API-Key: $CONVERT_API_KEY" \
  -o clip.gif

Example — Python (stream to disk)¶

Stream the response chunk-by-chunk so large files don't get buffered in memory.

import httpx

with httpx.stream(
    "GET",
    "https://convert.toolkitapi.io/v1/convert/media",
    headers={"X-API-Key": CONVERT_API_KEY},
    params={
        "url": "https://example.com/podcast.wav",
        "source_format": "wav",
        "target_format": "mp3",
    },
) as resp:
    resp.raise_for_status()
    with open("podcast.mp3", "wb") as f:
        for chunk in resp.iter_bytes():
            f.write(chunk)

Example — Node.js (fetch → file)¶

import { writeFile } from "node:fs/promises";

const url = new URL("https://convert.toolkitapi.io/v1/convert/media");
url.searchParams.set("url", "https://example.com/clip.mov");
url.searchParams.set("source_format", "mov");
url.searchParams.set("target_format", "mp4");

const resp = await fetch(url, { headers: { "X-API-Key": process.env.CONVERT_API_KEY } });
if (!resp.ok) throw new Error(`convert failed: ${resp.status}`);

const buffer = Buffer.from(await resp.arrayBuffer());
await writeFile("clip.mp4", buffer);

Example — JavaScript in the browser¶

const params = new URLSearchParams({
  url: "https://example.com/clip.mp4",
  source_format: "mp4",
  target_format: "webm",
});

const resp = await fetch(`https://convert.toolkitapi.io/v1/convert/media?${params}`, {
  headers: { "X-API-Key": CONVERT_API_KEY },
});
const blob = await resp.blob();
const audioUrl = URL.createObjectURL(blob);
document.querySelector("video").src = audioUrl;

Supported conversions¶

The exact matrix is returned by GET /v1/convert/supported-media-formats. Common pairs include:

Invalid source/target pairs return 400 from the format validator.

Notes¶

• The Content-Type header is mapped from the target format via the toolkit's media-type table.
• The conversion runs in a worker thread so the async event loop stays responsive.
• Source URLs are fetched server-side; private or auth-protected URLs are not supported.
• Very large files may exceed the sync request timeout — check /v1/convert/supported-media-formats and consider splitting long media.

Errors¶

See Error Handling for the shared error envelope.

Related¶

• Media Info — probe metadata before converting
• Supported Media Formats — full conversion matrix
• Video Thumbnail — extract a frame as an image
• Document — document format conversion (PDF/DOCX/EPUB)