{"openapi":"3.2.0","info":{"title":"YouTube to Telegram Uploader API","description":"Enterprise-grade media bridge: Seamlessly transfer video and audio from global platforms to Telegram. Features advanced restriction bypass, high-speed streaming, and background task processing.","version":"1.0.0"},"servers":[{"url":"https://you2tele.jojapi.net"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"YouTube"},{"name":"Stream"},{"name":"Download"},{"name":"Metadata"}],"x-agent-commerce":{"catalog_url":"https://you2tele.jojapi.net/_jojapi/agent/plans","discovery_url":"https://you2tele.jojapi.net/.well-known/x402","directory_url":"https://agents.jojapi.net/apis/youtube-to-telegram-uploader-api","docs":"https://docs.jojapi.com/consumers/agents"},"paths":{"/search":{"get":{"operationId":"get_search","summary":"search","description":"If `query` is a URL, returns full video metadata (same as `/video_info`).\n\nOtherwise, searches YouTube and returns a list of matching results.\n\nResults are **cached for 1 hour** — identical queries return instantly.\n\nEach result includes title, video ID, URL, thumbnail, channel info, duration, and view count.","tags":["YouTube"],"responses":{"200":{"description":"Search results, or single video info when a URL is provided","content":{"application/json":{"examples":{"Example_1":{"value":[{"id":"dQw4w9WgXcQ","title":"Rick Astley - Never Gonna Give You Up (Official Video)","description":"The official video for Never Gonna Give You Up by Rick Astley.","duration_seconds":213,"duration_string":"03:33","view_count":1767304003,"thumbnail":"https://i.ytimg.com/vi/dQw4w9WgXcQ/hq720.jpg","webpage_url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","webpage_url_domain":"youtube.com","uploader_info":{"name":"Rick Astley"}}]}}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error message"}},"type":"object","required":["message"],"title":"ErrorResponse","description":"Error response format returned by all endpoints"},"examples":{"Example_1":{"value":{"message":"Forbidden: Access denied."}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"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"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"examples":{"Example_1":{"value":{"detail":[{"loc":[],"msg":"","type":"","ctx":{}}]}}}}}}},"parameters":[{"name":"limit","in":"query","description":"Maximum number of results to return when searching (1–50). Ignored when query is a URL.","required":false,"schema":{"type":"number","example":10,"default":10}},{"name":"query","in":"query","description":"Search query string, or a full video URL to fetch its metadata directly","required":true,"schema":{"type":"string"}}]}},"/youtube_video_stream":{"get":{"operationId":"get_youtube_video_stream","summary":"youtube_video_stream","description":"Extracts a direct streaming URL from YouTube and returns a temporary playback link valid for **10 minutes**.\n\nThe playback link (`/youtube_video_stream_play`) streams the file in real time. If video and audio are separate tracks, they are merged on-the-fly.\n\n**Cookies**: Send your YouTube account cookies via the `X-Cookies` header to access private videos, personal playlists, or members-only content.","tags":["Stream"],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"url":{"type":"string","title":"Url","description":"Temporary streaming/playback URL (valid 10 minutes)"},"warning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Warning","description":"Deprecation notice if a deprecated parameter was used"}},"type":"object","required":["url"],"title":"StreamResponse","description":"Response model for streaming URL endpoints"},"examples":{"Example_1":{"value":{"url":"https://api.example.com/youtube_video_stream_play?key=abc123xyz456"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error message"}},"type":"object","required":["message"],"title":"ErrorResponse","description":"Error response format returned by all endpoints"},"examples":{"not_supported_site":{"value":{"message":"Unsupported website. This API currently supports: Youtube, Facebook, Tiktok, Instagram, Twitter, Soundcloud."}},"live_not_supported":{"value":{"message":"Live videos are not supported. Only pre-recorded videos can be downloaded."}},"invalid_video_id":{"value":{"message":"Invalid video_id format."}}}}}},"403":{"description":"Access restricted","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error message"}},"type":"object","required":["message"],"title":"ErrorResponse","description":"Error response format returned by all endpoints"},"examples":{"age_restricted":{"value":{"message":"Age-restricted content requires authentication."}},"premiere_not_started":{"value":{"message":"Video premiere has not started yet."}}}}}},"404":{"description":"Video not found","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error message"}},"type":"object","required":["message"],"title":"ErrorResponse","description":"Error response format returned by all endpoints"},"examples":{"Example_1":{"value":{"message":"Invalid video ID."}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"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"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"examples":{"Example_1":{"value":{"detail":[{"loc":[],"msg":"","type":"","ctx":{}}]}}}}}},"425":{"description":"Download in progress — poll `progress_url` for status","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","title":"Status","description":"`processing` while download runs in background","default":"processing"},"download_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Download Url","description":"Download URL (youtube_to_server only)"},"job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Id","description":"Job ID to track progress (youtube_to_telegram only)"}},"type":"object","title":"TryAfterResponse","description":"Response returned when download is queued for background processing"},"examples":{"Example_1":{"value":{"job_id":"abc123xyz789","status":"processing"}}}}}},"500":{"description":"Could not extract stream URLs","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error message"}},"type":"object","required":["message"],"title":"ErrorResponse","description":"Error response format returned by all endpoints"},"examples":{"Example_1":{"value":{"message":"Could not extract video URLs"}}}}}},"503":{"description":"Service temporarily unavailable","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error message"}},"type":"object","required":["message"],"title":"ErrorResponse","description":"Error response format returned by all endpoints"},"examples":{"geo_bypass_unavailable":{"value":{"message":"Regional bypass service temporarily unavailable."}},"proxy_unavailable":{"value":{"message":"Proxy service unavailable. Please try again later."}}}}}}},"parameters":[{"name":"file_format","in":"query","description":"Output file format:\n- `mp4` – Video, MP4\n- `m4a` – Audio, M4A\n- `mp3` – Audio, MP3","required":false,"schema":{"type":"string","enum":["mp4","m4a","mp3"],"default":"mp4"}},{"name":"video_id","in":"query","description":"YouTube video ID (10–12 alphanumeric characters, e.g. `dQw4w9WgXcQ`)","required":true,"schema":{"type":"string"}},{"name":"quality","in":"query","description":"Output quality (applied to the chosen format):\n- `best` – Best available quality\n- `worst` – Lowest quality\n- `1080p / 720p / 480p / 360p` – Video at specific resolution\n- `256k / 128k` – Audio at specific bitrate","required":false,"schema":{"type":"string","example":"best","default":"best"}},{"name":"format","in":"query","description":"**Deprecated** — use `file_format` instead. Accepted values: `audio`, `video`.","required":false,"schema":{"type":"string"}},{"name":"X-Cookies","in":"header","description":"Netscape-format cookie string from your YouTube account session, used to access content available only to your account (private videos, personal playlists, members-only content, etc.).","required":false,"schema":{"type":"string"}}]}},"/youtube_live_hls":{"get":{"operationId":"get_youtube_live_hls","summary":"youtube_live_hls","description":"Validates that the video is currently live, then returns a temporary playback link valid for **10 minutes**.\n\nThe playback link (`/youtube_live_hls_play`) delivers the stream as **segmented chunks** with adaptive bitrate — ideal for web players and most streaming clients.\n\n**Adaptive vs MP4**: Use this endpoint for web players and modern streaming clients. Use `/youtube_live_mp4` when you need a format compatible with standard media players that don't support adaptive streaming.\n\nUse `audio_only=true` to receive an audio-only stream.\n\n**Cookies**: Send your YouTube account cookies via the `X-Cookies` header to access private videos, personal playlists, or members-only content.","tags":["Stream"],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"url":{"type":"string","title":"Url","description":"Temporary streaming/playback URL (valid 10 minutes)"},"warning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Warning","description":"Deprecation notice if a deprecated parameter was used"}},"type":"object","required":["url"],"title":"StreamResponse","description":"Response model for streaming URL endpoints"},"examples":{"Example_1":{"value":{"url":"https://api.example.com/youtube_video_stream_play?key=abc123xyz456"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error message"}},"type":"object","required":["message"],"title":"ErrorResponse","description":"Error response format returned by all endpoints"},"examples":{"not_supported_site":{"value":{"message":"Unsupported website. This API currently supports: Youtube, Facebook, Tiktok, Instagram, Twitter, Soundcloud."}}}}}},"403":{"description":"Access restricted","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error message"}},"type":"object","required":["message"],"title":"ErrorResponse","description":"Error response format returned by all endpoints"},"examples":{"age_restricted":{"value":{"message":"Age-restricted content requires authentication."}},"members_only":{"value":{"message":"This video is available to this channel's members"}},"access_denied":{"value":{"message":"Forbidden: Access denied."}},"country_blocked":{"value":{"message":"This video cannot be downloaded because it is not available in the country where the API server is located."}},"premiere_not_started":{"value":{"message":"Video premiere has not started yet."}}}}}},"404":{"description":"Video not found","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error message"}},"type":"object","required":["message"],"title":"ErrorResponse","description":"Error response format returned by all endpoints"},"examples":{"Example_1":{"value":{"message":"Invalid video ID."}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"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"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"examples":{"Example_1":{"value":{"detail":[{"loc":[],"msg":"","type":"","ctx":{}}]}}}}}},"500":{"description":"Failed to start stream","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error message"}},"type":"object","required":["message"],"title":"ErrorResponse","description":"Error response format returned by all endpoints"},"examples":{"Example_1":{"value":{"message":"Failed to start live process"}}}}}},"503":{"description":"Service temporarily unavailable","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error message"}},"type":"object","required":["message"],"title":"ErrorResponse","description":"Error response format returned by all endpoints"},"examples":{"geo_bypass_unavailable":{"value":{"message":"Regional bypass service temporarily unavailable."}},"proxy_unavailable":{"value":{"message":"Proxy service unavailable. Please try again later."}}}}}}},"parameters":[{"name":"video_id","in":"query","description":"YouTube live stream video ID (10–12 alphanumeric characters)","required":true,"schema":{"type":"string"}},{"name":"audio_only","in":"query","description":"Stream audio track only (no video).","required":false,"schema":{"type":"boolean","example":false,"default":false}},{"name":"X-Cookies","in":"header","description":"Netscape-format cookie string from your YouTube account session, used to access content available only to your account (private videos, personal playlists, members-only content, etc.).","required":false,"schema":{"type":"string"}}]}},"/youtube_to_telegram":{"get":{"operationId":"get_youtube_to_telegram","summary":"youtube_to_telegram","description":"Downloads a YouTube video or audio track and uploads it to a Telegram channel.\n\n**Caching**: All formats and qualities are cached — subsequent requests for the same video, format, and quality return instantly.\n\n**Webhook**: Supply `webhook_url` to receive a POST notification when the upload completes. The payload will be:\n```json\n{\"job_id\": \"abc123\", \"status\": \"completed\", \"video_id\": \"dQw4w9WgXcQ\", \"result\": {...}, \"timestamp\": 1700000000.0}\n```\n\n**Cookies**: Send your YouTube account cookies via the `X-Cookies` header to access private videos, personal playlists, or members-only content.","tags":["Download"],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"file_url":{"type":"string","title":"File Url","description":"Telegram message link"},"message_id":{"type":"integer","title":"Message Id","description":"Telegram message ID"},"chat_username":{"type":"string","title":"Chat Username","description":"Telegram channel username with @"},"status":{"description":"Upload status","default":"completed","type":"string","enum":["initializing","downloading","background_processing","completed","failed"],"title":"JobStatus"},"warning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Warning","description":"Deprecation notice if a deprecated parameter was used"}},"type":"object","required":["file_url","message_id","chat_username"],"title":"TelegramResponse","description":"Response model for /youtube_to_telegram endpoint"},"examples":{"Example_1":{"value":{"chat_username":"@storingayyadmusicbots","file_url":"https://t.me/storingayyadmusicbots/1234","message_id":1234,"status":"completed"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error message"}},"type":"object","required":["message"],"title":"ErrorResponse","description":"Error response format returned by all endpoints"},"examples":{"not_supported_site":{"value":{"message":"Unsupported website. This API currently supports: Youtube, Facebook, Tiktok, Instagram, Twitter, Soundcloud."}},"live_not_supported":{"value":{"message":"Live videos are not supported. Only pre-recorded videos can be downloaded."}}}}}},"403":{"description":"Access restricted","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error message"}},"type":"object","required":["message"],"title":"ErrorResponse","description":"Error response format returned by all endpoints"},"examples":{"access_denied":{"value":{"message":"Forbidden: Access denied."}},"age_restricted":{"value":{"message":"Age-restricted content requires authentication."}},"premiere_not_started":{"value":{"message":"Video premiere has not started yet."}}}}}},"404":{"description":"Video not found","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error message"}},"type":"object","required":["message"],"title":"ErrorResponse","description":"Error response format returned by all endpoints"},"examples":{"Example_1":{"value":{"message":"Invalid video ID."}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"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"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"examples":{"Example_1":{"value":{"detail":[{"loc":[],"msg":"","type":"","ctx":{}}]}}}}}},"425":{"description":"Download in progress — retry the returned URL","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","title":"Status","description":"`processing` while download runs in background","default":"processing"},"download_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Download Url","description":"Download URL (youtube_to_server only)"},"job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Id","description":"Job ID to track progress (youtube_to_telegram only)"}},"type":"object","title":"TryAfterResponse","description":"Response returned when download is queued for background processing"},"examples":{"Example_1":{"value":{"job_id":"abc123xyz789","status":"processing"}}}}}},"500":{"description":"Download failed","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error message"}},"type":"object","required":["message"],"title":"ErrorResponse","description":"Error response format returned by all endpoints"},"examples":{"download_failed":{"value":{"message":"Timeout while downloading video info"}},"format_unavailable":{"value":{"message":"Requested video format is not available."}}}}}},"503":{"description":"Service temporarily unavailable","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error message"}},"type":"object","required":["message"],"title":"ErrorResponse","description":"Error response format returned by all endpoints"},"examples":{"geo_bypass_unavailable":{"value":{"message":"Regional bypass service temporarily unavailable."}},"cache_unavailable":{"value":{"message":"Cache service temporarily unavailable. Please try again in a moment."}}}}}}},"parameters":[{"name":"webhook_url","in":"query","description":"Optional URL to receive a POST callback when the download completes.","required":false,"schema":{"type":"string"}},{"name":"file_format","in":"query","description":"Output file format:\n- `m4a` – Audio, M4A (result cached)\n- `mp3` – Audio, MP3 (never cached)\n- `mp4` – Video, MP4 (result cached)","required":false,"schema":{"type":"string","enum":["m4a","mp3","mp4"],"default":"m4a"}},{"name":"format","in":"query","description":"**Deprecated** — use `file_format` instead. Accepted values: `audio`, `video`.","required":false,"schema":{"type":"string"}},{"name":"video_id","in":"query","description":"YouTube video ID (10–12 alphanumeric characters, e.g. `dQw4w9WgXcQ`)","required":true,"schema":{"type":"string"}},{"name":"quality","in":"query","description":"Output quality (applied to the chosen format):\n- `best` – Best available quality\n- `worst` – Lowest quality\n- `1080p / 720p / 480p / 360p` – Video at specific resolution\n- `256k / 128k` – Audio at specific bitrate","required":false,"schema":{"type":"string","example":"best","default":"best"}},{"name":"X-Cookies","in":"header","description":"Netscape-format cookie string from your YouTube account session, used to access content available only to your account (private videos, personal playlists, members-only content, etc.).","required":false,"schema":{"type":"string"}}]}},"/youtube_to_server":{"get":{"operationId":"get_youtube_to_server","summary":"youtube_to_server","description":"Downloads a YouTube video or audio track to the server and returns a temporary download link valid for **10 minutes**.\n\n**MEGA subscribers** have no file size limit; others are limited to 5 GB.\n\n**Webhook**: Supply `webhook_url` to receive a POST callback when the download completes. The payload will be:\n```json\n{\"job_id\": \"abc123\", \"status\": \"completed\", \"video_id\": \"dQw4w9WgXcQ\", \"result\": {...}, \"timestamp\": 1700000000.0}\n```\n\n**Cookies**: Send your YouTube account cookies via the `X-Cookies` header to access private videos, personal playlists, or members-only content.","tags":["Download"],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"download_url":{"type":"string","title":"Download Url","description":"Temporary download URL (valid 10 minutes)"},"key":{"type":"string","title":"Key","description":"Temporary download key"},"video_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Video Id","description":"YouTube video ID"},"video_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Video Title","description":"Video title"},"duration":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duration","description":"Video duration in seconds"},"status":{"description":"Download status","default":"completed","type":"string","enum":["initializing","downloading","background_processing","completed","failed"],"title":"JobStatus"},"warning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Warning","description":"Deprecation notice if a deprecated parameter was used"}},"type":"object","required":["download_url","key"],"title":"ServerResponse","description":"Response model for /youtube_to_server endpoint"},"examples":{"Example_1":{"summary":"Example_1","value":{"download_url":"https://api.example.com/youtube_to_server_download?key=abc123xyz456","duration":212,"key":"abc123xyz456","status":"completed","video_id":"dQw4w9WgXcQ","video_title":"Rick Astley - Never Gonna Give You Up"}}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error message"}},"type":"object","required":["message"],"title":"ErrorResponse","description":"Error response format returned by all endpoints"},"examples":{"invalid_video_id":{"summary":"invalid_video_id","value":{"message":"Invalid video_id format."}},"live_not_supported":{"summary":"live_not_supported","value":{"message":"Live videos are not supported. Only pre-recorded videos can be downloaded."}},"not_supported_site":{"summary":"not_supported_site","value":{"message":"Unsupported website. This API currently supports: Youtube, Facebook, Tiktok, Instagram, Twitter, Soundcloud."}}}}}},"403":{"description":"Access restricted","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error message"}},"type":"object","required":["message"],"title":"ErrorResponse","description":"Error response format returned by all endpoints"},"examples":{"access_denied":{"summary":"access_denied","value":{"message":"Forbidden: Access denied."}},"premiere_not_started":{"summary":"premiere_not_started","value":{"message":"Video premiere has not started yet."}}}}}},"404":{"description":"Video not found","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error message"}},"type":"object","required":["message"],"title":"ErrorResponse","description":"Error response format returned by all endpoints"},"examples":{"Example_1":{"summary":"Example_1","value":{"message":"Invalid video ID."}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"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"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"examples":{"Example_1":{"summary":"Example_1","value":{"detail":[{"loc":[],"msg":"","type":"","ctx":{}}]}}}}}},"425":{"description":"Download in progress — poll `progress_url` for status","content":{"application/json":{"schema":{"properties":{"status":{"type":"string","title":"Status","description":"`processing` while download runs in background","default":"processing"},"download_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Download Url","description":"Download URL (youtube_to_server only)"},"job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Id","description":"Job ID to track progress (youtube_to_telegram only)"}},"type":"object","title":"TryAfterResponse","description":"Response returned when download is queued for background processing"},"examples":{"Example_1":{"summary":"Example_1","value":{"job_id":"abc123xyz789","status":"processing"}}}}}},"500":{"description":"Download failed","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error message"}},"type":"object","required":["message"],"title":"ErrorResponse","description":"Error response format returned by all endpoints"},"examples":{"download_failed":{"summary":"download_failed","value":{"message":"Timeout while downloading video info"}}}}}},"503":{"description":"Service temporarily unavailable","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error message"}},"type":"object","required":["message"],"title":"ErrorResponse","description":"Error response format returned by all endpoints"},"examples":{"geo_bypass_unavailable":{"summary":"geo_bypass_unavailable","value":{"message":"Regional bypass service temporarily unavailable."}},"cache_unavailable":{"summary":"cache_unavailable","value":{"message":"Cache service temporarily unavailable. Please try again in a moment."}},"proxy_unavailable":{"summary":"proxy_unavailable","value":{"message":"Proxy service unavailable. Please try again later."}}}}}}},"parameters":[{"name":"quality","in":"query","description":"Output quality (applied to the chosen format):\n- `best` – Best available quality\n- `worst` – Lowest quality\n- `1080p / 720p / 480p / 360p` – Video at specific resolution\n- `256k / 128k` – Audio at specific bitrate","required":false,"schema":{"type":"string","example":"best","default":"best"}},{"name":"format","in":"query","description":"**Deprecated** — use `file_format` instead. Accepted values: `audio`, `video`.","required":false,"schema":{"type":"string"}},{"name":"video_id","in":"query","description":"YouTube video ID (10–12 alphanumeric characters, e.g. `dQw4w9WgXcQ`)","required":true,"schema":{"type":"string"}},{"name":"webhook_url","in":"query","description":"Optional URL to receive a POST callback when the download completes.","required":false,"schema":{"type":"string"}},{"name":"file_format","in":"query","description":"Output file format:\n- `mp4` – Video, MP4\n- `m4a` – Audio, M4A\n- `mp3` – Audio, MP3","required":false,"schema":{"type":"string","enum":["mp4","m4a","mp3"],"default":"mp4"}},{"name":"X-Cookies","in":"header","description":"Netscape-format cookie string from your YouTube account session, used to access content available only to your account (private videos, personal playlists, members-only content, etc.).","required":false,"schema":{"type":"string"}}]}},"/video_info":{"get":{"operationId":"get_video_info","summary":"video_info","description":"Fetches metadata for any supported video URL (YouTube, TikTok, Instagram, Facebook, SoundCloud, and more), including title, duration, view count, thumbnail, subtitles, available formats, and uploader info.\n\nResults are **cached for 1 hour** — subsequent requests for the same URL return instantly. Requests with cookies bypass the cache.\n\n**Cookies**: Send your account cookies via the `X-Cookies` header to access private content.","tags":["Metadata"],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Video ID"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Video title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Video description"},"duration_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duration Seconds","description":"Duration in seconds"},"duration_string":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Duration String","description":"Duration as HH:MM:SS"},"upload_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Upload Date","description":"Upload date (YYYYMMDD)"},"view_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"View Count","description":"View count"},"concurrent_view_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Concurrent View Count","description":"Current concurrent viewer count (live streams)"},"thumbnail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail","description":"Best thumbnail URL"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"Video language code"},"has_subtitles":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Subtitles","description":"Whether automatic subtitles exist"},"subtitle_languages":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Subtitle Languages","description":"Available automatic subtitle language codes (e.g. 'en', 'ar', 'fr')"},"webpage_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Webpage Url","description":"Full video URL"},"webpage_url_domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Webpage Url Domain","description":"Domain of the video URL (e.g. youtube.com)"},"uploader_info":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Uploader Info","description":"Uploader/channel info"},"formats":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Formats","description":"Available download formats"}},"type":"object","title":"VideoInfoResponse","description":"Response model for /video_info endpoint"},"examples":{"Example_1":{"value":{"id":{},"title":{},"description":{},"duration_seconds":{},"duration_string":{},"upload_date":{},"view_count":{},"concurrent_view_count":{},"thumbnail":{},"language":{},"has_subtitles":{},"subtitle_languages":{},"webpage_url":{},"webpage_url_domain":{},"uploader_info":{},"formats":{}}}}}}},"400":{"description":"Unsupported site","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error message"}},"type":"object","required":["message"],"title":"ErrorResponse","description":"Error response format returned by all endpoints"},"examples":{"Example_1":{"value":{"message":"Unsupported website. This API currently supports: Youtube, Facebook, Tiktok, Instagram, Twitter, Soundcloud."}}}}}},"403":{"description":"Access restricted","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error message"}},"type":"object","required":["message"],"title":"ErrorResponse","description":"Error response format returned by all endpoints"},"examples":{"access_denied":{"value":{"message":"Forbidden: Access denied."}},"geo_blocked":{"value":{"message":"This video is not available in your region."}},"country_blocked":{"value":{"message":"This video cannot be downloaded because it is not available in the country where the API server is located."}}}}}},"404":{"description":"Video not found","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error message"}},"type":"object","required":["message"],"title":"ErrorResponse","description":"Error response format returned by all endpoints"},"examples":{"Example_1":{"value":{"message":"Invalid video ID."}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"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"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"examples":{"Example_1":{"value":{"detail":[{"loc":[],"msg":"","type":"","ctx":{}}]}}}}}},"500":{"description":"Failed to fetch metadata","content":{"application/json":{"schema":{"properties":{"message":{"type":"string","title":"Message","description":"Human-readable error message"}},"type":"object","required":["message"],"title":"ErrorResponse","description":"Error response format returned by all endpoints"},"examples":{"Example_1":{"value":{"message":"Failed to fetch video information."}}}}}}},"parameters":[{"name":"video_url","in":"query","description":"Full video URL from any supported site (YouTube, TikTok, Instagram, Facebook, etc.)","required":true,"schema":{"type":"string"}},{"name":"X-Cookies","in":"header","description":"Netscape-format cookie string from your YouTube account session, used to access content available only to your account (private videos, personal playlists, members-only content, etc.).","required":false,"schema":{"type":"string"}}]}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-JoJAPI-Key","description":"Your JoJ API key."}}}}