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.

POST/v1/resolveauth: Bearer

Resolve a public URL into metadata and available formats. Free inside the rate limit.

request body
{
  "url": "https://www.tiktok.com/@user/video/123"
}
response
{
  "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.
GET/v1/formats?url=auth: Bearer

Return the format list for a URL without the rest of the metadata.

response
{
  "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.
POST/v1/downloadsauth: Bearer

Create an asynchronous MP4, audio, or GIF job. Charges one credit.

request body
{
  "url": "https://www.tiktok.com/@user/video/123",
  "format": "mp4",
  "quality": "1080p",
  "format_id": "optional-from-resolve",
  "audio_only": false
}
response
{
  "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.
GET/v1/downloads/:idauth: Bearer

Read a job, its progress, metadata, and the signed file URL when ready.

response
{
  "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.
DELETE/v1/downloads/:idauth: Bearer

Cancel a queued or running job, or delete a ready job and its file. Refunds the credit.

response
{
  "code": 0,
  "data": {
    "job_id": "job_810d06575caa26661070579d",
    "status": "canceled",
    "progress": 0
  }
}
  • Canceling an already terminal job returns the stored state.
POST/v1/audioauth: Bearer

Create an MP3 extraction job. Charges one credit.

request body
{
  "url": "https://www.youtube.com/watch?v=aqz-KE-bpKQ"
}
response
{
  "code": 0,
  "data": {
    "job_id": "job_...",
    "status": "queued",
    "format": "audio",
    "quality": "audio",
    "credits_charged": 1
  }
}
GET/v1/meauth: Bearer

Return the account balance and current month usage.

response
{
  "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
  }
}
GET/v1/healthauth: None

Public health check for the API and the download worker.

response
{
  "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_URL

The URL is not a valid public http(s) link.

INVALID_ARGUMENT

A required argument is missing or malformed.

UNSUPPORTED_PLATFORM

That host is not on the supported platform list.

PRIVATE_CONTENT

The post is private or followers-only.

DRM_PROTECTED

The media is DRM protected and will not be decrypted.

LOGIN_REQUIRED

The platform requires a logged-in session for this post.

RATE_LIMITED

Too many requests. Retry after the window resets.

QUOTA_EXCEEDED

The free daily quota for this network is used up.

INSUFFICIENT_CREDITS

The API key owner has no credits left.

EXTRACTOR_FAILED

The extractor could not read this page.

FILE_TOO_LARGE

The file is larger than 500 MB.

DURATION_LIMIT_EXCEEDED

The video is longer than 30 minutes.

LIVE_NOT_SUPPORTED

Live streams are not supported.

TIMEOUT

The request timed out. Retry once.

NOT_FOUND

The job or media no longer exists.

JOB_NOT_READY

The job has no downloadable file yet.

UNAUTHORIZED

A valid Bearer API key is required.

INTERNAL

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