Video files are everywhere—training clips, product demos, social media exports, and meeting recordings—but many AI agents cannot inspect or transform them without a separate video-processing pipeline.
Agent Media Tools offers five video utility APIs that fit into a curl command, plus three matching MCP tools for URL-based agent workflows. Together they cover common processing tasks:
You do not need ffmpeg on your machine, a GPU, or an API key for these basic REST endpoints. Normal service safeguards and resource limits still apply. For agent workflows that start from public URLs, the MCP tools video_thumbnail, trim_video, and video_to_gif download the video and return a temporary result link.
| Tool | curl / REST | MCP (Agent) | Auth |
|---|---|---|---|
| Video Info | GET /api/video/info?url=... |
— | None |
| Thumbnail | POST /api/video/thumbnail (multipart) |
video_thumbnail |
None |
| Trim / Clip | POST /api/video/trim (multipart) |
trim_video |
None |
| GIF | POST /api/video/gif (multipart) |
video_to_gif |
None |
| Audio Extract | POST /api/video/audio (multipart) |
— | None |
The upload endpoints accept common video containers supported by the service's ffmpeg installation. The maximum output clip length for trimming is 10 minutes.
/api/video/info)Before you process a video it helps to know what you're dealing with: how long is it, what resolution, what codec? The info endpoint accepts a public URL and returns structured metadata powered by ffprobe (for direct media URLs) or yt-dlp (for YouTube, Vimeo, and other streaming sites).
curl "https://agentmediatools.com/api/video/info?url=https://test-videos.s3.amazonaws.com/sample.mp4"
Response:
{
"success": true,
"filename": "https://test-videos.s3.amazonaws.com/sample.mp4",
"duration_s": 30.04,
"size_bytes": 1055736,
"bitrate": "281224",
"video": {
"codec": "h264",
"w": 1280,
"h": 720
},
"audio": {
"codec": "aac",
"channels": 2,
"sample_rate": 44100
},
"source": "ffprobe"
}
For supported platform pages, including many YouTube and Vimeo URLs, the response can include the title, uploader, and selected stream metadata. Platform availability can change upstream:
curl "https://agentmediatools.com/api/video/info?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ"
/api/video/thumbnail + MCP video_thumbnail)Grab a single JPEG frame from any video at a specific timestamp. Defaults to the 1-second mark if you don't specify a time.
curl -X POST https://agentmediatools.com/api/video/thumbnail \ -F "video=@meeting-recording.mp4" \ -F "time=120.5"
Response:
{
"success": true,
"url": "/downloads/t-1719524567890.jpg",
"size": 84532,
"time_s": 120.5
}
You can also use HH:MM:SS format: time=02:00.5 for the same frame.
import requests
resp = requests.post(
"https://agentmediatools.com/api/video/thumbnail",
files={"video": open("demo.mp4", "rb")},
data={"time": "5"}
)
result = resp.json()
# result["url"] → "/downloads/t-17195....jpg"
# Prepend https://agentmediatools.com for the full URL
{
"name": "video_thumbnail",
"arguments": {
"video_url": "https://example.com/clip.mp4",
"time": "30"
}
}
The MCP tool downloads the public URL, submits it to the thumbnail endpoint, and returns the result with an absolute URL.
/api/video/trim + MCP trim_video)Cut a segment out of a video by specifying a start time and either an end time or a duration. Maximum output length is 600 seconds (10 minutes).
Two modes:
reencode (default) — frame-accurate cut. Re-encodes at CRF 23, which is a good quality/size tradeoff. Best for precise clips.copy — fast keyframe-aligned cut. Nearly instant but may be slightly off at the start. Best for rough cuts where speed matters.curl -X POST https://agentmediatools.com/api/video/trim \ -F "video=@long-presentation.mp4" \ -F "start=300" \ -F "duration=30"
Or using end time instead of duration:
curl -X POST https://agentmediatools.com/api/video/trim \ -F "video=@long-presentation.mp4" \ -F "start=00:05:00" \ -F "end=00:05:30" \ -F "mode=reencode"
Response:
{
"success": true,
"url": "/downloads/trim-1719524567890.mp4",
"size": 3421056,
"start_s": 300,
"duration_s": 30,
"end_s": 330,
"mode": "reencode",
"format": "mp4"
}
import requests
resp = requests.post(
"https://agentmediatools.com/api/video/trim",
files={"video": open("podcast.mp4", "rb")},
data={"start": "600", "duration": "60", "mode": "copy"}
)
print(resp.json()["url"])
{
"name": "trim_video",
"arguments": {
"video_url": "https://example.com/long-video.mp4",
"start": "120",
"duration": "15",
"mode": "reencode"
}
}
/api/video/gif + MCP video_to_gif)Convert any video clip into an animated GIF. This is useful for previews, memes, reaction GIFs, or embedding in documentation. You control the frame rate (1–30 FPS) and output width (160–1920 pixels).
curl -X POST "https://agentmediatools.com/api/video/gif?fps=15&scale=640" \ -F "video=@funny-moment.mp4" \
Response:
{
"success": true,
"url": "/downloads/g-1719524567890.gif",
"size": 2345678
}
Default values: 10 FPS, 480px width. Scale only sets the width — height is automatically calculated to maintain aspect ratio.
{
"name": "video_to_gif",
"arguments": {
"video_url": "https://example.com/viral-clip.mp4",
"fps": 12,
"scale": 320
}
}
/api/video/audio)Strip the audio track from a video file and get it back as MP3 (default), M4A, or WAV. This is especially useful for feeding speech into a transcription pipeline or extracting a podcast track.
curl -X POST "https://agentmediatools.com/api/video/audio?format=mp3" \ -F "video=@lecture.mp4"
Supported formats: mp3, m4a, wav.
import requests
resp = requests.post(
"https://agentmediatools.com/api/video/audio?format=wav",
files={"video": open("interview.mp4", "rb")},
)
result = resp.json()
download_url = "https://agentmediatools.com" + result["url"]
# Now feed download_url into a transcription API
These endpoints are designed to chain together. Here are a few real-world patterns:
An agent extracts a thumbnail from a security camera clip, then passes the image URL to a vision model to describe what's happening:
video_thumbnail with time=15describe_image or any multimodal LLMExtract the first 60 seconds of a recorded meeting and transcribe it:
/api/video/trim with start=0&duration=60/api/video/audio?format=mp3An AI agent generating docs or changelogs can create an animated GIF from a screen recording automatically:
video_to_gif with fps=8&scale=480| Constraint | Limit |
|---|---|
| Trim output duration | 10 minutes (600 seconds) |
| MCP public-URL download ceiling | 250 MB |
| GIF FPS range | 1–30 |
| GIF scale width | 160–1920 px |
| Trim processing timeout | 120 seconds |
The upload-based REST endpoints shown here do not require an API key. Upload, processing, abuse-prevention, and temporary-storage safeguards still apply and may evolve. For repeatable agent use, create a free API key in the Toolbox and follow the supported setup paths.
Agent Media Tools supports several MCP installation paths instead of relying on an unpublished npm package. Claude Desktop users can install the signed MCP bundle. Hermes and other compatible hosts can run the checked-in mcp-server.js with Node 18+, or use the hosted MCP transport documented in the setup guide.
Free tools can run without a key. Set MEDIA_TOOL_AGENT_KEY when your chosen pack or hosted connection calls authenticated, higher-limit, or agent-only routes. After the MCP host reloads, video_thumbnail, trim_video, and video_to_gif appear in its tool list.
It's worth being clear about boundaries so you're not surprised:
ffmpeg locally.You do not need an account to test the upload endpoints—use a small video you are authorized to process and try the curl commands above. When you are ready to integrate an AI agent, create a free API key in the Toolbox and follow the current setup guide.
The full OpenAPI spec and interactive documentation are available at the docs page.
Run the video tools in the browser, or call them from your agent with an API key. No signup required for the upload endpoints.
Open toolbox