Home
Documentation
API reference

API reference

MCPTube REST API reference generated from OpenAPI 3.1: routes, parameters, responses and error codes to download audio and video and transcribe YouTube videos.

Generated from the OpenAPI 3.1 specification, also available at https://mcp.mcptube.com/v1/openapi.json. Every route uses the Authorization: Bearer mct_YOUR_KEY header.

POST`/v1/audio`

Download audio

Downloads the audio of a YouTube video as MP3 (default, with cover art and tags) or M4A (original AAC). Returns a download link valid for 60 min. When processing takes longer than ~90 s, the response is 202 with `statusUrl`: poll `GET /jobs/{id}` until `status` = `done`.

Body (JSON)

Field	Type	Description
`url`required	string	URL or ID of a YouTube video (watch, youtu.be, shorts, live, embed or clip).
`format`	"mp3" \| "m4a"	Output format. Default: mp3.
`audioLanguage`	string	Preferred audio track when the video has dubs (e.g. "pt", "en", "original").

Example

curl

curl https://mcp.mcptube.com/v1/audio \
  -H "Authorization: Bearer mct_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","format":"mp3"}'

200 response

Field	Type	Description
`videoId`required	string	Video ID.
`title`required	string
`author`required	string
`durationSeconds`required	integer, -9007199254740991 to 9007199254740991 \| null
`fileName`required	string
`fileSizeBytes`required	integer, -9007199254740991 to 9007199254740991
`downloadUrl`required	string	Download link, no authentication (the random identifier is the secret).
`expiresAt`required	string	The file is deleted from the server at this time (60 min after creation).
`planNote`	string	Present when the plan lowered the request (e.g. resolution), in the caller locale.
`audioFormat`required	object \| null

200 OK

{
  "videoId": "dQw4w9WgXcQ",
  "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)",
  "author": "Rick Astley",
  "durationSeconds": 213,
  "fileName": "dQw4w9WgXcQ-Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster).mp3",
  "fileSizeBytes": 6441731,
  "downloadUrl": "https://mcp.mcptube.com/files/-U4ALuInCNI-3Rk8DxAtEOpUHuRy5NQ5/dQw4w9WgXcQ-Rick%20Astley%20-%20Never%20Gonna%20Give%20You%20Up.mp3",
  "expiresAt": "2026-10-21T22:12:24.000Z",
  "audioFormat": {
    "container": "mp4",
    "videoCodec": null,
    "audioCodec": "mp4a.40.2",
    "height": null,
    "fps": null,
    "audioTrack": null
  }
}

Other responses

Status	When
202	Still processing: the job keeps running in the background.
400	Invalid request: invalid_request (body or field) or invalid_url (invalid URL or playlist).
401	unauthorized: no credential, or an invalid, revoked or expired key or token.
403	plan_limit (video length, AI transcription outside Pro, monthly AI transcription cap) or banned (blocked IP).
404	video_unavailable (missing, private or removed video; does not use quota).
429	quota_exceeded (daily quota) or failures_exceeded (too many failed attempts in a short time; try again later).
500	internal: server failure; try again.
503	youtube_blocked (YouTube refused the server; does not use quota) or service_unavailable.

POST`/v1/video`

Download video

Downloads the video as MP4: H.264 up to 1080p; above that VP9 or AV1, with no re-encoding. AAC audio, cover art and chapters. The plan may lower the resolution (planNote). When processing takes longer than ~90 s, the response is 202 with `statusUrl`: poll `GET /jobs/{id}` until `status` = `done`.

Body (JSON)

Field	Type	Description
`url`required	string	URL or ID of a YouTube video (watch, youtu.be, shorts, live, embed or clip).
`maxHeight`	integer, 144 to 4320	Maximum height in pixels (144, 360, 480, 720, 1080, 1440, 2160). Default: 1080. The plan may lower it (planNote).
`audioLanguage`	string	Preferred audio track (e.g. "pt", "en", "original").

Example

curl

curl https://mcp.mcptube.com/v1/video \
  -H "Authorization: Bearer mct_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://youtu.be/dQw4w9WgXcQ","maxHeight":1080}'

200 response

Field	Type	Description
`videoId`required	string	Video ID.
`title`required	string
`author`required	string
`durationSeconds`required	integer, -9007199254740991 to 9007199254740991 \| null
`fileName`required	string
`fileSizeBytes`required	integer, -9007199254740991 to 9007199254740991
`downloadUrl`required	string	Download link, no authentication (the random identifier is the secret).
`expiresAt`required	string	The file is deleted from the server at this time (60 min after creation).
`planNote`	string	Present when the plan lowered the request (e.g. resolution), in the caller locale.
`videoCodec`required	"h264" \| "vp9" \| "av1" \| null
`compatibilityNote`	string	Present when the video is not H.264.
`videoFormat`required	object \| null
`audioFormat`required	object \| null

200 OK

