API Documentation

Quickstart

1Create an account and an API key in your dashboard (it starts with vda_). Confirming your email adds 10 free minutes.
2Send a link to POST /downloads. You get a download_id right away (HTTP 202).
3Poll GET /downloads/{id} every few seconds until status is ready, then fetch download_url.

1. Start a download

curl -X POST "https://videodownloadapi.com/api/v1/downloads" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=jNQXAC9IVRw","format":"mp4"}'

202 Accepted

{
  "download_id": "162b76ab-833e-4720-b687-dac284d479aa",
  "title": "Me at the zoo",
  "channel": "jawed",
  "platform": "Youtube",
  "thumbnail": "https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg?sqp=…",
  "duration_seconds": 19,
  "format": "mp4",
  "quality": "best",
  "status": "processing",
  "progress": 0,
  "minutes": 1,
  "size_bytes": null,
  "created_at": "2026-11-02T10:30:31.120Z",
  "expires_at": null
}

2. Check it until it's ready

curl "https://videodownloadapi.com/api/v1/downloads/162b76ab-833e-4720-b687-dac284d479aa" \
  -H "Authorization: Bearer YOUR_API_KEY"

200 OK

{
  "download_id": "162b76ab-833e-4720-b687-dac284d479aa",
  "title": "Me at the zoo",
  "channel": "jawed",
  "platform": "Youtube",
  "thumbnail": "https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg?sqp=…",
  "duration_seconds": 19,
  "format": "mp4",
  "quality": "best",
  "status": "ready",
  "progress": 100,
  "minutes": 1,
  "size_bytes": 475989,
  "created_at": "2026-11-02T10:30:31.120Z",
  "expires_at": "2026-11-04T10:30:46.678Z",
  "download_url": "https://videodownloadapi.com/api/downloads/162b76ab-833e-4720-b687-dac284d479aa?token=…"
}

Authentication

Every request carries your personal API key as a Bearer token. Create one key per tool or script in your dashboard: the key is shown once, and revoking it stops it right away. Keep keys on your server, never in browser code.

Header

Authorization: Bearer YOUR_API_KEY

Base URL: https://videodownloadapi.com/api/v1. Requests and responses are JSON. A missing or invalid key returns 401 with the code unauthorized.

Endpoints

get/accountPlan and remaining minutes get/mediaLook up a link post/downloadsStart a download get/downloads/{id}Get a download get/downloadsList downloads

get`/account`

Your plan and the minutes left, monthly allowance and packs included.

Response 200
Field	Description
`planstring` · required	Plan id One of: free, basic, pro, mega.
`plan_namestring` · required	Display name of the plan
`minutesinteger` · required	Minutes left, packs included
`renews_atdate-time \| null` · required	Next renewal of a paid plan
`manage_urluri` · required	Where to change plan or buy a pack

Example

curl "https://videodownloadapi.com/api/v1/account" \
  -H "Authorization: Bearer YOUR_API_KEY"

200 OK

{
  "plan": "basic",
  "plan_name": "Premium",
  "minutes": 487,
  "renews_at": "2026-12-01T09:12:44.000Z",
  "manage_url": "https://videodownloadapi.com/app"
}

Errors: 401, 429, 500. See Errors.

get`/media`

Title, duration and the minutes a download would cost. Nothing is downloaded or charged.

Parameters
Field	Description
`urluri` · query · required	Public link to the video or audio

Response 200
Field	Description
`titlestring` · required
`channelstring \| null` · optional	Author or channel
`platformstring \| null` · optional	Site the media comes from
`thumbnailuri \| null` · optional
`duration_secondsinteger` · required
`minutes_requiredinteger` · required	What a download costs: 1 per started minute

Example

curl -G "https://videodownloadapi.com/api/v1/media" \
  --data-urlencode "url=https://www.youtube.com/watch?v=jNQXAC9IVRw" \
  -H "Authorization: Bearer YOUR_API_KEY"

200 OK

{
  "title": "Me at the zoo",
  "channel": "jawed",
  "platform": "Youtube",
  "thumbnail": "https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg?sqp=…",
  "duration_seconds": 19,
  "minutes_required": 1
}

Errors: 400, 401, 422, 429, 500, 502. See Errors.

post`/downloads`

Looks up the link and starts the download. Downloads are billed per started minute of media: a 61-second video uses 2 minutes. Nothing is charged when the balance doesn't cover the media (402), and a failed download is refunded. Then poll GET /downloads/{id} until status is ready.

Body
Field	Description
`urluri` · required	Public link to the video or audio
`formatstring` · optional	mp4 for video, mp3, m4a or wav for audio only. Anything other than mp4 at best quality needs a paid plan or minutes from a pack. Default: mp4.
`qualitystring` · optional	Depends on the format: mp4: best, 1080p, 720p, 480p, 360p; mp3: best, 320kbps, 128kbps; m4a: best, 320kbps, 128kbps; wav: best. Default: best.

