API reference
Eight endpoints. One job model.
Base URL https://videodownloadmcp.com. JSON in, JSON out. API keys use the vd_ prefix and a Bearer header.
/v1/resolveauth: BearerResolve a public URL into metadata and available formats. Free inside the rate limit.
{
"url": "https://www.tiktok.com/@user/video/123"
}{
"code": 0,
"data": {
"platform": "tiktok",
"id": "123",
"url": "https://www.tiktok.com/@user/video/123",
"title": "Post title",
"duration_sec": 18,
"thumbnail": "https://...",
"uploader": "user",
"is_live": false,
"formats": [
{ "id": "play_addr_h264", "kind": "video", "quality": "1080p",
"label": "1080p MP4", "ext": "mp4", "has_audio": true }
],
"audio_formats": [
{ "id": "audio-mp3", "kind": "audio", "quality": "audio",
"label": "MP3 192 kbps", "ext": "mp3" }
],
"gif_formats": [],
"best": { "quality": "1080p", "label": "1080p MP4" }
}
}- Format URLs are never returned. The only downloadable URL comes from a job.
- A playlist URL returns UNSUPPORTED_PLATFORM. Pass one video at a time.
/v1/formats?url=auth: BearerReturn the format list for a URL without the rest of the metadata.
{
"code": 0,
"data": {
"url": "https://...",
"platform": "youtube",
"title": "Video title",
"duration_sec": 635,
"formats": [ ... ],
"best": { "quality": "1080p", "label": "1080p MP4" }
}
}- The url query parameter must be percent-encoded.
/v1/downloadsauth: BearerCreate an asynchronous MP4, audio, or GIF job. Charges one credit.
{
"url": "https://www.tiktok.com/@user/video/123",
"format": "mp4",
"quality": "1080p",
"format_id": "optional-from-resolve",
"audio_only": false
}{
"code": 0,
"data": {
"job_id": "job_810d06575caa26661070579d",
"status": "queued",
"progress": 0,
"format": "mp4",
"quality": "1080p",
"credits_charged": 1,
"created_at": "2026-11-03T16:50:02.440Z"
}
}- format accepts mp4, audio, or gif. quality accepts 360p, 480p, 720p, 1080p, 2160p, or audio.
- The response is HTTP 202 with a queued job, not a finished file.
/v1/downloads/:idauth: BearerRead a job, its progress, metadata, and the signed file URL when ready.
{
"code": 0,
"data": {
"job_id": "job_810d06575caa26661070579d",
"status": "ready",
"progress": 100,
"format": "mp4",
"quality": "1080p",
"engine": "yt-dlp",
"credits_charged": 1,
"metadata": {
"title": "Video title",
"platform": "tiktok",
"duration_sec": 18,
"thumbnail": "https://..."
},
"error": null,
"file": {
"url": "https://videodownloadmcp.com/v1/files/job_810d?token=...",
"mime": "video/mp4",
"size": 8412733,
"expires_at": "2026-11-04T02:15:00.000Z"
}
}
}- Poll no faster than every 2 seconds. Terminal statuses: ready, failed, canceled, expired.
- The file URL is valid for 15 minutes and works without the API key.
/v1/downloads/:idauth: BearerCancel a queued or running job, or delete a ready job and its file. Refunds the credit.
{
"code": 0,
"data": {
"job_id": "job_810d06575caa26661070579d",
"status": "canceled",
"progress": 0
}
}- Canceling an already terminal job returns the stored state.
/v1/audioauth: BearerCreate an MP3 extraction job. Charges one credit.
{
"url": "https://www.youtube.com/watch?v=aqz-KE-bpKQ"
}{
"code": 0,
"data": {
"job_id": "job_...",
"status": "queued",
"format": "audio",
"quality": "audio",
"credits_charged": 1
}
}/v1/meauth: BearerReturn the account balance and current month usage.
{
"code": 0,
"data": {
"user_id": "user_...",
"api_key_id": "key_...",
"credits": 100,
"downloads_this_month": 14,
"credits_spent_this_month": 14,
"free_downloads_today": 0,
"free_downloads_per_day": 3
}
}/v1/healthauth: NonePublic health check for the API and the download worker.
{
"code": 0,
"data": {
"status": "ok",
"api": "ok",
"engine": "yt-dlp",
"version": "0.1.0",
"worker": { "status": "ok", "ttl_sec": 900 }
}
}- status is degraded when the worker is unreachable.
Error codes
Failures return { "code": "CODE", "message": "..." } with a matching HTTP status. MCP tool calls wrap the same code in an isError result.
INVALID_URLThe URL is not a valid public http(s) link.
INVALID_ARGUMENTA required argument is missing or malformed.
UNSUPPORTED_PLATFORMThat host is not on the supported platform list.
PRIVATE_CONTENTThe post is private or followers-only.
DRM_PROTECTEDThe media is DRM protected and will not be decrypted.
LOGIN_REQUIREDThe platform requires a logged-in session for this post.
RATE_LIMITEDToo many requests. Retry after the window resets.
QUOTA_EXCEEDEDThe free daily quota for this network is used up.
INSUFFICIENT_CREDITSThe API key owner has no credits left.
EXTRACTOR_FAILEDThe extractor could not read this page.
FILE_TOO_LARGEThe file is larger than 500 MB.
DURATION_LIMIT_EXCEEDEDThe video is longer than 30 minutes.
LIVE_NOT_SUPPORTEDLive streams are not supported.
TIMEOUTThe request timed out. Retry once.
NOT_FOUNDThe job or media no longer exists.
JOB_NOT_READYThe job has no downloadable file yet.
UNAUTHORIZEDA valid Bearer API key is required.
INTERNALUnexpected server error. The request id is in the logs.
Limits
- 20 resolves per minute per API key.
- 8 new jobs per minute per API key.
- 30 minute maximum duration and 500 MB maximum file size.
- Files expire 15 minutes after a job becomes ready.
- Anonymous web requests: 3 downloads per network per day.