{
  "videoId": "dQw4w9WgXcQ",
  "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)",
  "author": "Rick Astley",
  "durationSeconds": 213,
  "fileName": "dQw4w9WgXcQ-Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster).mp4",
  "fileSizeBytes": 30007919,
  "downloadUrl": "https://mcp.mcptube.com/files/q2w8XyZ0fJ4mN1aB7cD9eF3gH5iK6lM8/dQw4w9WgXcQ-Rick%20Astley.mp4",
  "expiresAt": "2026-10-21T22:15:10.000Z",
  "videoCodec": "h264",
  "planNote": "Resolution capped at 720p (requested: 1080p). Your plan: Free. Upgrade to Pro for 500 calls a day, video with no quality or length limits and AI transcription: https://app.mcptube.com/dashboard/billing?checkout=pro_monthly",
  "videoFormat": {
    "container": "mp4",
    "videoCodec": "avc1.4d401f",
    "audioCodec": null,
    "height": 720,
    "fps": 25,
    "audioTrack": null
  },
  "audioFormat": {
    "container": "mp4",
    "videoCodec": null,
    "audioCodec": "mp4a.40.2",
    "height": null,
    "fps": null,
    "audioTrack": null
  }
}

Other responses

Status	When
202	Still processing: the job keeps running in the background.
400	Invalid request: invalid_request (body or field) or invalid_url (invalid URL or playlist).
401	unauthorized: no credential, or an invalid, revoked or expired key or token.
403	plan_limit (video length, AI transcription outside Pro, monthly AI transcription cap) or banned (blocked IP).
404	video_unavailable (missing, private or removed video; does not use quota).
429	quota_exceeded (daily quota) or failures_exceeded (too many failed attempts in a short time; try again later).
500	internal: server failure; try again.
503	youtube_blocked (YouTube refused the server; does not use quota) or service_unavailable.

POST`/v1/transcribe`

Transcribe video

Uses the YouTube captions (manual before automatic). Without captions, transcribes the audio with AI (Pro only, up to 30 hours a month). The response carries SRT and/or text according to `format`. When processing takes longer than ~90 s, the response is 202 with `statusUrl`: poll `GET /jobs/{id}` until `status` = `done`.

Body (JSON)

Field	Type	Description
`url`required	string	URL or ID of a YouTube video (watch, youtu.be, shorts, live, embed or clip).
`language`	string	Caption language (ISO code, e.g. "pt", "en"). Empty: the original captions of the video.
`forceAiTranscription`	boolean	Ignores YouTube captions and transcribes the audio with AI (Pro only). Default: false.
`format`	"srt" \| "text" \| "both"	What to return: SRT, plain text or both. Default: both.

Example

curl

curl https://mcp.mcptube.com/v1/transcribe \
  -H "Authorization: Bearer mct_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"dQw4w9WgXcQ","language":"en","format":"text"}'

200 response

Field	Type	Description
`videoId`required	string
`title`required	string
`author`required	string
`durationSeconds`required	integer, -9007199254740991 to 9007199254740991 \| null
`source`required	"youtube-captions" \| "youtube-auto-captions" \| "ai-transcription"	Where the transcript came from: youtube-captions (manual captions), youtube-auto-captions (automatic captions) or ai-transcription (audio transcribed by AI, Pro).
`language`required	string \| null
`languageName`required	string \| null
`cueCount`required	integer, -9007199254740991 to 9007199254740991
`aiTranscriptionSeconds`required	integer, -9007199254740991 to 9007199254740991 \| null	Seconds of audio transcribed by AI (null when it came from captions).
`aiTranscriptionUsedSeconds`	integer, -9007199254740991 to 9007199254740991	AI transcription used this month, in seconds (Pro).
`aiTranscriptionLimitSeconds`	integer, -9007199254740991 to 9007199254740991	Monthly AI transcription cap, in seconds (Pro: 108000 s = 30 h).
`srt`	string	Captions in SRT format (format srt or both).
`text`	string	Plain text (format text or both).

200 OK

{
  "videoId": "dQw4w9WgXcQ",
  "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)",
  "author": "Rick Astley",
  "durationSeconds": 213,
  "source": "youtube-captions",
  "language": "en",
  "languageName": "English",
  "cueCount": 61,
  "aiTranscriptionSeconds": null,
  "text": "We're no strangers to love You know the rules and so do I ..."
}

Other responses

Status	When
202	Still processing: the job keeps running in the background.
400	Invalid request: invalid_request (body or field) or invalid_url (invalid URL or playlist).
401	unauthorized: no credential, or an invalid, revoked or expired key or token.
403	plan_limit (video length, AI transcription outside Pro, monthly AI transcription cap) or banned (blocked IP).
404	video_unavailable (missing, private or removed video; does not use quota).
429	quota_exceeded (daily quota) or failures_exceeded (too many failed attempts in a short time; try again later).
500	internal: server failure; try again.
503	youtube_blocked (YouTube refused the server; does not use quota) or service_unavailable.

GET`/v1/me`

Plan and quotas

