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.

environment
export VD_KEY=vd_your_key
export VD_BASE=https://videodownloadmcp.com

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

request
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"}'
response
{
  "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.

request
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"
  }'
response
{
  "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.

request
curl -s https://videodownloadmcp.com/v1/downloads/job_810d \
  -H "Authorization: Bearer $VD_KEY"
response
{
  "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"
    }
  }
}
node example
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.

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

limitvalue
max video duration30 minutes
max file size500 MB
file lifetime15 minutes
resolve rate limit20 per minute per key
download rate limit8 per minute per key
anonymous web quota3 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 code
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.

API reference