Response 202
Field	Description
`download_iduuid` · required
`titlestring` · optional
`channelstring \| null` · optional
`platformstring \| null` · optional
`thumbnailuri \| null` · optional
`duration_secondsinteger` · optional
`formatstring` · required	One of: mp4, mp3, m4a, wav.
`qualitystring` · required	One of: best, 1080p, 720p, 480p, 360p, 320kbps, 128kbps.
`statusstring` · required	See the statuses below One of: analyzed, processing, storing, ready, failed, expired.
`progressinteger` · required
`minutesinteger` · required	Minutes this download costs
`size_bytesinteger \| null` · optional	File size, once ready
`created_atdate-time` · optional
`expires_atdate-time \| null` · optional	When the file is deleted, 48 hours after it's ready
`download_urluri` · optional	Only when status is ready: signed link valid for 1 hour

Example

curl -X POST "https://videodownloadapi.com/api/v1/downloads" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=jNQXAC9IVRw","format":"mp4"}'

202 Accepted

{
  "download_id": "162b76ab-833e-4720-b687-dac284d479aa",
  "title": "Me at the zoo",
  "channel": "jawed",
  "platform": "Youtube",
  "thumbnail": "https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg?sqp=…",
  "duration_seconds": 19,
  "format": "mp4",
  "quality": "best",
  "status": "processing",
  "progress": 0,
  "minutes": 1,
  "size_bytes": null,
  "created_at": "2026-11-02T10:30:31.120Z",
  "expires_at": null
}

Errors: 400, 401, 402, 403, 422, 429, 500, 502. See Errors.

get`/downloads/{id}`

Status and progress. Once status is ready, download_url is a signed link valid for 1 hour: call again for a fresh one while the file is kept (48 hours). Progress is refreshed about every 15 seconds, so polling every 5 to 10 seconds is plenty.

Parameters
Field	Description
`iduuid` · path · required	download_id returned when the download started

Response 200
Field	Description
`download_iduuid` · required
`titlestring` · optional
`channelstring \| null` · optional
`platformstring \| null` · optional
`thumbnailuri \| null` · optional
`duration_secondsinteger` · optional
`formatstring` · required	One of: mp4, mp3, m4a, wav.
`qualitystring` · required	One of: best, 1080p, 720p, 480p, 360p, 320kbps, 128kbps.
`statusstring` · required	See the statuses below One of: analyzed, processing, storing, ready, failed, expired.
`progressinteger` · required
`minutesinteger` · required	Minutes this download costs
`size_bytesinteger \| null` · optional	File size, once ready
`created_atdate-time` · optional
`expires_atdate-time \| null` · optional	When the file is deleted, 48 hours after it's ready
`download_urluri` · optional	Only when status is ready: signed link valid for 1 hour

Example

curl "https://videodownloadapi.com/api/v1/downloads/162b76ab-833e-4720-b687-dac284d479aa" \
  -H "Authorization: Bearer YOUR_API_KEY"

200 OK

{
  "download_id": "162b76ab-833e-4720-b687-dac284d479aa",
  "title": "Me at the zoo",
  "channel": "jawed",
  "platform": "Youtube",
  "thumbnail": "https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg?sqp=…",
  "duration_seconds": 19,
  "format": "mp4",
  "quality": "best",
  "status": "ready",
  "progress": 100,
  "minutes": 1,
  "size_bytes": 475989,
  "created_at": "2026-11-02T10:30:31.120Z",
  "expires_at": "2026-11-04T10:30:46.678Z",
  "download_url": "https://videodownloadapi.com/api/downloads/162b76ab-833e-4720-b687-dac284d479aa?token=…"
}

Errors: 401, 404, 429, 500. See Errors.

get`/downloads`

Your most recent downloads, newest first.

Parameters
Field	Description
`limitinteger` · query · optional	How many downloads to return Default: 20.

Response 200
Field	Description
`downloadsDownload[]` · required

Example

curl -G "https://videodownloadapi.com/api/v1/downloads" \
  --data-urlencode "limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

200 OK

{
  "downloads": [
    {
      "download_id": "162b76ab-833e-4720-b687-dac284d479aa",
      "title": "Me at the zoo",
      "channel": "jawed",
      "platform": "Youtube",
      "thumbnail": "https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg?sqp=…",
      "duration_seconds": 19,
      "format": "mp4",
      "quality": "best",
      "status": "ready",
      "progress": 100,
      "minutes": 1,
      "size_bytes": 475989,
      "created_at": "2026-11-02T10:30:31.120Z",
      "expires_at": "2026-11-04T10:30:46.678Z",
      "download_url": "https://videodownloadapi.com/api/downloads/162b76ab-833e-4720-b687-dac284d479aa?token=…"
    }
  ]
}

Errors: 401, 429, 500. See Errors.

Download object