Caller's plan, daily quota (resets at 00:00 UTC) and AI transcription this month. Does not use quota.

Example

curl

curl https://mcp.mcptube.com/v1/me \
  -H "Authorization: Bearer mct_YOUR_KEY"

200 response

Field	Type	Description
`subject`required	string	Quota owner: user:<id> (account) or key:<id> (standalone key).
`via`required	"key" \| "oauth"
`plan`required	object
`quota`required	object
`aiTranscription`required	object	AI transcription this month, in seconds of audio.

200 OK

{
  "subject": "user:6ad93b198e40ee3ebe286315",
  "via": "key",
  "plan": {
    "id": "free",
    "label": "Free",
    "aiTranscription": false,
    "maxHeight": 720,
    "maxDurationSeconds": 3600,
    "requestsPerDay": 20,
    "aiTranscriptionSecondsPerMonth": 0,
    "maxKeys": 1
  },
  "quota": {
    "used": 3,
    "limit": 20,
    "remaining": 17,
    "resetsAt": "2026-10-22T00:00:00.000Z"
  },
  "aiTranscription": {
    "usedSeconds": 0,
    "limitSeconds": 0,
    "resetsAt": "2026-11-01T00:00:00.000Z"
  }
}

Other responses

Status	When
401	unauthorized: no credential, or an invalid, revoked or expired key or token.
503	youtube_blocked (YouTube refused the server; does not use quota) or service_unavailable.

GET`/v1/jobs/{id}`

Get a job

State of a job created by a 202 response. Kept for 1 hour; only its creator can read it.

Path parameters

Parameter	Type	Description
`id`required	string

Example

curl

curl https://mcp.mcptube.com/v1/jobs/job_7HqZ2mWv \
  -H "Authorization: Bearer mct_YOUR_KEY"

200 response

Field	Type	Description
`id`required	string
`tool`required	"download_audio" \| "download_video" \| "transcribe_video"
`status`required	"running" \| "done" \| "error"
`createdAt`required	string
`finishedAt`required	string \| null
`statusUrl`required	string
`result`	object	The same JSON as the 200 response of the tool (status done).
`error`	object	Present when status = error.

200 OK

{
  "id": "job_2Xf9kQ7mR1sT4vW8yZ0aB3cD",
  "tool": "download_video",
  "status": "done",
  "createdAt": "2026-10-21T22:00:00.000Z",
  "finishedAt": "2026-10-21T22:02:11.000Z",
  "statusUrl": "https://mcp.mcptube.com/v1/jobs/job_2Xf9kQ7mR1sT4vW8yZ0aB3cD",
  "result": {
    "videoId": "dQw4w9WgXcQ",
    "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)",
    "author": "Rick Astley",
    "durationSeconds": 213,
    "fileName": "dQw4w9WgXcQ-Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster).mp4",
    "fileSizeBytes": 30007919,
    "downloadUrl": "https://mcp.mcptube.com/files/q2w8XyZ0fJ4mN1aB7cD9eF3gH5iK6lM8/dQw4w9WgXcQ-Rick%20Astley.mp4",
    "expiresAt": "2026-10-21T22:15:10.000Z",
    "videoCodec": "h264",
    "planNote": "Resolution capped at 720p (requested: 1080p). Your plan: Free. Upgrade to Pro for 500 calls a day, video with no quality or length limits and AI transcription: https://app.mcptube.com/dashboard/billing?checkout=pro_monthly",
    "videoFormat": {
      "container": "mp4",
      "videoCodec": "avc1.4d401f",
      "audioCodec": null,
      "height": 720,
      "fps": 25,
      "audioTrack": null
    },
    "audioFormat": {
      "container": "mp4",
      "videoCodec": null,
      "audioCodec": "mp4a.40.2",
      "height": null,
      "fps": null,
      "audioTrack": null
    }
  }
}

Other responses

Status	When
401	unauthorized: no credential, or an invalid, revoked or expired key or token.
404	not_found: missing or expired job, or a job of another account.

Error format

Field	Type	Description
`code`required	"unauthorized" \| "invalid_request" \| "invalid_url" \| "plan_limit" \| "banned" \| "video_unavailable" \| "not_found" \| "quota_exceeded" \| "failures_exceeded" \| "youtube_blocked" \| "service_unavailable" \| "internal"	Stable code to handle in your code (never translated).
`message`required	string	Message to show to the user, in the account language (English or Brazilian Portuguese; otherwise the request's Accept-Language, else English).
`requestId`	string	Request identifier, for support.

API reference

POST/v1/audio

Body (JSON)

Example

200 response

Other responses

POST/v1/video

Body (JSON)

Example

200 response

Other responses

POST/v1/transcribe

Body (JSON)

Example

200 response

Other responses

GET/v1/me

Example

200 response

Other responses

GET/v1/jobs/{id}

Path parameters

Example

200 response

Other responses

Error format

POST`/v1/audio`

POST`/v1/video`

POST`/v1/transcribe`

GET`/v1/me`

GET`/v1/jobs/{id}`