{"openapi":"3.1.0","info":{"title":"YouTube Transcript API - Public","description":"TranscriptAPI: extract the transcript of any YouTube video as structured JSON, with or without timestamps. The same API also covers search, channels, playlists, and video metadata.\n\nBase URL: [https://transcriptapi.com](https://transcriptapi.com) (every path below is under /api/v2/youtube).\n\nAuth: send Authorization: Bearer YOUR_API_KEY. Get a key at [https://transcriptapi.com/dashboard/api-keys](https://transcriptapi.com/dashboard/api-keys).\n\nCredits: failed calls and 429s cost 0; successful calls cost 1 credit unless the endpoint states otherwise. Costs are stated on each endpoint, including per-page pricing on paginated endpoints. Cached responses (HTTP 200) also cost 1 credit.\n\nRate limits: 200 requests per minute per key. Honor X-RateLimit headers and Retry-After on 429.\n\nErrors: every endpoint documents its status codes and retry flags; retry only 408, 429, and 503.\n\nCommon tasks:\n- Transcribe a video: GET /api/v2/youtube/transcript?video_url=UF8uR6Z6KLc\n- Find videos on a topic to transcribe: GET /api/v2/youtube/search?q=ocean+conservation&type=video&upload_date=week\n- Size up a channel (subscribers, video count, tabs): GET /api/v2/youtube/channel/info?channel=@NASA\n- Pull a channel's videos, Shorts, or streams: GET /api/v2/youtube/channel/videos?channel=@NASA&tab=shorts\n- Get a video's likes, views, description links, and related videos: GET /api/v2/youtube/video/metadata?video_url=UF8uR6Z6KLc&include=related\n- List a playlist's videos: GET /api/v2/youtube/playlist/videos?playlist=<URL or PL... ID>\n- Check a video's available transcript languages, at no credit cost: GET /api/v2/youtube/info?video_url=UF8uR6Z6KLc\n- Do all of this from Claude Desktop or any MCP client: [https://transcriptapi.com/docs/mcp](https://transcriptapi.com/docs/mcp)\n\nGuides and full reference: [https://transcriptapi.com/docs/api](https://transcriptapi.com/docs/api)","version":"1.0.0"},"paths":{"/api/v2/youtube/transcript":{"get":{"tags":["YouTube transcript"],"summary":"Get YouTube transcript (v2)","description":"Get a YouTube video's transcript — pass a video URL or 11-character ID as `video_url`.\n\nBy default you get English, or the video's first available language if there's no English.\n\nTo choose a language, set `language` to a comma-separated list in priority order; we return the first one that's available. Example: `language=de,en,asr` tries German, then English, then the auto-generated captions.\n\n- `asr` = the video's auto-generated captions (ASR = automatic speech recognition).\n- `asr-<code>` = auto-generated captions in a specific language, e.g. `asr-hi`.\n- A plain code like `hi` returns the human-made captions if they exist, otherwise the auto-generated ones (`asr-hi`).\n- Language codes ignore region (`de` matches `de-DE`) and are case-insensitive. Up to 10 codes.\n\nThe `language` field in the response always tells you exactly what you got. Tip: call GET /api/v2/youtube/info first (it's free) to see which languages a video offers.","operationId":"get_transcript_v2_api_v2_youtube_transcript_get","security":[{"bearerAuth":[]}],"parameters":[{"name":"video_url","in":"query","required":true,"schema":{"type":"string","pattern":"^([a-zA-Z0-9_-]{11}|https?://.*)$","description":"YouTube video URL or bare 11-char ID","title":"Video Url"},"description":"YouTube video URL or bare 11-char ID"},{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional comma-separated language priority list (e.g. `de,en,asr`). Omit it to get English, or the video's first available language. We return the first code that's available. `asr` = auto-generated captions; `asr-<code>` = a specific auto language (e.g. `asr-hi`). Codes ignore region (`de` matches `de-DE`). The response's `language` field tells you exactly what you got — ask for `hi` and you'll see `asr-hi` if only auto-generated captions exist.","title":"Language"},"description":"Optional comma-separated language priority list (e.g. `de,en,asr`). Omit it to get English, or the video's first available language. We return the first code that's available. `asr` = auto-generated captions; `asr-<code>` = a specific auto language (e.g. `asr-hi`). Codes ignore region (`de` matches `de-DE`). The response's `language` field tells you exactly what you got — ask for `hi` and you'll see `asr-hi` if only auto-generated captions exist.","examples":{"german_then_english":{"summary":"Prefer German, fall back to English","description":"Returns German captions if available, otherwise English.","value":"de,en"},"auto_generated":{"summary":"Auto-generated captions only","description":"Skips human-made captions and asks for the ASR track directly.","value":"asr"}}},{"name":"language_fallback","in":"query","required":false,"schema":{"type":"boolean","description":"Only used with `language`. `true` (default): a plain code like `hi` returns the human-made captions when they exist, otherwise the auto-generated ones. `false`: a plain code returns human-made captions only; if none exist for any code you listed you get a `404` with `available_languages` (no credit used). With `false`, a plain code whose `kind` is `auto` is skipped and the next code is tried. `asr` / `asr-<code>` still ask for auto-generated captions.","default":true,"title":"Language Fallback"},"description":"Only used with `language`. `true` (default): a plain code like `hi` returns the human-made captions when they exist, otherwise the auto-generated ones. `false`: a plain code returns human-made captions only; if none exist for any code you listed you get a `404` with `available_languages` (no credit used). With `false`, a plain code whose `kind` is `auto` is skipped and the next code is tried. `asr` / `asr-<code>` still ask for auto-generated captions."},{"name":"send_metadata","in":"query","required":false,"schema":{"type":"boolean","description":"Include basic video metadata in response","default":false,"title":"Send Metadata"},"description":"Include basic video metadata in response"},{"name":"format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/TranscriptFormatV2","description":"Response format: json or text","default":"json"},"description":"Response format: json or text"},{"name":"include_timestamp","in":"query","required":false,"schema":{"type":"boolean","description":"Include timestamps in transcript output","default":true,"title":"Include Timestamp"},"description":"Include timestamps in transcript output"}],"responses":{"200":{"description":"Transcript retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APITranscriptResponseV2"},"examples":{"json_with_timestamps":{"summary":"JSON format with timestamps (default)","value":{"video_id":"dQw4w9WgXcQ","language":"en","transcript":[{"text":"Never gonna give you up","start":0.0,"duration":4.12},{"text":"Never gonna let you down","start":4.12,"duration":3.85}],"metadata":{"title":"Rick Astley - Never Gonna Give You Up","author_name":"RickAstleyVEVO","author_url":"https://www.youtube.com/@RickAstley","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg"},"length_seconds":213,"lengthText":"3:33"}},"json_without_timestamps":{"summary":"JSON format without timestamps (include_timestamp=false)","value":{"video_id":"dQw4w9WgXcQ","language":"en","transcript":[{"text":"Never gonna give you up"},{"text":"Never gonna let you down"}],"length_seconds":213,"lengthText":"3:33"}},"text_with_timestamps":{"summary":"Text format with timestamps (default)","value":{"video_id":"dQw4w9WgXcQ","language":"en","transcript":"[0.0s] Never gonna give you up\n[4.12s] Never gonna let you down\n[7.97s] Never gonna run around and desert you","length_seconds":213,"lengthText":"3:33"}},"text_without_timestamps":{"summary":"Text format without timestamps (include_timestamp=false)","value":{"video_id":"dQw4w9WgXcQ","language":"en","transcript":"Never gonna give you up Never gonna let you down Never gonna run around and desert you","length_seconds":213,"lengthText":"3:33"}}}}},"headers":{"X-Cache-Status":{"description":"Cache status for the request (HIT, PARTIAL-HIT, MISS)","schema":{"type":"string"}}}},"401":{"description":"Unauthorized - invalid Authorization format or API key","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}},"headers":{"WWW-Authenticate":{"description":"Authentication scheme for this endpoint","schema":{"type":"string","example":"Bearer"}}}},"402":{"description":"Payment Required - inactive plan or exhausted credits","content":{"application/json":{"schema":{"$defs":{"PaymentActionDetail":{"properties":{"message":{"description":"User-friendly explanation of why payment is required","title":"Message","type":"string"},"reason":{"description":"Machine-readable reason for the payment requirement","enum":["insufficient_credits","no_active_paid_plan"],"title":"Reason","type":"string"},"action_label":{"description":"Short label for the recommended action CTA","title":"Action Label","type":"string"},"action_url":{"description":"URL to take the recommended action (top-up or pricing)","title":"Action Url","type":"string"}},"required":["message","reason","action_label","action_url"],"title":"PaymentActionDetail","type":"object"}},"properties":{"detail":{"$ref":"#/components/schemas/PaymentActionDetail"}},"required":["detail"],"title":"PaymentRequiredResponse","type":"object"},"examples":{"topup":{"summary":"Active paid plan but credits exhausted","value":{"detail":{"message":"You have an active plan, but you've run out of credits.","reason":"insufficient_credits","action_label":"Top up credits","action_url":"https://transcriptapi.com/top-up"}}},"billing":{"summary":"No active paid plan","value":{"detail":{"message":"You don't have an active paid plan yet.","reason":"no_active_paid_plan","action_label":"Go to billing to choose a plan","action_url":"https://transcriptapi.com/billing"}}}}}}},"404":{"description":"**Not Found** - Video doesn't exist or no transcript available. **Do not retry.**\n\nThe body has a human `detail` and a machine-readable `code`: `no_captions` (the video exists but has no captions), `video_unavailable` (the video can't be retrieved), or, when `language` was provided (Mode B), `no_transcript_for_requested_languages` together with an `available_languages` list so the caller can retry with a language that exists.","content":{"application/json":{"schema":{"$defs":{"AvailableLanguage":{"description":"A language available for a video (PRD §5.2).\n\n`code` is a normalized base code (`en`, `de`, `zh`) or the reserved `asr`\npseudo-code for auto-generated captions.","properties":{"code":{"description":"Normalized language code, or 'asr' for auto-generated","title":"Code","type":"string"},"name":{"description":"Human-readable language name","title":"Name","type":"string"},"kind":{"anyOf":[{"enum":["manual","auto"],"type":"string"},{"type":"null"}],"description":"What this code returns: 'manual' = human-made captions, 'auto' = YouTube's auto-generated captions. A plain code (e.g. `ru`) returns the manual track when one exists, otherwise the auto track, so it can be 'auto' too; `asr-<code>` is always 'auto'.","title":"Kind"}},"required":["code","name"],"title":"AvailableLanguage","type":"object"}},"description":"Canonical 404 body when a Mode B `language` priority list resolves nothing.\n\nOnly returned when `language` is provided (Mode B). The legacy Mode A 404\n(no `language` param) uses the plain `ErrorResponse` shape with no\n`available_languages`.","properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"description":"Machine-readable error code","title":"Code","type":"string"},"available_languages":{"description":"Languages that ARE available, so the caller can retry","items":{"$ref":"#/components/schemas/AvailableLanguage"},"title":"Available Languages","type":"array"}},"required":["detail","code"],"title":"TranscriptNotFoundResponse","type":"object"},"examples":{"no_captions":{"summary":"Video exists but has no captions - code `no_captions`","value":{"detail":"No transcript available for video ABC123XYZ","code":"no_captions"}},"video_unavailable":{"summary":"Video can't be retrieved (deleted, private, nonexistent) - code `video_unavailable`","value":{"detail":"Video ABC123XYZ not found or unavailable","code":"video_unavailable"}},"no_transcript_for_requested_languages":{"summary":"`language` provided (Mode B) - includes code + available_languages","value":{"detail":"No transcript available for the requested languages: en, de","code":"no_transcript_for_requested_languages","available_languages":[{"code":"hi","name":"Hindi","kind":"manual"},{"code":"asr-hi","name":"Hindi (auto-generated)","kind":"auto"}]}}}}}},"408":{"description":"**Request Timeout / Retry** - Temporary failure (bot detection, network issues). **Safe to retry** after a short delay (1-5 seconds).","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"retry":{"summary":"Temporary failure - retry recommended","value":{"detail":"Request failed, please retry"}}}}}},"422":{"description":"**Validation Error** - Invalid YouTube URL or video ID format. **Do not retry** with the same input.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}}},"429":{"description":"**Too Many Requests** - Rate limit exceeded. **Retry after** the delay in `Retry-After` header.","headers":{"Retry-After":{"description":"Seconds until the limit resets","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}}},"500":{"description":"**Internal Server Error** - Unexpected error. May retry, but if persistent, contact support.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"server_error":{"summary":"Unexpected server error","value":{"detail":"Internal server error"}}}}}},"503":{"description":"**Service Unavailable** - Service temporarily down or initializing. **Retry** after a short delay.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"unavailable":{"summary":"Service temporarily unavailable","value":{"detail":"Service not initialized"}}}}}}}}},"/api/v2/youtube/info":{"get":{"tags":["YouTube transcript"],"summary":"Get YouTube video info (v2)","description":"Discover a video's metadata and available transcript languages — free (no credit used), with the same API key/plan as the transcript endpoint. Each language is returned as a code you can pass to the transcript endpoint's `language` parameter (e.g. `en`, or `asr-en` for auto-generated English). Each also has a `kind`: `manual` (human-made captions) or `auto` (auto-generated). A plain code returns the manual track when one exists, otherwise the auto track, so `kind` tells you which one you will get.","operationId":"get_video_info_v2_api_v2_youtube_info_get","security":[{"bearerAuth":[]}],"parameters":[{"name":"video_url","in":"query","required":true,"schema":{"type":"string","pattern":"^([a-zA-Z0-9_-]{11}|https?://.*)$","description":"YouTube video URL or bare 11-char ID","title":"Video Url"},"description":"YouTube video URL or bare 11-char ID"}],"responses":{"200":{"description":"Video metadata and available languages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__api__v2__youtube__schemas__VideoInfoResponse"},"examples":{"info":{"summary":"Metadata + available languages","value":{"video_id":"dQw4w9WgXcQ","metadata":{"title":"Rick Astley - Never Gonna Give You Up","author_name":"RickAstleyVEVO","author_url":"https://www.youtube.com/@RickAstley","thumbnail_url":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg"},"available_languages":[{"code":"en","name":"English","kind":"manual"},{"code":"asr-en","name":"English (auto-generated)","kind":"auto"}]}}}}}},"401":{"description":"Unauthorized - invalid Authorization format or API key","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}},"headers":{"WWW-Authenticate":{"description":"Authentication scheme for this endpoint","schema":{"type":"string","example":"Bearer"}}}},"402":{"description":"Payment Required - inactive plan or exhausted credits","content":{"application/json":{"schema":{"$defs":{"PaymentActionDetail":{"properties":{"message":{"description":"User-friendly explanation of why payment is required","title":"Message","type":"string"},"reason":{"description":"Machine-readable reason for the payment requirement","enum":["insufficient_credits","no_active_paid_plan"],"title":"Reason","type":"string"},"action_label":{"description":"Short label for the recommended action CTA","title":"Action Label","type":"string"},"action_url":{"description":"URL to take the recommended action (top-up or pricing)","title":"Action Url","type":"string"}},"required":["message","reason","action_label","action_url"],"title":"PaymentActionDetail","type":"object"}},"properties":{"detail":{"$ref":"#/components/schemas/PaymentActionDetail"}},"required":["detail"],"title":"PaymentRequiredResponse","type":"object"},"examples":{"topup":{"summary":"Active paid plan but credits exhausted","value":{"detail":{"message":"You have an active plan, but you've run out of credits.","reason":"insufficient_credits","action_label":"Top up credits","action_url":"https://transcriptapi.com/top-up"}}},"billing":{"summary":"No active paid plan","value":{"detail":{"message":"You don't have an active paid plan yet.","reason":"no_active_paid_plan","action_label":"Go to billing to choose a plan","action_url":"https://transcriptapi.com/billing"}}}}}}},"404":{"description":"**Not Found** - Video doesn't exist or has no caption tracks. **Do not retry.**","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"no_captions":{"summary":"Video has no caption tracks","value":{"detail":"No transcript available for video ABC123XYZ"}}}}}},"408":{"description":"**Request Timeout / Retry** - Temporary failure (bot detection, network issues). **Safe to retry** after a short delay (1-5 seconds).","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"retry":{"summary":"Temporary failure - retry recommended","value":{"detail":"Request failed, please retry"}}}}}},"422":{"description":"**Validation Error** - Invalid input format. **Do not retry** with the same input.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}}},"429":{"description":"**Too Many Requests** - Rate limit exceeded. **Retry after** the delay in `Retry-After` header.","headers":{"Retry-After":{"description":"Seconds until the limit resets","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}}},"500":{"description":"**Internal Server Error** - Unexpected error. May retry, but if persistent, contact support.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"server_error":{"summary":"Unexpected server error","value":{"detail":"Internal server error"}}}}}},"503":{"description":"**Service Unavailable** - Service temporarily down or initializing. **Retry** after a short delay.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"unavailable":{"summary":"Service temporarily unavailable","value":{"detail":"Service not initialized"}}}}}}}}},"/api/v2/youtube/search":{"get":{"tags":["YouTube search"],"summary":"Search YouTube videos or channels","description":"Search YouTube for videos or channels.\n\n- `type=video` (default): Returns video results with titles, thumbnails, view counts, etc.\n- `type=channel`: Returns channel results with handles, subscriber counts, etc.\n\nReturns YouTube's full page (~20 items) per call.\n\n**Pagination:** The response includes `continuation_token` (when `has_more=true`). To fetch the next page, call the endpoint again with `continuation=<token>` and omit `q`/`type` (the token already encodes them).\n\n**Credit cost:** 1 credit per successful request (each page).","operationId":"search_api_v2_youtube_search_get","security":[{"bearerAuth":[]}],"parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}],"description":"Search query (required for first page)","title":"Q"},"description":"Search query (required for first page)"},{"name":"type","in":"query","required":false,"schema":{"$ref":"#/components/schemas/SearchType","description":"Result type: video, channel, playlist, or movie","default":"video"},"description":"Result type: video, channel, playlist, or movie","examples":{"videos":{"summary":"Videos (default)","value":"video"},"channels":{"summary":"Channels","value":"channel"},"playlists":{"summary":"Playlists","value":"playlist"},"movies":{"summary":"Movies","value":"movie"}}},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(relevance|views)$"},{"type":"null"}],"description":"Sort order (first page): relevance (default) or views (YouTube 'Popularity'). YouTube no longer offers upload-date or rating sort in search. Use upload_date windows for recency.","title":"Sort"},"description":"Sort order (first page): relevance (default) or views (YouTube 'Popularity'). YouTube no longer offers upload-date or rating sort in search. Use upload_date windows for recency.","examples":{"most_viewed":{"summary":"Most viewed first","value":"views"}}},{"name":"upload_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(hour|today|week|month|year)$"},{"type":"null"}],"description":"Upload-date window (first page). Videos only.","title":"Upload Date"},"description":"Upload-date window (first page). Videos only.","examples":{"past_week":{"summary":"Uploaded in the last week","value":"week"}}},{"name":"duration","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(short|medium|long)$"},{"type":"null"}],"description":"Duration bucket (first page). Videos only: short <4m, medium 4-20m, long >20m.","title":"Duration"},"description":"Duration bucket (first page). Videos only: short <4m, medium 4-20m, long >20m.","examples":{"long_form":{"summary":"Long-form only (>20m)","value":"long"}}},{"name":"features","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated feature filters (first page), e.g. hd,subtitles,cc,live,4k,hdr,360,vr180,3d,location,creative_commons,purchased.","title":"Features"},"description":"Comma-separated feature filters (first page), e.g. hd,subtitles,cc,live,4k,hdr,360,vr180,3d,location,creative_commons,purchased."},{"name":"sp","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9+/=_-]+$"},{"type":"null"}],"description":"Advanced: raw YouTube `sp` filter (base64). Overrides the structured filters above.","title":"Sp"},"description":"Advanced: raw YouTube `sp` filter (base64). Overrides the structured filters above."},{"name":"continuation","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"Continuation token from previous page. When provided, q/type/filters are ignored.","title":"Continuation"},"description":"Continuation token from previous page. When provided, q/type/filters are ignored.","examples":{"next_page":{"summary":"Fetch the next page","description":"Opaque token copied verbatim from the previous response's `continuation` field.","value":"<continuation-token-from-previous-response>"}}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"**Bad Request** - Invalid parameter combination. Provide either `q` or `continuation`, not both.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"missing":{"summary":"No parameter provided","value":{"detail":"Either 'q' or 'continuation' is required"}},"both":{"summary":"Both parameters provided","value":{"detail":"Provide either 'q' or 'continuation', not both"}}}}}},"401":{"description":"Unauthorized - invalid Authorization format or API key","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}},"headers":{"WWW-Authenticate":{"description":"Authentication scheme for this endpoint","schema":{"type":"string","example":"Bearer"}}}},"402":{"description":"Payment Required - inactive plan or exhausted credits","content":{"application/json":{"schema":{"$defs":{"PaymentActionDetail":{"properties":{"message":{"description":"User-friendly explanation of why payment is required","title":"Message","type":"string"},"reason":{"description":"Machine-readable reason for the payment requirement","enum":["insufficient_credits","no_active_paid_plan"],"title":"Reason","type":"string"},"action_label":{"description":"Short label for the recommended action CTA","title":"Action Label","type":"string"},"action_url":{"description":"URL to take the recommended action (top-up or pricing)","title":"Action Url","type":"string"}},"required":["message","reason","action_label","action_url"],"title":"PaymentActionDetail","type":"object"}},"properties":{"detail":{"$ref":"#/components/schemas/PaymentActionDetail"}},"required":["detail"],"title":"PaymentRequiredResponse","type":"object"},"examples":{"topup":{"summary":"Active paid plan but credits exhausted","value":{"detail":{"message":"You have an active plan, but you've run out of credits.","reason":"insufficient_credits","action_label":"Top up credits","action_url":"https://transcriptapi.com/top-up"}}},"billing":{"summary":"No active paid plan","value":{"detail":{"message":"You don't have an active paid plan yet.","reason":"no_active_paid_plan","action_label":"Go to billing to choose a plan","action_url":"https://transcriptapi.com/billing"}}}}}}},"408":{"description":"**Request Timeout / Retry** - Temporary failure (bot detection, network issues). **Safe to retry** after a short delay (1-5 seconds).","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"retry":{"summary":"Temporary failure - retry recommended","value":{"detail":"Request failed, please retry"}}}}}},"422":{"description":"**Validation Error** - Invalid input format. **Do not retry** with the same input.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}}},"429":{"description":"**Too Many Requests** - Rate limit exceeded. **Retry after** the delay in `Retry-After` header.","headers":{"Retry-After":{"description":"Seconds until the limit resets","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}}},"500":{"description":"**Internal Server Error** - Unexpected error. May retry, but if persistent, contact support.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"server_error":{"summary":"Unexpected server error","value":{"detail":"Internal server error"}}}}}},"503":{"description":"**Service Unavailable** - Service temporarily down or initializing. **Retry** after a short delay.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"unavailable":{"summary":"Service temporarily unavailable","value":{"detail":"Service not initialized"}}}}}}}}},"/api/v2/youtube/channel/resolve":{"get":{"tags":["YouTube channel"],"summary":"Resolve channel reference to UC... ID","description":"Resolve any channel reference (@handle, URL, or UC... ID) to a canonical UC... channel ID.\n\n**Credit cost:** FREE (requires auth + at least 1 active credit, but does not charge).","operationId":"resolve_channel_api_v2_youtube_channel_resolve_get","security":[{"bearerAuth":[]}],"parameters":[{"name":"input","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"@handle, channel URL, or UC... ID","title":"Input"},"description":"@handle, channel URL, or UC... ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelResolveResponse"}}}},"400":{"description":"**Bad Request** - Missing or invalid parameters. **Do not retry** with the same input.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}}},"401":{"description":"Unauthorized - invalid Authorization format or API key","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}},"headers":{"WWW-Authenticate":{"description":"Authentication scheme for this endpoint","schema":{"type":"string","example":"Bearer"}}}},"402":{"description":"Payment Required - inactive plan or exhausted credits","content":{"application/json":{"schema":{"$defs":{"PaymentActionDetail":{"properties":{"message":{"description":"User-friendly explanation of why payment is required","title":"Message","type":"string"},"reason":{"description":"Machine-readable reason for the payment requirement","enum":["insufficient_credits","no_active_paid_plan"],"title":"Reason","type":"string"},"action_label":{"description":"Short label for the recommended action CTA","title":"Action Label","type":"string"},"action_url":{"description":"URL to take the recommended action (top-up or pricing)","title":"Action Url","type":"string"}},"required":["message","reason","action_label","action_url"],"title":"PaymentActionDetail","type":"object"}},"properties":{"detail":{"$ref":"#/components/schemas/PaymentActionDetail"}},"required":["detail"],"title":"PaymentRequiredResponse","type":"object"},"examples":{"topup":{"summary":"Active paid plan but credits exhausted","value":{"detail":{"message":"You have an active plan, but you've run out of credits.","reason":"insufficient_credits","action_label":"Top up credits","action_url":"https://transcriptapi.com/top-up"}}},"billing":{"summary":"No active paid plan","value":{"detail":{"message":"You don't have an active paid plan yet.","reason":"no_active_paid_plan","action_label":"Go to billing to choose a plan","action_url":"https://transcriptapi.com/billing"}}}}}}},"404":{"description":"**Not Found** - Channel does not exist. **Do not retry.**","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"not_found":{"summary":"Channel not found","value":{"detail":"Channel not found"}}}}}},"408":{"description":"**Request Timeout / Retry** - Temporary failure (bot detection, network issues). **Safe to retry** after a short delay (1-5 seconds).","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"retry":{"summary":"Temporary failure - retry recommended","value":{"detail":"Request failed, please retry"}}}}}},"429":{"description":"**Too Many Requests** - Rate limit exceeded. **Retry after** the delay in `Retry-After` header.","headers":{"Retry-After":{"description":"Seconds until the limit resets","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}}},"500":{"description":"**Internal Server Error** - Unexpected error. May retry, but if persistent, contact support.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"server_error":{"summary":"Unexpected server error","value":{"detail":"Internal server error"}}}}}},"503":{"description":"**Service Unavailable** - Service temporarily down or initializing. **Retry** after a short delay.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"unavailable":{"summary":"Service temporarily unavailable","value":{"detail":"Service not initialized"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v2/youtube/channel/info":{"get":{"tags":["YouTube channel"],"summary":"Channel profile / identity","description":"Fetch a channel's profile: title, @handle, verified flag, subscriber/video count text, description, keywords, tags, thumbnails, banners, and available tabs.\n\nUse the `channel` parameter with an @handle, channel URL, or UC... channel ID.\n\nFormatted counts are display strings (e.g. `27.8M subscribers`) and are `null` when YouTube does not expose them — never `0`. About-tab fields YouTube does not serve over an unauthenticated request (join date, total views, country, external links) are omitted.\n\n**Freshness:** cached for 5 minutes.\n\n**Credit cost:** 1 credit per request.","operationId":"channel_info_api_v2_youtube_channel_info_get","security":[{"bearerAuth":[]}],"parameters":[{"name":"channel","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Channel identifier: @handle, channel URL, or UC... channel ID","title":"Channel"},"description":"Channel identifier: @handle, channel URL, or UC... channel ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelInfoResponse"}}}},"400":{"description":"**Bad Request** - Missing or invalid parameters. **Do not retry** with the same input.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}}},"401":{"description":"Unauthorized - invalid Authorization format or API key","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}},"headers":{"WWW-Authenticate":{"description":"Authentication scheme for this endpoint","schema":{"type":"string","example":"Bearer"}}}},"402":{"description":"Payment Required - inactive plan or exhausted credits","content":{"application/json":{"schema":{"$defs":{"PaymentActionDetail":{"properties":{"message":{"description":"User-friendly explanation of why payment is required","title":"Message","type":"string"},"reason":{"description":"Machine-readable reason for the payment requirement","enum":["insufficient_credits","no_active_paid_plan"],"title":"Reason","type":"string"},"action_label":{"description":"Short label for the recommended action CTA","title":"Action Label","type":"string"},"action_url":{"description":"URL to take the recommended action (top-up or pricing)","title":"Action Url","type":"string"}},"required":["message","reason","action_label","action_url"],"title":"PaymentActionDetail","type":"object"}},"properties":{"detail":{"$ref":"#/components/schemas/PaymentActionDetail"}},"required":["detail"],"title":"PaymentRequiredResponse","type":"object"},"examples":{"topup":{"summary":"Active paid plan but credits exhausted","value":{"detail":{"message":"You have an active plan, but you've run out of credits.","reason":"insufficient_credits","action_label":"Top up credits","action_url":"https://transcriptapi.com/top-up"}}},"billing":{"summary":"No active paid plan","value":{"detail":{"message":"You don't have an active paid plan yet.","reason":"no_active_paid_plan","action_label":"Go to billing to choose a plan","action_url":"https://transcriptapi.com/billing"}}}}}}},"404":{"description":"**Not Found** - Channel does not exist. **Do not retry.**","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"not_found":{"summary":"Channel not found","value":{"detail":"Channel not found"}}}}}},"408":{"description":"**Request Timeout / Retry** - Temporary failure (bot detection, network issues). **Safe to retry** after a short delay (1-5 seconds).","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"retry":{"summary":"Temporary failure - retry recommended","value":{"detail":"Request failed, please retry"}}}}}},"429":{"description":"**Too Many Requests** - Rate limit exceeded. **Retry after** the delay in `Retry-After` header.","headers":{"Retry-After":{"description":"Seconds until the limit resets","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}}},"500":{"description":"**Internal Server Error** - Unexpected error. May retry, but if persistent, contact support.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"server_error":{"summary":"Unexpected server error","value":{"detail":"Internal server error"}}}}}},"503":{"description":"**Service Unavailable** - Service temporarily down or initializing. **Retry** after a short delay.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"unavailable":{"summary":"Service temporarily unavailable","value":{"detail":"Service not initialized"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v2/youtube/channel/playlists":{"get":{"tags":["YouTube channel"],"summary":"Paginated channel playlists","description":"List the playlists shown on a channel (id, title, URL, video-count text, thumbnails), paginated.\n\nFirst request: provide `channel` (@handle, URL, or UC... ID). Subsequent requests: provide `continuation` token from the previous response.\n\nVideo-count text is a display string (e.g. `11 videos`) and is `null` when YouTube omits it — never `0`.\n\n**Freshness:** cached for 5 minutes.\n\n**Credit cost:** 1 credit per page.","operationId":"channel_playlists_api_v2_youtube_channel_playlists_get","security":[{"bearerAuth":[]}],"parameters":[{"name":"channel","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Channel identifier: @handle, channel URL, or UC... channel ID","title":"Channel"},"description":"Channel identifier: @handle, channel URL, or UC... channel ID"},{"name":"continuation","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"Continuation token from previous page","title":"Continuation"},"description":"Continuation token from previous page"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelPlaylistsResponse"}}}},"400":{"description":"**Bad Request** - Provide either `channel` or `continuation`, not both.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"missing":{"summary":"No parameter provided","value":{"detail":"Either 'channel' or 'continuation' is required"}},"both":{"summary":"Both parameters provided","value":{"detail":"Provide either 'channel'/'channel_id' or 'continuation', not both"}}}}}},"401":{"description":"Unauthorized - invalid Authorization format or API key","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}},"headers":{"WWW-Authenticate":{"description":"Authentication scheme for this endpoint","schema":{"type":"string","example":"Bearer"}}}},"402":{"description":"Payment Required - inactive plan or exhausted credits","content":{"application/json":{"schema":{"$defs":{"PaymentActionDetail":{"properties":{"message":{"description":"User-friendly explanation of why payment is required","title":"Message","type":"string"},"reason":{"description":"Machine-readable reason for the payment requirement","enum":["insufficient_credits","no_active_paid_plan"],"title":"Reason","type":"string"},"action_label":{"description":"Short label for the recommended action CTA","title":"Action Label","type":"string"},"action_url":{"description":"URL to take the recommended action (top-up or pricing)","title":"Action Url","type":"string"}},"required":["message","reason","action_label","action_url"],"title":"PaymentActionDetail","type":"object"}},"properties":{"detail":{"$ref":"#/components/schemas/PaymentActionDetail"}},"required":["detail"],"title":"PaymentRequiredResponse","type":"object"},"examples":{"topup":{"summary":"Active paid plan but credits exhausted","value":{"detail":{"message":"You have an active plan, but you've run out of credits.","reason":"insufficient_credits","action_label":"Top up credits","action_url":"https://transcriptapi.com/top-up"}}},"billing":{"summary":"No active paid plan","value":{"detail":{"message":"You don't have an active paid plan yet.","reason":"no_active_paid_plan","action_label":"Go to billing to choose a plan","action_url":"https://transcriptapi.com/billing"}}}}}}},"404":{"description":"**Not Found** - Channel does not exist. **Do not retry.**","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"not_found":{"summary":"Channel not found","value":{"detail":"Channel not found"}}}}}},"408":{"description":"**Request Timeout / Retry** - Temporary failure (bot detection, network issues). **Safe to retry** after a short delay (1-5 seconds).","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"retry":{"summary":"Temporary failure - retry recommended","value":{"detail":"Request failed, please retry"}}}}}},"429":{"description":"**Too Many Requests** - Rate limit exceeded. **Retry after** the delay in `Retry-After` header.","headers":{"Retry-After":{"description":"Seconds until the limit resets","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}}},"500":{"description":"**Internal Server Error** - Unexpected error. May retry, but if persistent, contact support.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"server_error":{"summary":"Unexpected server error","value":{"detail":"Internal server error"}}}}}},"503":{"description":"**Service Unavailable** - Service temporarily down or initializing. **Retry** after a short delay.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"unavailable":{"summary":"Service temporarily unavailable","value":{"detail":"Service not initialized"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v2/youtube/channel/posts":{"get":{"tags":["YouTube channel"],"summary":"Paginated channel community posts","description":"List a channel's community/Posts feed (text, publish time, like count text, and attachments — image, multi-image, video, playlist, or poll), paginated.\n\nFirst request: provide `channel` (@handle, URL, or UC... ID). Subsequent requests: provide `continuation` token from the previous response.\n\nChannels with no community tab return an empty `results` list (HTTP 200, not an error). Like counts are display strings (e.g. `1.2K`) and are `null` when hidden — never `0`.\n\n**Freshness:** cached for 5 minutes.\n\n**Credit cost:** 1 credit per page.","operationId":"channel_posts_api_v2_youtube_channel_posts_get","security":[{"bearerAuth":[]}],"parameters":[{"name":"channel","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Channel identifier: @handle, channel URL, or UC... channel ID","title":"Channel"},"description":"Channel identifier: @handle, channel URL, or UC... channel ID"},{"name":"continuation","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"Continuation token from previous page","title":"Continuation"},"description":"Continuation token from previous page"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelPostsResponse"}}}},"400":{"description":"**Bad Request** - Provide either `channel` or `continuation`, not both.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"missing":{"summary":"No parameter provided","value":{"detail":"Either 'channel' or 'continuation' is required"}},"both":{"summary":"Both parameters provided","value":{"detail":"Provide either 'channel'/'channel_id' or 'continuation', not both"}}}}}},"401":{"description":"Unauthorized - invalid Authorization format or API key","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}},"headers":{"WWW-Authenticate":{"description":"Authentication scheme for this endpoint","schema":{"type":"string","example":"Bearer"}}}},"402":{"description":"Payment Required - inactive plan or exhausted credits","content":{"application/json":{"schema":{"$defs":{"PaymentActionDetail":{"properties":{"message":{"description":"User-friendly explanation of why payment is required","title":"Message","type":"string"},"reason":{"description":"Machine-readable reason for the payment requirement","enum":["insufficient_credits","no_active_paid_plan"],"title":"Reason","type":"string"},"action_label":{"description":"Short label for the recommended action CTA","title":"Action Label","type":"string"},"action_url":{"description":"URL to take the recommended action (top-up or pricing)","title":"Action Url","type":"string"}},"required":["message","reason","action_label","action_url"],"title":"PaymentActionDetail","type":"object"}},"properties":{"detail":{"$ref":"#/components/schemas/PaymentActionDetail"}},"required":["detail"],"title":"PaymentRequiredResponse","type":"object"},"examples":{"topup":{"summary":"Active paid plan but credits exhausted","value":{"detail":{"message":"You have an active plan, but you've run out of credits.","reason":"insufficient_credits","action_label":"Top up credits","action_url":"https://transcriptapi.com/top-up"}}},"billing":{"summary":"No active paid plan","value":{"detail":{"message":"You don't have an active paid plan yet.","reason":"no_active_paid_plan","action_label":"Go to billing to choose a plan","action_url":"https://transcriptapi.com/billing"}}}}}}},"404":{"description":"**Not Found** - Channel does not exist. **Do not retry.**","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"not_found":{"summary":"Channel not found","value":{"detail":"Channel not found"}}}}}},"408":{"description":"**Request Timeout / Retry** - Temporary failure (bot detection, network issues). **Safe to retry** after a short delay (1-5 seconds).","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"retry":{"summary":"Temporary failure - retry recommended","value":{"detail":"Request failed, please retry"}}}}}},"429":{"description":"**Too Many Requests** - Rate limit exceeded. **Retry after** the delay in `Retry-After` header.","headers":{"Retry-After":{"description":"Seconds until the limit resets","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}}},"500":{"description":"**Internal Server Error** - Unexpected error. May retry, but if persistent, contact support.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"server_error":{"summary":"Unexpected server error","value":{"detail":"Internal server error"}}}}}},"503":{"description":"**Service Unavailable** - Service temporarily down or initializing. **Retry** after a short delay.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"unavailable":{"summary":"Service temporarily unavailable","value":{"detail":"Service not initialized"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v2/youtube/channel/sections":{"get":{"tags":["YouTube channel"],"summary":"Curated channel sections (Home/featured page)","description":"Return the curated, grouped sections shown on a channel page — titled shelves of videos, playlists, shorts, or featured channels, in the channel's own order. This is the grouped-page view, distinct from the flat `/channel/videos` and `/channel/playlists` lists.\n\nUse `channel` (@handle, URL, or UC... ID). `tab` selects which page: `featured` (default, the Home page), `podcasts`, or `releases` — the latter two exist only on channels that have them (an empty `results` list otherwise).\n\n**Freshness:** cached for 5 minutes.\n\n**Credit cost:** 1 credit per request.","operationId":"channel_sections_api_v2_youtube_channel_sections_get","security":[{"bearerAuth":[]}],"parameters":[{"name":"channel","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Channel identifier: @handle, channel URL, or UC... channel ID","title":"Channel"},"description":"Channel identifier: @handle, channel URL, or UC... channel ID"},{"name":"tab","in":"query","required":false,"schema":{"type":"string","pattern":"^(featured|podcasts|releases)$","description":"Which curated page: featured (default), podcasts, or releases","default":"featured","title":"Tab"},"description":"Which curated page: featured (default), podcasts, or releases"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelSectionsResponse"}}}},"400":{"description":"**Bad Request** - Missing or invalid parameters. **Do not retry** with the same input.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}}},"401":{"description":"Unauthorized - invalid Authorization format or API key","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}},"headers":{"WWW-Authenticate":{"description":"Authentication scheme for this endpoint","schema":{"type":"string","example":"Bearer"}}}},"402":{"description":"Payment Required - inactive plan or exhausted credits","content":{"application/json":{"schema":{"$defs":{"PaymentActionDetail":{"properties":{"message":{"description":"User-friendly explanation of why payment is required","title":"Message","type":"string"},"reason":{"description":"Machine-readable reason for the payment requirement","enum":["insufficient_credits","no_active_paid_plan"],"title":"Reason","type":"string"},"action_label":{"description":"Short label for the recommended action CTA","title":"Action Label","type":"string"},"action_url":{"description":"URL to take the recommended action (top-up or pricing)","title":"Action Url","type":"string"}},"required":["message","reason","action_label","action_url"],"title":"PaymentActionDetail","type":"object"}},"properties":{"detail":{"$ref":"#/components/schemas/PaymentActionDetail"}},"required":["detail"],"title":"PaymentRequiredResponse","type":"object"},"examples":{"topup":{"summary":"Active paid plan but credits exhausted","value":{"detail":{"message":"You have an active plan, but you've run out of credits.","reason":"insufficient_credits","action_label":"Top up credits","action_url":"https://transcriptapi.com/top-up"}}},"billing":{"summary":"No active paid plan","value":{"detail":{"message":"You don't have an active paid plan yet.","reason":"no_active_paid_plan","action_label":"Go to billing to choose a plan","action_url":"https://transcriptapi.com/billing"}}}}}}},"404":{"description":"**Not Found** - Channel does not exist. **Do not retry.**","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"not_found":{"summary":"Channel not found","value":{"detail":"Channel not found"}}}}}},"408":{"description":"**Request Timeout / Retry** - Temporary failure (bot detection, network issues). **Safe to retry** after a short delay (1-5 seconds).","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"retry":{"summary":"Temporary failure - retry recommended","value":{"detail":"Request failed, please retry"}}}}}},"429":{"description":"**Too Many Requests** - Rate limit exceeded. **Retry after** the delay in `Retry-After` header.","headers":{"Retry-After":{"description":"Seconds until the limit resets","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}}},"500":{"description":"**Internal Server Error** - Unexpected error. May retry, but if persistent, contact support.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"server_error":{"summary":"Unexpected server error","value":{"detail":"Internal server error"}}}}}},"503":{"description":"**Service Unavailable** - Service temporarily down or initializing. **Retry** after a short delay.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"unavailable":{"summary":"Service temporarily unavailable","value":{"detail":"Service not initialized"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v2/youtube/channel/search":{"get":{"tags":["YouTube channel"],"summary":"Search videos within a channel","description":"Search for videos within a specific channel.\n\nFirst page: pass `channel` (@handle, URL, or UC... ID) + `q`.\nSubsequent pages: pass `continuation` token from previous response (omit `channel`/`q`).\n\nReturns YouTube's full page (~30 items) per call.\n\n**Pagination:** The response includes `continuation_token` (when `has_more=true`).\n\n**Credit cost:** 1 credit per page.","operationId":"channel_search_api_v2_youtube_channel_search_get","security":[{"bearerAuth":[]}],"parameters":[{"name":"channel","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Channel identifier: @handle, channel URL, or UC... channel ID","title":"Channel"},"description":"Channel identifier: @handle, channel URL, or UC... channel ID"},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}],"description":"Search query (required for first page)","title":"Q"},"description":"Search query (required for first page)"},{"name":"continuation","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"Continuation token from previous page. When provided, channel/q are ignored.","title":"Continuation"},"description":"Continuation token from previous page. When provided, channel/q are ignored."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelSearchResponse"}}}},"400":{"description":"**Bad Request** - Invalid parameter combination. Provide either (`channel` + `q`) or `continuation`, not both.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"missing":{"summary":"No parameter provided","value":{"detail":"Either 'channel'+'q' or 'continuation' is required"}},"both":{"summary":"Both parameters provided","value":{"detail":"Provide either 'channel'+'q' or 'continuation', not both"}}}}}},"401":{"description":"Unauthorized - invalid Authorization format or API key","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}},"headers":{"WWW-Authenticate":{"description":"Authentication scheme for this endpoint","schema":{"type":"string","example":"Bearer"}}}},"402":{"description":"Payment Required - inactive plan or exhausted credits","content":{"application/json":{"schema":{"$defs":{"PaymentActionDetail":{"properties":{"message":{"description":"User-friendly explanation of why payment is required","title":"Message","type":"string"},"reason":{"description":"Machine-readable reason for the payment requirement","enum":["insufficient_credits","no_active_paid_plan"],"title":"Reason","type":"string"},"action_label":{"description":"Short label for the recommended action CTA","title":"Action Label","type":"string"},"action_url":{"description":"URL to take the recommended action (top-up or pricing)","title":"Action Url","type":"string"}},"required":["message","reason","action_label","action_url"],"title":"PaymentActionDetail","type":"object"}},"properties":{"detail":{"$ref":"#/components/schemas/PaymentActionDetail"}},"required":["detail"],"title":"PaymentRequiredResponse","type":"object"},"examples":{"topup":{"summary":"Active paid plan but credits exhausted","value":{"detail":{"message":"You have an active plan, but you've run out of credits.","reason":"insufficient_credits","action_label":"Top up credits","action_url":"https://transcriptapi.com/top-up"}}},"billing":{"summary":"No active paid plan","value":{"detail":{"message":"You don't have an active paid plan yet.","reason":"no_active_paid_plan","action_label":"Go to billing to choose a plan","action_url":"https://transcriptapi.com/billing"}}}}}}},"404":{"description":"**Not Found** - Channel does not exist. **Do not retry.**","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"not_found":{"summary":"Channel not found","value":{"detail":"Channel not found"}}}}}},"408":{"description":"**Request Timeout / Retry** - Temporary failure (bot detection, network issues). **Safe to retry** after a short delay (1-5 seconds).","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"retry":{"summary":"Temporary failure - retry recommended","value":{"detail":"Request failed, please retry"}}}}}},"429":{"description":"**Too Many Requests** - Rate limit exceeded. **Retry after** the delay in `Retry-After` header.","headers":{"Retry-After":{"description":"Seconds until the limit resets","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}}},"500":{"description":"**Internal Server Error** - Unexpected error. May retry, but if persistent, contact support.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"server_error":{"summary":"Unexpected server error","value":{"detail":"Internal server error"}}}}}},"503":{"description":"**Service Unavailable** - Service temporarily down or initializing. **Retry** after a short delay.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"unavailable":{"summary":"Service temporarily unavailable","value":{"detail":"Service not initialized"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v2/youtube/channel/videos":{"get":{"tags":["YouTube channel"],"summary":"Paginated channel uploads","description":"List a channel's videos (paginated). `tab=videos` (default) is the uploads feed (~100/page); `tab=shorts` and `tab=streams` (live) return those feeds (~48/page). \n\nFirst request: provide `channel` (@handle, URL, or UC... ID). Subsequent requests: provide `continuation` token from previous response (and repeat the same `tab` and `sort`).\n\n### Sorting — `sort=latest|popular|oldest`\n\n`sort` is **opt-in**, and omitting it is *not* the same as `sort=latest`: the two read different YouTube feeds.\n\n| | `tab=videos`, no `sort` | `tab=videos` + any `sort` |\n|---|---|---|\n| source | uploads playlist | channel Videos tab |\n| page size | ~100 | ~30 |\n| `playlist_info` | populated | `null` |\n| Shorts | **mixed in** | excluded (use `tab=shorts`) |\n| members-only videos | excluded | included, flagged `members_only: true` |\n\nSo the two feeds are different *sets*, not one list in two orders: the uploads playlist interleaves Shorts with long-form uploads, while the Videos tab holds long-form only and adds membership content. Paging a full catalogue with `sort` set therefore costs ~3.3x the pages (and ~3.3x the credits) of the unsorted feed — omit `sort` when you just want newest-first. `tab=shorts` / `tab=streams` read the same feed either way; `sort` only reorders them.\n\n```\n?channel=@NASA                                 # uploads feed, newest first, ~100/page\n?channel=@NASA&sort=popular                    # Videos tab, most-viewed first, ~30/page\n?channel=@NASA&tab=streams&sort=oldest         # oldest live streams first\n?continuation=<token>&tab=streams&sort=oldest  # page 2 - repeat tab AND sort\n```\n\n**Credit cost:** 1 credit per page.","operationId":"channel_videos_api_v2_youtube_channel_videos_get","security":[{"bearerAuth":[]}],"parameters":[{"name":"channel","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Channel identifier: @handle, channel URL, or UC... channel ID","title":"Channel"},"description":"Channel identifier: @handle, channel URL, or UC... channel ID","examples":{"handle":{"summary":"By @handle","description":"Look up a channel's uploads by its public handle.","value":"@NASA"}}},{"name":"tab","in":"query","required":false,"schema":{"type":"string","pattern":"^(videos|shorts|streams)$","description":"Which feed: videos (default, uploads), shorts, or streams (live). Pass the same `tab` when paginating shorts/streams.","default":"videos","title":"Tab"},"description":"Which feed: videos (default, uploads), shorts, or streams (live). Pass the same `tab` when paginating shorts/streams.","examples":{"videos":{"summary":"Uploads (default)","value":"videos"},"shorts":{"summary":"Shorts feed","description":"List the channel's Shorts instead of long-form uploads.","value":"shorts"},"streams":{"summary":"Live streams","value":"streams"}}},{"name":"sort","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(latest|popular|oldest)$"},{"type":"null"}],"description":"Sort order. **Omit it** to keep the current uploads feed (~100/page, Shorts mixed in, members-only videos excluded). Any explicit value switches `tab=videos` to YouTube's channel-tab feed (~30/page, long-form only, members-only videos included and flagged with `members_only`), so omitting `sort` is not the same as `sort=latest`. Repeat the same value when paginating.","title":"Sort"},"description":"Sort order. **Omit it** to keep the current uploads feed (~100/page, Shorts mixed in, members-only videos excluded). Any explicit value switches `tab=videos` to YouTube's channel-tab feed (~30/page, long-form only, members-only videos included and flagged with `members_only`), so omitting `sort` is not the same as `sort=latest`. Repeat the same value when paginating.","examples":{"omitted":{"summary":"Omitted (default)","description":"Newest-first uploads feed, ~100/page, Shorts mixed in, no members-only videos. The cheapest way to page a whole catalogue."},"popular":{"summary":"Most viewed first","description":"Channel-tab feed ordered by view count, ~30/page.","value":"popular"},"oldest":{"summary":"Oldest first","description":"Channel-tab feed in ascending publish order, ~30/page.","value":"oldest"},"latest":{"summary":"Newest first (channel-tab feed)","description":"Same ordering as omitting `sort`, but read from the channel-tab feed - ~30/page, `playlist_info: null`, Shorts excluded, members-only included.","value":"latest"}}},{"name":"continuation","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"Continuation token from previous page","title":"Continuation"},"description":"Continuation token from previous page","examples":{"next_page":{"summary":"Fetch the next page","description":"Opaque token copied verbatim from the previous response's `continuation` field. Omit `channel`/`channel_id` when paging.","value":"<continuation-token-from-previous-response>"}}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelVideosResponse"}}}},"400":{"description":"**Bad Request** - Invalid parameter combination. Provide either `channel` or `continuation`, not both.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"missing":{"summary":"No parameter provided","value":{"detail":"Either 'channel' or 'continuation' is required"}},"both":{"summary":"Both parameters provided","value":{"detail":"Provide either 'channel'/'channel_id' or 'continuation', not both"}}}}}},"401":{"description":"Unauthorized - invalid Authorization format or API key","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}},"headers":{"WWW-Authenticate":{"description":"Authentication scheme for this endpoint","schema":{"type":"string","example":"Bearer"}}}},"402":{"description":"Payment Required - inactive plan or exhausted credits","content":{"application/json":{"schema":{"$defs":{"PaymentActionDetail":{"properties":{"message":{"description":"User-friendly explanation of why payment is required","title":"Message","type":"string"},"reason":{"description":"Machine-readable reason for the payment requirement","enum":["insufficient_credits","no_active_paid_plan"],"title":"Reason","type":"string"},"action_label":{"description":"Short label for the recommended action CTA","title":"Action Label","type":"string"},"action_url":{"description":"URL to take the recommended action (top-up or pricing)","title":"Action Url","type":"string"}},"required":["message","reason","action_label","action_url"],"title":"PaymentActionDetail","type":"object"}},"properties":{"detail":{"$ref":"#/components/schemas/PaymentActionDetail"}},"required":["detail"],"title":"PaymentRequiredResponse","type":"object"},"examples":{"topup":{"summary":"Active paid plan but credits exhausted","value":{"detail":{"message":"You have an active plan, but you've run out of credits.","reason":"insufficient_credits","action_label":"Top up credits","action_url":"https://transcriptapi.com/top-up"}}},"billing":{"summary":"No active paid plan","value":{"detail":{"message":"You don't have an active paid plan yet.","reason":"no_active_paid_plan","action_label":"Go to billing to choose a plan","action_url":"https://transcriptapi.com/billing"}}}}}}},"404":{"description":"**Not Found** - Channel does not exist. **Do not retry.**","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"not_found":{"summary":"Channel not found","value":{"detail":"Channel not found"}}}}}},"408":{"description":"**Request Timeout / Retry** - Temporary failure (bot detection, network issues). **Safe to retry** after a short delay (1-5 seconds).","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"retry":{"summary":"Temporary failure - retry recommended","value":{"detail":"Request failed, please retry"}}}}}},"429":{"description":"**Too Many Requests** - Rate limit exceeded. **Retry after** the delay in `Retry-After` header.","headers":{"Retry-After":{"description":"Seconds until the limit resets","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}}},"500":{"description":"**Internal Server Error** - Unexpected error. May retry, but if persistent, contact support.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"server_error":{"summary":"Unexpected server error","value":{"detail":"Internal server error"}}}}}},"503":{"description":"**Service Unavailable** - Service temporarily down or initializing. **Retry** after a short delay.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"unavailable":{"summary":"Service temporarily unavailable","value":{"detail":"Service not initialized"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v2/youtube/channel/latest":{"get":{"tags":["YouTube channel"],"summary":"Latest 15 videos via RSS","description":"Get the latest 15 videos from a channel via YouTube RSS feed.\n\nUse the `channel` parameter with an @handle, channel URL, or UC... channel ID.\n\nReturns exact publish timestamps and view counts.\n\nWhen YouTube's feed is unavailable, the list comes from the channel's uploads instead (`X-Data-Source: browse`): `published` is then approximate (from \"9 hours ago\"; `X-Published-Approximate: true`), `viewCount` is set only when YouTube shows the exact number, and `updated`, `description` and `starRating` are null. If that also fails, the last good list (up to 7 days old) is returned with `X-Cache-Status: STALE`.\n\n**Credit cost:** FREE (requires auth + at least 1 active credit, but does not charge).","operationId":"channel_latest_api_v2_youtube_channel_latest_get","security":[{"bearerAuth":[]}],"parameters":[{"name":"channel","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Channel identifier: @handle, channel URL, or UC... channel ID","title":"Channel"},"description":"Channel identifier: @handle, channel URL, or UC... channel ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelLatestResponse"}}},"headers":{"X-Cache-Status":{"description":"HIT, MISS, or STALE (last good list, served while YouTube is unavailable)","schema":{"type":"string"}},"X-Data-Source":{"description":"rss (YouTube feed) or browse (channel uploads, used when the feed is unavailable)","schema":{"type":"string"}},"X-Published-Approximate":{"description":"Present and `true` when `published` is approximated from relative times","schema":{"type":"string"}}}},"401":{"description":"Unauthorized - invalid Authorization format or API key","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}},"headers":{"WWW-Authenticate":{"description":"Authentication scheme for this endpoint","schema":{"type":"string","example":"Bearer"}}}},"402":{"description":"Payment Required - inactive plan or exhausted credits","content":{"application/json":{"schema":{"$defs":{"PaymentActionDetail":{"properties":{"message":{"description":"User-friendly explanation of why payment is required","title":"Message","type":"string"},"reason":{"description":"Machine-readable reason for the payment requirement","enum":["insufficient_credits","no_active_paid_plan"],"title":"Reason","type":"string"},"action_label":{"description":"Short label for the recommended action CTA","title":"Action Label","type":"string"},"action_url":{"description":"URL to take the recommended action (top-up or pricing)","title":"Action Url","type":"string"}},"required":["message","reason","action_label","action_url"],"title":"PaymentActionDetail","type":"object"}},"properties":{"detail":{"$ref":"#/components/schemas/PaymentActionDetail"}},"required":["detail"],"title":"PaymentRequiredResponse","type":"object"},"examples":{"topup":{"summary":"Active paid plan but credits exhausted","value":{"detail":{"message":"You have an active plan, but you've run out of credits.","reason":"insufficient_credits","action_label":"Top up credits","action_url":"https://transcriptapi.com/top-up"}}},"billing":{"summary":"No active paid plan","value":{"detail":{"message":"You don't have an active paid plan yet.","reason":"no_active_paid_plan","action_label":"Go to billing to choose a plan","action_url":"https://transcriptapi.com/billing"}}}}}}},"404":{"description":"**Not Found** - Channel does not exist. **Do not retry.**","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"not_found":{"summary":"Channel not found","value":{"detail":"Channel not found"}}}}}},"408":{"description":"**Request Timeout / Retry** - Temporary failure (bot detection, network issues). **Safe to retry** after a short delay (1-5 seconds).","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"retry":{"summary":"Temporary failure - retry recommended","value":{"detail":"Request failed, please retry"}}}}}},"429":{"description":"**Too Many Requests** - Rate limit exceeded. **Retry after** the delay in `Retry-After` header.","headers":{"Retry-After":{"description":"Seconds until the limit resets","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}}},"500":{"description":"**Internal Server Error** - Unexpected error. May retry, but if persistent, contact support.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"server_error":{"summary":"Unexpected server error","value":{"detail":"Internal server error"}}}}}},"503":{"description":"**Service Unavailable** - Service temporarily down or initializing. **Retry** after a short delay.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"unavailable":{"summary":"Service temporarily unavailable","value":{"detail":"Service not initialized"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v2/youtube/playlist/videos":{"get":{"tags":["YouTube playlist"],"summary":"Paginated playlist videos","description":"List videos in a playlist (paginated, ~100 per page).\n\nFirst request: provide `playlist` (YouTube playlist URL or playlist ID). Subsequent requests: provide `continuation` token.\n\n**Credit cost:** 1 credit per page.","operationId":"playlist_videos_api_v2_youtube_playlist_videos_get","security":[{"bearerAuth":[]}],"parameters":[{"name":"playlist","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Playlist identifier: YouTube playlist URL or playlist ID (PL..., UU..., etc.)","title":"Playlist"},"description":"Playlist identifier: YouTube playlist URL or playlist ID (PL..., UU..., etc.)","examples":{"playlist_id":{"summary":"By playlist ID","value":"PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI"}}},{"name":"continuation","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"Continuation token from previous page","title":"Continuation"},"description":"Continuation token from previous page","examples":{"next_page":{"summary":"Fetch the next page","description":"Opaque token copied verbatim from the previous response's `continuation` field.","value":"<continuation-token-from-previous-response>"}}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaylistVideosResponse"}}}},"400":{"description":"**Bad Request** - Invalid parameter combination. Provide either `playlist` or `continuation`, not both.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"missing":{"summary":"No parameter provided","value":{"detail":"Either 'playlist' or 'continuation' is required"}},"both":{"summary":"Both parameters provided","value":{"detail":"Provide either 'playlist'/'playlist_id' or 'continuation', not both"}}}}}},"401":{"description":"Unauthorized - invalid Authorization format or API key","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}},"headers":{"WWW-Authenticate":{"description":"Authentication scheme for this endpoint","schema":{"type":"string","example":"Bearer"}}}},"402":{"description":"Payment Required - inactive plan or exhausted credits","content":{"application/json":{"schema":{"$defs":{"PaymentActionDetail":{"properties":{"message":{"description":"User-friendly explanation of why payment is required","title":"Message","type":"string"},"reason":{"description":"Machine-readable reason for the payment requirement","enum":["insufficient_credits","no_active_paid_plan"],"title":"Reason","type":"string"},"action_label":{"description":"Short label for the recommended action CTA","title":"Action Label","type":"string"},"action_url":{"description":"URL to take the recommended action (top-up or pricing)","title":"Action Url","type":"string"}},"required":["message","reason","action_label","action_url"],"title":"PaymentActionDetail","type":"object"}},"properties":{"detail":{"$ref":"#/components/schemas/PaymentActionDetail"}},"required":["detail"],"title":"PaymentRequiredResponse","type":"object"},"examples":{"topup":{"summary":"Active paid plan but credits exhausted","value":{"detail":{"message":"You have an active plan, but you've run out of credits.","reason":"insufficient_credits","action_label":"Top up credits","action_url":"https://transcriptapi.com/top-up"}}},"billing":{"summary":"No active paid plan","value":{"detail":{"message":"You don't have an active paid plan yet.","reason":"no_active_paid_plan","action_label":"Go to billing to choose a plan","action_url":"https://transcriptapi.com/billing"}}}}}}},"404":{"description":"**Not Found** - Playlist does not exist. **Do not retry.**","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"not_found":{"summary":"Playlist not found","value":{"detail":"Playlist not found"}}}}}},"408":{"description":"**Request Timeout / Retry** - Temporary failure (bot detection, network issues). **Safe to retry** after a short delay (1-5 seconds).","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"retry":{"summary":"Temporary failure - retry recommended","value":{"detail":"Request failed, please retry"}}}}}},"422":{"description":"**Validation Error** - Invalid playlist identifier. Must be a playlist URL or ID starting with `PL`, `UU`, `LL`, `FL`, or `OL`. **Do not retry** with the same input.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"invalid_playlist_id":{"summary":"Invalid playlist identifier","value":{"detail":"Invalid playlist identifier"}}}}}},"429":{"description":"**Too Many Requests** - Rate limit exceeded. **Retry after** the delay in `Retry-After` header.","headers":{"Retry-After":{"description":"Seconds until the limit resets","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}}},"500":{"description":"**Internal Server Error** - Unexpected error. May retry, but if persistent, contact support.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"server_error":{"summary":"Unexpected server error","value":{"detail":"Internal server error"}}}}}},"503":{"description":"**Service Unavailable** - Service temporarily down or initializing. **Retry** after a short delay.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"unavailable":{"summary":"Service temporarily unavailable","value":{"detail":"Service not initialized"}}}}}}}}},"/api/v2/youtube/video/metadata":{"get":{"tags":["YouTube video"],"summary":"Video metadata (no captions required)","description":"Inspect a video's metadata without needing captions: title, view/like count text, publish date, structured description + links, uploading-channel summary, and thumbnails.\n\n**Optional `include`** (comma-separated) adds heavier data:\n- `related` — related videos.\n- `details` — duration, category, tags, official thumbnails, caption-track inventory and availability flags. These come from YouTube's player endpoint, which requires our proxied (production) path; where unavailable, `details.available` is `false` with a `reason` rather than guessed values.\n\nDisplay strings and numbers are kept distinct; hidden counts are `null`, never `0`.\n\n**Freshness:** cached for 5 minutes.\n\n**Credit cost:** 1 credit per request.","operationId":"get_video_metadata_api_v2_youtube_video_metadata_get","security":[{"bearerAuth":[]}],"parameters":[{"name":"video_url","in":"query","required":true,"schema":{"type":"string","description":"YouTube video URL or 11-character video ID","title":"Video Url"},"description":"YouTube video URL or 11-character video ID"},{"name":"include","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated extras: details, related","title":"Include"},"description":"Comma-separated extras: details, related","examples":{"details_and_related":{"summary":"Full detail, plus related videos","description":"Adds duration/category/tags/caption inventory and a related-videos list.","value":"details,related"},"related_only":{"summary":"Related videos only","value":"related"}}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/app__api__v2__youtube__schemas_youtube__VideoInfoResponse"}}}},"400":{"description":"**Bad Request** - Missing or invalid parameters. **Do not retry** with the same input.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}}},"401":{"description":"Unauthorized - invalid Authorization format or API key","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}},"headers":{"WWW-Authenticate":{"description":"Authentication scheme for this endpoint","schema":{"type":"string","example":"Bearer"}}}},"402":{"description":"Payment Required - inactive plan or exhausted credits","content":{"application/json":{"schema":{"$defs":{"PaymentActionDetail":{"properties":{"message":{"description":"User-friendly explanation of why payment is required","title":"Message","type":"string"},"reason":{"description":"Machine-readable reason for the payment requirement","enum":["insufficient_credits","no_active_paid_plan"],"title":"Reason","type":"string"},"action_label":{"description":"Short label for the recommended action CTA","title":"Action Label","type":"string"},"action_url":{"description":"URL to take the recommended action (top-up or pricing)","title":"Action Url","type":"string"}},"required":["message","reason","action_label","action_url"],"title":"PaymentActionDetail","type":"object"}},"properties":{"detail":{"$ref":"#/components/schemas/PaymentActionDetail"}},"required":["detail"],"title":"PaymentRequiredResponse","type":"object"},"examples":{"topup":{"summary":"Active paid plan but credits exhausted","value":{"detail":{"message":"You have an active plan, but you've run out of credits.","reason":"insufficient_credits","action_label":"Top up credits","action_url":"https://transcriptapi.com/top-up"}}},"billing":{"summary":"No active paid plan","value":{"detail":{"message":"You don't have an active paid plan yet.","reason":"no_active_paid_plan","action_label":"Go to billing to choose a plan","action_url":"https://transcriptapi.com/billing"}}}}}}},"404":{"description":"**Not Found** - The requested resource does not exist. **Do not retry.**","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}}},"408":{"description":"**Request Timeout / Retry** - Temporary failure (bot detection, network issues). **Safe to retry** after a short delay (1-5 seconds).","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"retry":{"summary":"Temporary failure - retry recommended","value":{"detail":"Request failed, please retry"}}}}}},"422":{"description":"**Unprocessable** - `video_url` is not a valid YouTube video URL or ID.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"bad_id":{"summary":"Invalid video reference","value":{"detail":"Invalid video URL or ID"}}}}}},"429":{"description":"**Too Many Requests** - Rate limit exceeded. **Retry after** the delay in `Retry-After` header.","headers":{"Retry-After":{"description":"Seconds until the limit resets","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"}}}},"500":{"description":"**Internal Server Error** - Unexpected error. May retry, but if persistent, contact support.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"server_error":{"summary":"Unexpected server error","value":{"detail":"Internal server error"}}}}}},"503":{"description":"**Service Unavailable** - Service temporarily down or initializing. **Retry** after a short delay.","content":{"application/json":{"schema":{"properties":{"detail":{"description":"Human-readable error message","title":"Detail","type":"string"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional machine-readable error code","title":"Code"}},"required":["detail"],"title":"ErrorResponse","type":"object"},"examples":{"unavailable":{"summary":"Service temporarily unavailable","value":{"detail":"Service not initialized"}}}}}}}}}},"components":{"schemas":{"APITranscriptResponseV2":{"properties":{"video_id":{"type":"string","title":"Video Id","description":"YouTube video ID"},"language":{"type":"string","title":"Language","description":"Language of the returned transcript"},"transcript":{"anyOf":[{"items":{"$ref":"#/components/schemas/TranscriptSegment"},"type":"array"},{"items":{"$ref":"#/components/schemas/TranscriptSegmentTextOnly"},"type":"array"},{"type":"string"}],"title":"Transcript"},"metadata":{"anyOf":[{"$ref":"#/components/schemas/app__api__v2__youtube__schemas__Metadata"},{"type":"null"}]},"length_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Length Seconds","description":"Total video length in whole seconds (e.g. 213). null when the source doesn't expose a fixed length — live streams and the rare fallback extraction path."},"lengthText":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lengthtext","description":"Total video length as a human-readable string, e.g. '3:33' or '1:02:45'. null in the same cases as length_seconds. Matches the lengthText format used by the search/channel/playlist endpoints."}},"type":"object","required":["video_id","language","transcript"],"title":"APITranscriptResponseV2","description":"Public API response for v2 with a simplified contract.\n\n- When format=json, `transcript` is a list of segments (with or without timestamps).\n- When format=text, `transcript` is a plain string (with or without timestamps).\n- `metadata` is returned only when requested via send_metadata=true.\n- `length_seconds` / `lengthText` give the total video length; they are\n  `null` when the source doesn't expose a fixed length (e.g. live streams)."},"AvailableLanguage":{"properties":{"code":{"type":"string","title":"Code","description":"Normalized language code, or 'asr' for auto-generated"},"name":{"type":"string","title":"Name","description":"Human-readable language name"},"kind":{"anyOf":[{"type":"string","enum":["manual","auto"]},{"type":"null"}],"title":"Kind","description":"What this code returns: 'manual' = human-made captions, 'auto' = YouTube's auto-generated captions. A plain code (e.g. `ru`) returns the manual track when one exists, otherwise the auto track, so it can be 'auto' too; `asr-<code>` is always 'auto'."}},"type":"object","required":["code","name"],"title":"AvailableLanguage","description":"A language available for a video (PRD §5.2).\n\n`code` is a normalized base code (`en`, `de`, `zh`) or the reserved `asr`\npseudo-code for auto-generated captions."},"ChannelInfoResponse":{"properties":{"channelId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channelid"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"handle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Handle"},"verified":{"type":"boolean","title":"Verified","default":false},"subscriberCountText":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscribercounttext"},"videoCountText":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Videocounttext"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"keywords":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Keywords"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags"},"isFamilySafe":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Isfamilysafe"},"thumbnails":{"items":{"$ref":"#/components/schemas/Thumbnail"},"type":"array","title":"Thumbnails"},"banners":{"items":{"$ref":"#/components/schemas/Thumbnail"},"type":"array","title":"Banners"},"availableTabs":{"items":{"type":"string"},"type":"array","title":"Availabletabs"}},"type":"object","title":"ChannelInfoResponse","description":"Channel profile/identity from the Innertube browse endpoint.\n\nFormatted count strings (`subscriberCountText`, `videoCountText`) are display\nstrings, not exact numbers, and are `None` when YouTube does not expose them —\nnever coerced to 0. About-tab fields YouTube does not serve over an\nunauthenticated browse (join date, total views, country, external links) are\nintentionally omitted rather than guessed."},"ChannelLatestResponse":{"properties":{"channel":{"anyOf":[{"$ref":"#/components/schemas/RssChannelInfo"},{"type":"null"}]},"results":{"items":{"$ref":"#/components/schemas/RssVideoResult"},"type":"array","title":"Results"},"result_count":{"type":"integer","title":"Result Count","default":0}},"type":"object","title":"ChannelLatestResponse"},"ChannelPlaylistSummary":{"properties":{"playlistId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Playlistid"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"videoCountText":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Videocounttext"},"thumbnails":{"items":{"$ref":"#/components/schemas/Thumbnail"},"type":"array","title":"Thumbnails"}},"type":"object","title":"ChannelPlaylistSummary"},"ChannelPlaylistsResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/ChannelPlaylistSummary"},"type":"array","title":"Results"},"result_count":{"type":"integer","title":"Result Count","default":0},"continuation_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Continuation Token"},"has_more":{"type":"boolean","title":"Has More","default":false}},"type":"object","title":"ChannelPlaylistsResponse"},"ChannelPost":{"properties":{"postId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Postid"},"authorName":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorname"},"authorThumbnails":{"items":{"$ref":"#/components/schemas/Thumbnail"},"type":"array","title":"Authorthumbnails"},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text"},"publishedTimeText":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Publishedtimetext"},"voteCountText":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Votecounttext"},"attachment":{"anyOf":[{"$ref":"#/components/schemas/ChannelPostAttachment"},{"type":"null"}]}},"type":"object","title":"ChannelPost"},"ChannelPostAttachment":{"properties":{"type":{"type":"string","title":"Type"},"thumbnails":{"anyOf":[{"items":{"$ref":"#/components/schemas/Thumbnail"},"type":"array"},{"type":"null"}],"title":"Thumbnails"},"images":{"anyOf":[{"items":{"items":{"$ref":"#/components/schemas/Thumbnail"},"type":"array"},"type":"array"},{"type":"null"}],"title":"Images"},"videoId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Videoid"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"lengthText":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lengthtext"},"playlistId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Playlistid"},"videoCountText":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Videocounttext"},"totalVotesText":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Totalvotestext"},"choices":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Choices"}},"type":"object","required":["type"],"title":"ChannelPostAttachment","description":"Polymorphic post attachment. `type` is one of: image, multi_image, video,\nplaylist, poll (or the raw renderer name for anything not yet modelled).\nOnly the fields relevant to `type` are populated; the rest are omitted."},"ChannelPostsResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/ChannelPost"},"type":"array","title":"Results"},"result_count":{"type":"integer","title":"Result Count","default":0},"continuation_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Continuation Token"},"has_more":{"type":"boolean","title":"Has More","default":false}},"type":"object","title":"ChannelPostsResponse"},"ChannelResolveResponse":{"properties":{"channel_id":{"type":"string","title":"Channel Id"},"resolved_from":{"type":"string","title":"Resolved From"}},"type":"object","required":["channel_id","resolved_from"],"title":"ChannelResolveResponse"},"ChannelResult":{"properties":{"type":{"type":"string","const":"channel","title":"Type","default":"channel"},"channelId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channelid"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"handle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Handle"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"subscriberCount":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscribercount"},"verified":{"type":"boolean","title":"Verified","default":false},"rssUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rssurl"},"thumbnails":{"items":{"$ref":"#/components/schemas/Thumbnail"},"type":"array","title":"Thumbnails"}},"type":"object","title":"ChannelResult"},"ChannelSearchResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/VideoResult"},"type":"array","title":"Results"},"result_count":{"type":"integer","title":"Result Count","default":0},"continuation_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Continuation Token"},"has_more":{"type":"boolean","title":"Has More","default":false}},"type":"object","title":"ChannelSearchResponse"},"ChannelSection":{"properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"type":{"type":"string","title":"Type"},"items":{"items":{"$ref":"#/components/schemas/ChannelSectionItem"},"type":"array","title":"Items"}},"type":"object","required":["type"],"title":"ChannelSection"},"ChannelSectionItem":{"properties":{"kind":{"type":"string","title":"Kind"},"videoId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Videoid"},"playlistId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Playlistid"},"channelId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channelid"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"viewCountText":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Viewcounttext"},"videoCountText":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Videocounttext"},"subscriberText":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscribertext"},"thumbnails":{"items":{"$ref":"#/components/schemas/Thumbnail"},"type":"array","title":"Thumbnails"}},"type":"object","required":["kind"],"title":"ChannelSectionItem","description":"One item inside a section. `kind` is video | playlist | short | channel.\nOnly fields relevant to the kind are populated."},"ChannelSectionsResponse":{"properties":{"tab":{"type":"string","title":"Tab"},"results":{"items":{"$ref":"#/components/schemas/ChannelSection"},"type":"array","title":"Results"},"result_count":{"type":"integer","title":"Result Count","default":0}},"type":"object","required":["tab"],"title":"ChannelSectionsResponse"},"ChannelVideosResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/PlaylistVideoResult"},"type":"array","title":"Results"},"playlist_info":{"anyOf":[{"$ref":"#/components/schemas/PlaylistInfo"},{"type":"null"}]},"continuation_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Continuation Token"},"has_more":{"type":"boolean","title":"Has More","default":false}},"type":"object","title":"ChannelVideosResponse"},"DescriptionLink":{"properties":{"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"}},"type":"object","title":"DescriptionLink"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"PlaylistInfo":{"properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"numVideos":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numvideos"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"ownerName":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ownername"},"viewCount":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Viewcount"}},"type":"object","title":"PlaylistInfo"},"PlaylistVideoResult":{"properties":{"videoId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Videoid"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"channelId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channelid"},"channelTitle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channeltitle"},"channelHandle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channelhandle"},"lengthText":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lengthtext"},"viewCountText":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Viewcounttext"},"publishedTimeText":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Publishedtimetext"},"thumbnails":{"items":{"$ref":"#/components/schemas/Thumbnail"},"type":"array","title":"Thumbnails"},"index":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Index"},"members_only":{"type":"boolean","title":"Members Only","description":"Video is behind a channel membership (YouTube's \"Members only\" badge). Always `false` on the uploads feed and on playlists, which never include membership content. Members-only items have no `viewCountText` — YouTube does not publish view counts for them.","default":false}},"type":"object","title":"PlaylistVideoResult"},"PlaylistVideosResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/PlaylistVideoResult"},"type":"array","title":"Results"},"playlist_info":{"anyOf":[{"$ref":"#/components/schemas/PlaylistInfo"},{"type":"null"}]},"continuation_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Continuation Token"},"has_more":{"type":"boolean","title":"Has More","default":false}},"type":"object","title":"PlaylistVideosResponse"},"RelatedVideo":{"properties":{"kind":{"type":"string","title":"Kind"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"viewCountText":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Viewcounttext"},"lengthText":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lengthtext"},"channelName":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channelname"}},"type":"object","required":["kind"],"title":"RelatedVideo"},"RssChannelInfo":{"properties":{"channelId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channelid"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"published":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Published"}},"type":"object","title":"RssChannelInfo"},"RssStarRating":{"properties":{"average":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Average"},"count":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Count"},"min":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Min"},"max":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Max"}},"type":"object","title":"RssStarRating"},"RssThumbnail":{"properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"width":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Width"},"height":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Height"}},"type":"object","title":"RssThumbnail"},"RssVideoResult":{"properties":{"videoId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Videoid"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"channelId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channelid"},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author"},"published":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Published"},"updated":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated"},"link":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Link"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"thumbnail":{"anyOf":[{"$ref":"#/components/schemas/RssThumbnail"},{"type":"null"}]},"viewCount":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Viewcount"},"starRating":{"anyOf":[{"$ref":"#/components/schemas/RssStarRating"},{"type":"null"}]}},"type":"object","title":"RssVideoResult"},"SearchPlaylistResult":{"properties":{"type":{"type":"string","const":"playlist","title":"Type","default":"playlist"},"playlistId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Playlistid"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"videoCountText":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Videocounttext"},"thumbnails":{"items":{"$ref":"#/components/schemas/Thumbnail"},"type":"array","title":"Thumbnails"}},"type":"object","title":"SearchPlaylistResult"},"SearchResponse":{"properties":{"results":{"items":{"oneOf":[{"$ref":"#/components/schemas/VideoResult"},{"$ref":"#/components/schemas/ChannelResult"},{"$ref":"#/components/schemas/SearchPlaylistResult"}],"discriminator":{"propertyName":"type","mapping":{"channel":"#/components/schemas/ChannelResult","playlist":"#/components/schemas/SearchPlaylistResult","video":"#/components/schemas/VideoResult"}}},"type":"array","title":"Results"},"result_count":{"type":"integer","title":"Result Count","default":0},"continuation_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Continuation Token"},"has_more":{"type":"boolean","title":"Has More","default":false}},"type":"object","title":"SearchResponse"},"SearchType":{"type":"string","enum":["video","channel","playlist","movie"],"title":"SearchType"},"Thumbnail":{"properties":{"url":{"type":"string","title":"Url"},"width":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Width"},"height":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Height"}},"type":"object","required":["url"],"title":"Thumbnail"},"TranscriptFormatV2":{"type":"string","enum":["json","text"],"title":"TranscriptFormatV2","description":"Available transcript formats for v2 (restricted)."},"TranscriptSegment":{"properties":{"text":{"type":"string","title":"Text"},"start":{"type":"number","title":"Start"},"duration":{"type":"number","title":"Duration"}},"type":"object","required":["text","start","duration"],"title":"TranscriptSegment"},"TranscriptSegmentTextOnly":{"properties":{"text":{"type":"string","title":"Text"}},"type":"object","required":["text"],"title":"TranscriptSegmentTextOnly","description":"Transcript segment without timestamp information."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VideoCaptionTrack":{"properties":{"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"isAutoGenerated":{"type":"boolean","title":"Isautogenerated","default":false}},"type":"object","title":"VideoCaptionTrack"},"VideoInfoChannel":{"properties":{"channelId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channelid"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"subscriberCountText":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscribercounttext"},"thumbnails":{"items":{"$ref":"#/components/schemas/Thumbnail"},"type":"array","title":"Thumbnails"}},"type":"object","title":"VideoInfoChannel"},"VideoInfoDetails":{"properties":{"available":{"type":"boolean","title":"Available","default":false},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"},"lengthSeconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Lengthseconds"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags"},"isLiveContent":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Islivecontent"},"isFamilySafe":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Isfamilysafe"},"isUnlisted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Isunlisted"},"allowRatings":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Allowratings"},"thumbnails":{"items":{"$ref":"#/components/schemas/Thumbnail"},"type":"array","title":"Thumbnails"},"captionTracks":{"items":{"$ref":"#/components/schemas/VideoCaptionTrack"},"type":"array","title":"Captiontracks"}},"type":"object","title":"VideoInfoDetails","description":"Player-sourced details. `available` is False (with `reason`) when the\nplayer endpoint could not be read from the current IP (needs a residential\nproxy — production). Numeric-vs-display values are kept distinct."},"VideoResult":{"properties":{"type":{"type":"string","const":"video","title":"Type","default":"video"},"videoId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Videoid"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"channelId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channelid"},"channelTitle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channeltitle"},"channelHandle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channelhandle"},"channelVerified":{"type":"boolean","title":"Channelverified","default":false},"lengthText":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lengthtext"},"viewCountText":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Viewcounttext"},"publishedTimeText":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Publishedtimetext"},"hasCaptions":{"type":"boolean","title":"Hascaptions","default":false},"descriptionSnippet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Descriptionsnippet"},"isLive":{"type":"boolean","title":"Islive","default":false},"is4k":{"type":"boolean","title":"Is4K","default":false},"thumbnails":{"items":{"$ref":"#/components/schemas/Thumbnail"},"type":"array","title":"Thumbnails"}},"type":"object","title":"VideoResult"},"app__api__v2__youtube__schemas__Metadata":{"properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"author_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author Name"},"author_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author Url"},"thumbnail_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail Url"}},"type":"object","title":"Metadata"},"app__api__v2__youtube__schemas__VideoInfoResponse":{"properties":{"video_id":{"type":"string","title":"Video Id","description":"YouTube video ID"},"metadata":{"anyOf":[{"$ref":"#/components/schemas/app__api__v2__youtube__schemas__Metadata"},{"type":"null"}]},"available_languages":{"items":{"$ref":"#/components/schemas/AvailableLanguage"},"type":"array","title":"Available Languages","description":"Available transcript languages (includes 'asr' if auto-generated captions exist)"}},"type":"object","required":["video_id"],"title":"VideoInfoResponse","description":"Response for `GET /info` — metadata + available languages (non-billable)."},"app__api__v2__youtube__schemas_youtube__VideoInfoResponse":{"properties":{"videoId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Videoid"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"viewCountText":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Viewcounttext"},"viewCountShort":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Viewcountshort"},"publishDate":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Publishdate"},"relativeDate":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Relativedate"},"likeCountText":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Likecounttext"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"descriptionLinks":{"items":{"$ref":"#/components/schemas/DescriptionLink"},"type":"array","title":"Descriptionlinks"},"channel":{"anyOf":[{"$ref":"#/components/schemas/VideoInfoChannel"},{"type":"null"}]},"thumbnails":{"items":{"$ref":"#/components/schemas/Thumbnail"},"type":"array","title":"Thumbnails"},"details":{"anyOf":[{"$ref":"#/components/schemas/VideoInfoDetails"},{"type":"null"}]},"related":{"anyOf":[{"items":{"$ref":"#/components/schemas/RelatedVideo"},"type":"array"},{"type":"null"}],"title":"Related"}},"type":"object","title":"VideoInfoResponse"},"PaymentActionDetail":{"properties":{"message":{"description":"User-friendly explanation of why payment is required","title":"Message","type":"string"},"reason":{"description":"Machine-readable reason for the payment requirement","enum":["insufficient_credits","no_active_paid_plan"],"title":"Reason","type":"string"},"action_label":{"description":"Short label for the recommended action CTA","title":"Action Label","type":"string"},"action_url":{"description":"URL to take the recommended action (top-up or pricing)","title":"Action Url","type":"string"}},"required":["message","reason","action_label","action_url"],"title":"PaymentActionDetail","type":"object"}},"securitySchemes":{"bearerAuth":{"type":"http","description":"Use Authorization: Bearer {your_api_key}","scheme":"bearer"}}},"tags":[{"name":"YouTube transcript","description":"Pull any video's transcript by URL or 11-character ID, with or without timestamps, as JSON or text. Check available languages first, then pull the exact track."},{"name":"YouTube search","description":"Find the videos, channels, playlists, or movies worth processing: search a topic, then filter by popularity, upload date, or duration to build a work queue."},{"name":"YouTube channel","description":"Size up a channel and pull everything it publishes: subscriber and video counts, uploads, Shorts, live streams, playlists, community posts, sections, and available tabs, from any @handle, URL, or channel ID."},{"name":"YouTube playlist","description":"Walk every video in a playlist, paginated: a full course, season, or collection, ready to process."},{"name":"YouTube video","description":"Get a video's stats and context without transcribing: view and like counts, publish date, the full description with its links extracted, and related videos. Add include=details for duration, category, tags, and caption availability."}],"servers":[{"url":"https://transcriptapi.com"}],"security":[{"bearerAuth":[]}]}