Download
Field	Description
`download_iduuid` · required
`titlestring` · optional
`channelstring \| null` · optional
`platformstring \| null` · optional
`thumbnailuri \| null` · optional
`duration_secondsinteger` · optional
`formatstring` · required	One of: mp4, mp3, m4a, wav.
`qualitystring` · required	One of: best, 1080p, 720p, 480p, 360p, 320kbps, 128kbps.
`statusstring` · required	See the statuses below One of: analyzed, processing, storing, ready, failed, expired.
`progressinteger` · required
`minutesinteger` · required	Minutes this download costs
`size_bytesinteger \| null` · optional	File size, once ready
`created_atdate-time` · optional
`expires_atdate-time \| null` · optional	When the file is deleted, 48 hours after it's ready
`download_urluri` · optional	Only when status is ready: signed link valid for 1 hour

Statuses
Status	Meaning
`analyzed`	Looked up but not started (e.g. after a 402). Not charged.
`processing`	Charged and downloading; progress goes from 0 to 98.
`storing`	Downloaded, being saved to private storage.
`ready`	download_url is set: a signed link valid for 1 hour.
`failed`	Couldn't be downloaded; the minutes were refunded.
`expired`	The file was deleted after 48 hours.

Errors

Errors use the HTTP status and a JSON body with a stable code to branch on, and a message to show or log.

402 Payment Required

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough minutes. Add minutes from your account. 1 more minute needed."
  }
}

Error codes
HTTP	Code	When
400	`invalid_url`	The url is missing or isn't an http(s) link.
400	`invalid_option`	The format or quality isn't supported. Qualities depend on the format (mp4: best, 1080p, 720p, 480p, 360p; mp3: best, 320kbps, 128kbps; m4a: best, 320kbps, 128kbps; wav: best).
401	`unauthorized`	The API key is missing, revoked or invalid.
402	`insufficient_credits`	The balance doesn't cover the media. The message says how many minutes are missing; nothing is charged.
403	`paid_option`	Anything other than mp4 at best quality needs a paid plan or minutes from a pack.
404	`not_found`	No download with this id on your account.
422	`unreadable_video`	The media is private, deleted, age-restricted or from an unsupported site.
422	`private_link`	The url is a Claude artifact link, which is private and not supported yet.
422	`unsupported_live`	Live streams and media without a duration can't be downloaded.
429	`rate_limited`	More than 60 lookups in an hour, or too many at once. Retry later.
502	`unreadable_video`	The media couldn't be read right now. Retry in a moment.
500	`generic`	Unexpected error on our side. Retry in a moment.

Billing & limits

Downloads are billed per started minute of media: a 61-second video uses 2 minutes. Minutes are charged only if your balance covers the media (otherwise 402, nothing charged) and refunded automatically when a download fails.
Looking a link up with GET /media is free. Lookups (GET /media and POST /downloads) are limited to 60 per hour per account (429 beyond).
Files are kept 48 hours. download_url is valid 1 hour: get the download again for a fresh link.
Choosing the format and quality needs a paid plan or minutes from a pack; otherwise ask for mp4 at best quality (or leave both out).

Formats and qualities
Format	Kind	Qualities
`mp4`	video	best, 1080p, 720p, 480p, 360p
`mp3`	audio	best, 320kbps, 128kbps
`m4a`	audio	best, 320kbps, 128kbps
`wav`	audio	best

MCP server

The MCP server lets Claude, ChatGPT, Cursor or any MCP client download media for you, with the same API key. It uses Streamable HTTP with stateless JSON responses at https://videodownloadapi.com/api/mcp. Authenticate with the Authorization header, or ?key= for clients that only accept a URL. Your dashboard has one-click setups for each client.

Claude Code

claude mcp add --transport http videodownloadapi https://videodownloadapi.com/api/mcp --header "Authorization: Bearer YOUR_API_KEY"

mcpServers config

{
  "mcpServers": {
    "videodownloadapi": {
      "url": "https://videodownloadapi.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Tools
Tool	Arguments	What it does
`get_account`	none	Current plan and remaining minutes. Downloads are billed per started minute of media: a 61-second video uses 2 minutes.
`get_media_info`	url	Look up a media link (YouTube, X, LinkedIn, Instagram, TikTok, Facebook…) without downloading: title, channel, duration and the minutes a download would cost. Free.
`download_media`	url, format?, quality?	Start downloading a media link. Downloads are billed per started minute of media: a 61-second video uses 2 minutes. Charged only if the balance covers it, refunded if it fails. Then poll get_download with the returned download_id until status is ready.
`get_download`	download_id	Status and progress of a download. When status is ready, download_url is a link valid for 1 hour: give it to the user, or call again for a fresh one. Wait about 10 seconds between calls.
`list_downloads`	limit?	Most recent downloads of the account, newest first.

Start downloading

Create an account, confirm your email and get 10 free minutes to try the API.

Get an API key

Quickstart

Authentication

Endpoints

get/account

get/media

post/downloads

get/downloads/{id}

get/downloads

Download object

Errors

Billing & limits

MCP server

Start downloading

get`/account`

get`/media`

post`/downloads`

get`/downloads/{id}`

get`/downloads`