Início
Documentação
Referência da API

Referência da API

Referência da API REST do MCPTube gerada do OpenAPI 3.1: rotas, parâmetros, respostas e códigos de erro para baixar áudio e vídeo e transcrever o YouTube.

Gerada da especificação OpenAPI 3.1, também disponível em https://mcp.mcptube.com/v1/openapi.json. Todas as rotas usam o header Authorization: Bearer mct_SUA_CHAVE.

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

Corpo (JSON)

Campo	Tipo	Descrição
`url`obrigatório	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").

Exemplo

curl

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

Resposta 200

Campo	Tipo	Descrição
`videoId`obrigatório	string	Video ID.
`title`obrigatório	string
`author`obrigatório	string
`durationSeconds`obrigatório	inteiro, -9007199254740991 a 9007199254740991 \| null
`fileName`obrigatório	string
`fileSizeBytes`obrigatório	inteiro, -9007199254740991 a 9007199254740991
`downloadUrl`obrigatório	string	Download link, no authentication (the random identifier is the secret).
`expiresAt`obrigatório	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`obrigatório	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
  }
}

Outras respostas

Status	Quando
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`.

Corpo (JSON)

Campo	Tipo	Descrição
`url`obrigatório	string	URL or ID of a YouTube video (watch, youtu.be, shorts, live, embed or clip).
`maxHeight`	inteiro, 144 a 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").

Exemplo

curl

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

Resposta 200

Campo	Tipo	Descrição
`videoId`obrigatório	string	Video ID.
`title`obrigatório	string
`author`obrigatório	string
`durationSeconds`obrigatório	inteiro, -9007199254740991 a 9007199254740991 \| null
`fileName`obrigatório	string
`fileSizeBytes`obrigatório	inteiro, -9007199254740991 a 9007199254740991
`downloadUrl`obrigatório	string	Download link, no authentication (the random identifier is the secret).
`expiresAt`obrigatório	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`obrigatório	"h264" \| "vp9" \| "av1" \| null
`compatibilityNote`	string	Present when the video is not H.264.
`videoFormat`obrigatório	object \| null
`audioFormat`obrigatório	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
  }
}

Outras respostas

Status	Quando
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`.

Corpo (JSON)

Campo	Tipo	Descrição
`url`obrigatório	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.

Exemplo

curl

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

Resposta 200

Campo	Tipo	Descrição
`videoId`obrigatório	string
`title`obrigatório	string
`author`obrigatório	string
`durationSeconds`obrigatório	inteiro, -9007199254740991 a 9007199254740991 \| null
`source`obrigatório	"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`obrigatório	string \| null
`languageName`obrigatório	string \| null
`cueCount`obrigatório	inteiro, -9007199254740991 a 9007199254740991
`aiTranscriptionSeconds`obrigatório	inteiro, -9007199254740991 a 9007199254740991 \| null	Seconds of audio transcribed by AI (null when it came from captions).
`aiTranscriptionUsedSeconds`	inteiro, -9007199254740991 a 9007199254740991	AI transcription used this month, in seconds (Pro).
`aiTranscriptionLimitSeconds`	inteiro, -9007199254740991 a 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 ..."
}

Outras respostas

Status	Quando
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.

Exemplo

curl

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

Resposta 200

Campo	Tipo	Descrição
`subject`obrigatório	string	Quota owner: user:<id> (account) or key:<id> (standalone key).
`via`obrigatório	"key" \| "oauth"
`plan`obrigatório	object
`quota`obrigatório	object
`aiTranscription`obrigatório	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"
  }
}

Outras respostas

Status	Quando
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.

Parâmetros de caminho

Parâmetro	Tipo	Descrição
`id`obrigatório	string

Exemplo

curl

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

Resposta 200

Campo	Tipo	Descrição
`id`obrigatório	string
`tool`obrigatório	"download_audio" \| "download_video" \| "transcribe_video"
`status`obrigatório	"running" \| "done" \| "error"
`createdAt`obrigatório	string
`finishedAt`obrigatório	string \| null
`statusUrl`obrigatório	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
    }
  }
}

Outras respostas

Status	Quando
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.

Formato de erro

Campo	Tipo	Descrição
`code`obrigatório	"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`obrigatório	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.

Referência da API

POST/v1/audio

Corpo (JSON)

Exemplo

Resposta 200

Outras respostas

POST/v1/video

Corpo (JSON)

Exemplo

Resposta 200

Outras respostas

POST/v1/transcribe

Corpo (JSON)

Exemplo

Resposta 200

Outras respostas

GET/v1/me

Exemplo

Resposta 200

Outras respostas

GET/v1/jobs/{id}

Parâmetros de caminho

Exemplo

Resposta 200

Outras respostas

Formato de erro

POST`/v1/audio`

POST`/v1/video`

POST`/v1/transcribe`

GET`/v1/me`

GET`/v1/jobs/{id}`