Media¶

5 endpoints for video and audio conversion, thumbnail extraction, and metadata probing.

Python SDK Examples¶

Convert MP4 to WebM¶

Pass a public URL of the source file. Small files complete synchronously; large files return a job ID for async polling.

from toolkitapi import Convert

cv = Convert(api_key="tk_...")

result = cv.media(
    url="https://toolkitapi.io/videos/clip.mp4",
    source_format="mp4",
    target_format="webm",
)

# Small file — result contains the download URL directly
if result.get("status") == "completed":
    print(result["file_url"])
# Large file — poll the job
elif "job_id" in result:
    final = cv.wait_for_job(result["job_id"])
    print(final["file_url"])

Convert with wait_for_job helper¶

wait_for_job polls until the job completes or raises ToolkitAPIError on failure or timeout.

from toolkitapi import Convert, ToolkitAPIError

cv = Convert(api_key="tk_...", timeout=60.0)

response = cv.media(
    url="https://toolkitapi.io/videos/webinar.mov",
    source_format="mov",
    target_format="mp4",
)

if "job_id" in response:
    try:
        result = cv.wait_for_job(response["job_id"], timeout=300.0)
        print(f"Download: {result['file_url']}")
    except ToolkitAPIError as e:
        print(f"Conversion failed: {e}")
else:
    print(f"Download: {response['file_url']}")

Convert audio format¶

from toolkitapi import Convert

cv = Convert(api_key="tk_...")

result = cv.media(
    url="https://toolkitapi.io/audio/podcast.wav",
    source_format="wav",
    target_format="mp3",
)

if "job_id" in result:
    result = cv.wait_for_job(result["job_id"])

print(result["file_url"])

Stream converted media to disk¶

Use media_file() to stream the converted file directly to disk. This always completes synchronously.

from toolkitapi import Convert

cv = Convert(api_key="tk_...")

path = cv.media_file(
    url="https://toolkitapi.io/videos/short-clip.mp4",
    source_format="mp4",
    target_format="gif",
    output_path="clip.gif",
)
print(f"Saved to {path}")

Extract a video thumbnail¶

Pull a specific frame from a video as a PNG or JPEG image.

from toolkitapi import Convert
import base64
from pathlib import Path

cv = Convert(api_key="tk_...")

result = cv.video_thumbnail(
    url="https://toolkitapi.io/videos/presentation.mp4",
    timestamp="00:00:05",
    format="png",
)

# result["image"] is base64-encoded
Path("thumbnail.png").write_bytes(base64.b64decode(result["image"]))
print(f"Resolution: {result['width']}x{result['height']}")

Probe media metadata¶

Get duration, codec, resolution, bitrate, and stream details before converting.

from toolkitapi import Convert

cv = Convert(api_key="tk_...")

info = cv.media_info(url="https://toolkitapi.io/videos/clip.mp4")

print(f"Duration:   {info['duration']:.1f}s")
print(f"Resolution: {info.get('width')}x{info.get('height')}")
print(f"Video codec: {info.get('video_codec')}")
print(f"Audio codec: {info.get('audio_codec')}")
print(f"Bitrate:    {info.get('bitrate')} bps")

List supported formats¶

from toolkitapi import Convert

cv = Convert(api_key="tk_...")

formats = cv.supported_media_formats()

print("Video conversions:")
for pair in formats.get("video", []):
    print(f"  {pair['from']} → {pair['to']}")

print("\nAudio conversions:")
for pair in formats.get("audio", []):
    print(f"  {pair['from']} → {pair['to']}")

Request Parameters — POST /v1/convert/media¶

Request Parameters — POST /v1/convert/video-thumbnail¶

Request Parameters — POST /v1/convert/media-info¶

Response Fields — Conversion¶

Response Fields — Thumbnail¶