Quickstart
From link to file in four requests.
The API is asynchronous by default. Resolve the public page, create a job, poll for progress, then download the signed file. This page uses curl so every step is copyable.
Before you start
Create an account, open Settings, then API keys, and create a vd_ key. New accounts receive 20 credits. Resolve calls are free, so you can test the response shape before spending a credit.
Export the key as VD_KEY. Do not put it in a browser bundle or a public repository.
export VD_KEY=vd_your_key
export VD_BASE=https://videodownloadmcp.comResolve a link
Resolve returns metadata and the formats the public page actually exposes. It does not download the media. Use it to show the title, duration, and options before the user spends a credit.
curl -s https://videodownloadmcp.com/v1/resolve \
-H "Authorization: Bearer $VD_KEY" \
-H "content-type: application/json" \
-d '{"url":"https://www.youtube.com/watch?v=aqz-KE-bpKQ"}'{
"code": 0,
"data": {
"platform": "youtube",
"title": "Big Buck Bunny 60fps 4K",
"duration_sec": 635,
"thumbnail": "https://i.ytimg.com/...",
"formats": [
{ "quality": "1080p", "label": "1080p MP4", "ext": "mp4" },
{ "quality": "720p", "label": "720p MP4", "ext": "mp4" }
],
"audio_formats": [
{ "quality": "audio", "label": "MP3 192 kbps", "ext": "mp3" }
]
}
}Create a job
Pass the same URL with a format and a maximum quality. The worker selects the best format at or below the requested height. The response contains a job id; the job is queued, not finished.
curl -s https://videodownloadmcp.com/v1/downloads \
-H "Authorization: Bearer $VD_KEY" \
-H "content-type: application/json" \
-d '{
"url": "https://www.tiktok.com/@user/video/123",
"format": "mp4",
"quality": "1080p"
}'{
"code": 0,
"data": {
"job_id": "job_810d06575caa26661070579d",
"status": "queued",
"progress": 0,
"credits_charged": 1,
"created_at": "2026-11-03T16:50:02.440Z"
}
}Optional fields: format_id to prefer a specific format returned by resolve, and audio_only: true as an alias for the audio format.
Poll and download
Poll every two seconds. Stop on ready, failed, canceled, or expired. The file URL is signed and expires 15 minutes after the job becomes ready. Download it immediately; the API cannot mint a second URL after expiry.
curl -s https://videodownloadmcp.com/v1/downloads/job_810d \
-H "Authorization: Bearer $VD_KEY"{
"code": 0,
"data": {
"status": "ready",
"progress": 100,
"file": {
"url": "https://videodownloadmcp.com/v1/files/job_810d?token=...",
"mime": "video/mp4",
"size": 8412733,
"expires_at": "2026-11-04T02:15:00.000Z"
}
}
}const res = await fetch('https://videodownloadmcp.com/v1/downloads', {
method: 'POST',
headers: {
authorization: `Bearer ${process.env.VD_KEY}`,
'content-type': 'application/json',
},
body: JSON.stringify({ url, format: 'mp4', quality: '1080p' }),
});
const { data: job } = await res.json();
while (!['ready', 'failed', 'canceled', 'expired'].includes(job.status)) {
await new Promise((r) => setTimeout(r, 2000));
const poll = await fetch(
`https://videodownloadmcp.com/v1/downloads/${job.job_id}`,
{ headers: { authorization: `Bearer ${process.env.VD_KEY}` } },
);
job = (await poll.json()).data;
}Extract audio
The audio endpoint is the download endpoint with an MP3 postprocessor. It costs one credit and follows the same job lifecycle.
curl -s https://videodownloadmcp.com/v1/audio \
-H "Authorization: Bearer $VD_KEY" \
-H "content-type: application/json" \
-d '{"url":"https://www.youtube.com/watch?v=aqz-KE-bpKQ"}'Errors and limits
Errors use a stable string code and an HTTP status. Retry only TIMEOUT and 5xx responses; retrying PRIVATE_CONTENT or DRM_PROTECTED will never succeed.
| limit | value |
|---|---|
| max video duration | 30 minutes |
| max file size | 500 MB |
| file lifetime | 15 minutes |
| resolve rate limit | 20 per minute per key |
| download rate limit | 8 per minute per key |
| anonymous web quota | 3 per network per day |
Full error descriptions are on the API reference.
MCP instead of REST
The MCP server exposes the same six operations at /mcp. If your client supports streamable HTTP, there is nothing to install.
claude mcp add --transport http videodownload \
https://videodownloadmcp.com/mcp \
--header "Authorization: Bearer $VD_KEY"See the MCP setup page for Cursor and Codex configs.
Rate limits and credits
Each API key has its own minute buckets and charges the owning account. A failed job refunds its credit automatically. The free web downloader does not use credits; it has a daily per-network quota instead.
Check the balance and current month usage with GET /v1/me. Plans and credit packs are on the pricing page.
Need the full schema?
Every endpoint, request field, and error code.