{"openapi":"3.1.0","info":{"title":"TranscriptYT YouTube Transcript API","version":"1.0.0","description":"YouTube Transcript API for developers. Get any public video's transcript as JSON, text, SRT, or VTT in 150+ languages, with AI transcription fallback. Full guide: https://transcript-yt.com/docs","contact":{"email":"aadit@techiseasy.co.in","url":"https://transcript-yt.com"},"termsOfService":"https://transcript-yt.com/terms"},"servers":[{"url":"https://transcript-yt.com"}],"externalDocs":{"url":"https://transcript-yt.com/docs"},"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"paths":{"/v1/transcript":{"get":{"operationId":"getTranscript","summary":"Get a YouTube video transcript","description":"Returns the transcript of a public YouTube video. Costs 1 credit; videos with no captions are transcribed with AI speech-to-text at 1 credit per started 3 minutes of audio. Failed requests are not billed.","parameters":[{"name":"url","in":"query","required":true,"description":"A YouTube URL (watch, youtu.be, shorts, embed) or a bare 11-character video ID.","schema":{"type":"string","example":"5f3Pn-N6yLc"}},{"name":"language","in":"query","description":"BCP-47 code. Defaults to the original / English track. If the video has no track in this language, the original is machine-translated.","schema":{"type":"string","pattern":"^[A-Za-z0-9-]{2,16}$"}},{"name":"translate_to","in":"query","description":"BCP-47 target code (150+ languages). Machine-translates the selected track, keeping timings.","schema":{"type":"string","pattern":"^[A-Za-z0-9-]{2,16}$"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","text","srt","vtt","csv","md"],"default":"json"}},{"name":"includeSegments","in":"query","description":"Set false to return only full text (JSON format only).","schema":{"type":"boolean","default":true}},{"name":"timestamps","in":"query","description":"Prefix each line with [HH:MM:SS] in text and md output.","schema":{"type":"boolean","default":false}},{"name":"paragraphs","in":"query","description":"Merge segments into paragraph-length chunks.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Transcript. JSON by default; text/plain, text/vtt, text/csv, or text/markdown for other formats.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix seconds when the window resets."},"X-Credits-Charged":{"schema":{"type":"integer"}},"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Cache":{"schema":{"type":"string","enum":["HIT","MISS"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transcript"}},"text/plain":{"schema":{"type":"string"}},"text/vtt":{"schema":{"type":"string"}},"text/csv":{"schema":{"type":"string"}},"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"INVALID_REQUEST or INVALID_VIDEO","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHORIZED: missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Out of credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutOfCredits"}}}},"404":{"description":"VIDEO_UNAVAILABLE, NO_CAPTIONS, or LANGUAGE_NOT_AVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"UPSTREAM_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"BLOCKED (temporary, retry shortly) or SERVICE_UNAVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"postTranscript","summary":"Get a YouTube video transcript (JSON body)","description":"Same as GET /v1/transcript with parameters in a JSON body.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string"},"language":{"type":"string","pattern":"^[A-Za-z0-9-]{2,16}$"},"translate_to":{"type":"string","pattern":"^[A-Za-z0-9-]{2,16}$"},"format":{"type":"string","enum":["json","text","srt","vtt","csv","md"],"default":"json"},"includeSegments":{"type":"boolean","default":true},"timestamps":{"type":"boolean","default":false},"paragraphs":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Transcript. JSON by default; text/plain, text/vtt, text/csv, or text/markdown for other formats.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix seconds when the window resets."},"X-Credits-Charged":{"schema":{"type":"integer"}},"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Cache":{"schema":{"type":"string","enum":["HIT","MISS"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transcript"}},"text/plain":{"schema":{"type":"string"}},"text/vtt":{"schema":{"type":"string"}},"text/csv":{"schema":{"type":"string"}},"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"INVALID_REQUEST or INVALID_VIDEO","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHORIZED: missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Out of credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutOfCredits"}}}},"404":{"description":"VIDEO_UNAVAILABLE, NO_CAPTIONS, or LANGUAGE_NOT_AVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"UPSTREAM_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"BLOCKED (temporary, retry shortly) or SERVICE_UNAVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/languages":{"get":{"operationId":"listLanguages","summary":"List a video's caption tracks","description":"Lists available caption tracks without downloading one. Free.","parameters":[{"name":"url","in":"query","required":true,"description":"A YouTube URL (watch, youtu.be, shorts, embed) or a bare 11-character video ID.","schema":{"type":"string","example":"5f3Pn-N6yLc"}}],"responses":{"200":{"description":"Caption tracks","content":{"application/json":{"schema":{"type":"object","properties":{"videoId":{"type":"string"},"languages":{"type":"array","items":{"type":"object","required":["languageCode","languageName","autoGenerated"],"properties":{"languageCode":{"type":"string","example":"en"},"languageName":{"type":"string","example":"English"},"autoGenerated":{"type":"boolean"}}}}}}}}},"400":{"description":"INVALID_VIDEO","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"UNAUTHORIZED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"VIDEO_UNAVAILABLE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/usage":{"get":{"operationId":"getUsage","summary":"Get plan and remaining credits","description":"Free.","responses":{"200":{"description":"Usage","content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string","example":"STARTER"},"credits_remaining":{"type":"integer"},"plan_credits":{"type":"object","properties":{"total":{"type":"integer"},"used":{"type":"integer"},"remaining":{"type":"integer"}}},"topup_credits":{"type":"object","properties":{"remaining":{"type":"integer"},"grants":{"type":"array","items":{"type":"object","properties":{"remaining":{"type":"integer"},"expires_at":{"type":"string","format":"date-time"}}}}}},"period_resets_at":{"type":["string","null"],"format":"date-time"},"rate_limit_per_minute":{"type":"integer"}}}}}},"401":{"description":"UNAUTHORIZED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key, e.g. ts_live_..."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Segment":{"type":"object","required":["start","duration","text"],"properties":{"start":{"type":"number","description":"Seconds"},"duration":{"type":"number","description":"Seconds"},"text":{"type":"string"}}},"Transcript":{"type":"object","properties":{"videoId":{"type":"string"},"title":{"type":["string","null"]},"author":{"type":["string","null"]},"channelId":{"type":["string","null"]},"durationSeconds":{"type":"number"},"language":{"type":"string","description":"Language delivered (the target when translated)."},"translated":{"type":"boolean"},"autoGenerated":{"type":"boolean"},"source":{"type":"string","enum":["captions","speech_to_text"]},"segments":{"type":"array","items":{"$ref":"#/components/schemas/Segment"}},"text":{"type":"string"},"availableLanguages":{"type":"array","items":{"type":"object","required":["languageCode","languageName","autoGenerated"],"properties":{"languageCode":{"type":"string","example":"en"},"languageName":{"type":"string","example":"English"},"autoGenerated":{"type":"boolean"}}}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_REQUEST","INVALID_VIDEO","VIDEO_UNAVAILABLE","NO_CAPTIONS","LANGUAGE_NOT_AVAILABLE","BLOCKED","UPSTREAM_ERROR","UNAUTHORIZED","RATE_LIMITED","SERVICE_UNAVAILABLE","INTERNAL"]},"message":{"type":"string"}}}}},"OutOfCredits":{"type":"object","properties":{"error":{"type":"string","example":"Out of credits"},"plan":{"type":"string"},"credits_remaining":{"type":"integer"},"upgrade_url":{"type":"string"},"topup_url":{"type":"string"}}}}}}