A production-ready REST API built on yt-dlp. Resolve metadata, stream media, and extract audio from 1,615+ supported platforms — YouTube, TikTok, Instagram, Twitter, and more.
All endpoints return JSON unless otherwise noted. Errors always include success: false and an error field.
Returns current service status. Use this to confirm the API is running and check the yt-dlp version in production.
GET / // Response { "service": "nexus-yt-dlp-api", "status": "ok", "ytdlp_version": "2026.07.04" }
Extracts metadata and CDN stream URLs from any supported platform. Also accepts POST with a JSON body. Returns url for single-stream platforms (TikTok, Snapchat etc.) or urls[] for split-stream platforms (YouTube DASH). Use /stream to download safely — never pass the raw CDN URLs to clients directly.
| Param | Type | Description |
|---|---|---|
| urlrequired | string | Any supported media URL |
| typeoptional | string | video or audio. Default: video |
| qualityoptional | string | best, worst, or a height like 720. Default: best |
GET /resolve?url=https://youtube.com/watch?v=...&type=video&quality=720 POST /resolve // body: { "url": "...", "type": "audio", "quality": "best" } // Response { "success": true, "url": null, // null for YouTube (DASH), direct URL for others "urls": [ // split streams (YouTube only) { "url": "https://...", "ext": "mp4", "vcodec": "avc1", "acodec": null }, { "url": "https://...", "ext": "m4a", "vcodec": null, "acodec": "mp4a" } ], "title": "Video Title", "thumbnail": "https://...", "duration": 281, "duration_string": "4:41", "ext": "mp4", "resolution": "1280x720", "filesize": 32456789, "uploader": "Channel Name", "platform": "Youtube", "webpage_url": "https://youtube.com/watch?v=..." }
Streams the media file to the client with correct Content-Type and Content-Disposition headers. Handles DASH muxing server-side — clients never receive raw IP-bound CDN URLs (which would cause 403). Single-stream platforms proxy directly via CDN for instant start. YouTube and other DASH platforms are muxed through ffmpeg on the server.
| Param | Type | Description |
|---|---|---|
| urlrequired | string | Any supported media URL |
| typeoptional | string | video or audio. Default: video |
| qualityoptional | string | best, worst, or height like 720. Default: best |
GET /stream?url=https://tiktok.com/...&type=video GET /stream?url=https://youtube.com/...&type=audio&quality=128 // Response: binary file bytes // Content-Type: video/mp4 or audio/mp4 // Content-Disposition: attachment; filename="Video Title.mp4"
Convenience alias for /stream?type=audio. Extracts the best available audio track. Ideal for music bots, podcast tools, and audio-only downloaders. Returns m4a audio in an mp4 container.
| Param | Type | Description |
|---|---|---|
| urlrequired | string | Any supported media URL |
| qualityoptional | string | Bitrate: 128, 96, 64 etc. Default: best |
GET /audio?url=https://youtube.com/watch?v=...&quality=128 GET /audio?url=https://soundcloud.com/... // Response: binary audio bytes // Content-Type: audio/mp4 // Content-Disposition: attachment; filename="Track Title.m4a"
Returns complete metadata for any media URL without exposing CDN stream URLs. Includes engagement stats (views, likes, comments), chapters, subtitle languages, upload date, and channel info. Safe to cache and display to users.
| Param | Type | Description |
|---|---|---|
| urlrequired | string | Any supported media URL |
GET /info?url=https://youtube.com/watch?v=... // Response { "success": true, "id": "dQw4w9WgXcQ", "title": "Video Title", "description": "Full description...", "thumbnail": "https://...", "duration": 212, "upload_date": "20091025", "uploader": "Channel Name", "channel_url": "https://...", "view_count": 1400000000, "like_count": 17000000, "comment_count": 2500000, "tags": ["tag1", "tag2"], "categories": ["Music"], "is_live": false, "availability": "public", "chapters": [{ "title": "Intro", "start_time": 0, "end_time": 18 }], "subtitles": { "en": [...], "es": [...] } }
Returns every format yt-dlp can extract for a URL — format IDs, resolutions, codecs, bitrates, and filesizes. Use this to let users pick a quality, then pass that quality value to /stream.
| Param | Type | Description |
|---|---|---|
| urlrequired | string | Any supported media URL |
GET /formats?url=https://youtube.com/watch?v=... // Response { "success": true, "title": "Video Title", "platform": "Youtube", "formats": [ { "format_id": "137", "ext": "mp4", "resolution": "1920x1080", "fps": 30, "vcodec": "avc1.640028", "acodec": null, "tbr": 2500.5, "filesize": 45678900, "has_video": true, "has_audio": false } ] }
Proxies the media thumbnail image directly to the client. Use this URL as an <img src> — avoids CORS restrictions when displaying thumbnails from YouTube, TikTok, and other platforms in web/bot UIs.
| Param | Type | Description |
|---|---|---|
| urlrequired | string | Any supported media URL |
GET /thumbnail?url=https://youtube.com/watch?v=... // Response: image bytes // Content-Type: image/jpeg (or image/webp, image/png) // Use directly as: <img src="/thumbnail?url=...">
Resolves up to 10 URLs concurrently. Individual failures don't fail the whole batch — each result has its own success field. Useful for playlist handling or building a download queue.
| Field | Type | Description |
|---|---|---|
| urlsrequired | array | Array of media URLs (max 10) |
| typeoptional | string | video or audio. Default: video |
| qualityoptional | string | Quality for all URLs. Default: best |
POST /batch { "urls": ["https://youtube.com/...", "https://tiktok.com/..."], "type": "video", "quality": "720" } // Response { "success": true, "total": 2, "succeeded": 2, "failed": 0, "results": [ { "url_input": "https://youtube.com/...", "success": true, /* ...resolve fields */ }, { "url_input": "https://tiktok.com/...", "success": true, /* ...resolve fields */ } ] }
Returns every platform supported by the running yt-dlp version. Use the search param to filter. Useful for checking if a platform is supported before making a request.
| Param | Type | Description |
|---|---|---|
| searchoptional | string | Filter extractors by name |
GET /extractors GET /extractors?search=tiktok // Response { "success": true, "total": 1615, "extractors": ["Youtube", "TikTok", "Instagram", /* ... */] }
These are the most commonly used platforms. All 1,615 supported sites are listed below.
Every platform supported by yt-dlp 2026.07.04. If a site is listed here, passing its URL to any endpoint will work.
1,615 extractors
Pass these as the quality param to /resolve, /stream, /audio, and /batch. If the requested quality isn't available on a platform, yt-dlp automatically falls back to the next closest option — it never errors on unavailable quality.
| Value | Type | Meaning |
|---|---|---|
| best | video + audio | Highest available quality (default) |
| worst | video + audio | Lowest available quality |
| 2160 | video | 4K (3840×2160) |
| 1440 | video | 2K (2560×1440) |
| 1080 | video | Full HD (1920×1080) |
| 720 | video | HD (1280×720) |
| 480 | video | SD (854×480) |
| 360 | video | Low (640×360) |
| 240 | video | Very low (426×240) |
| 128 | audio | ~128 kbps |
| 96 | audio | ~96 kbps |
| 64 | audio | ~64 kbps |
All errors return JSON with success: false, a human-readable error field, and an optional detail field with the raw yt-dlp error.
{
"success": false,
"error": "Human readable message",
"detail": "Raw yt-dlp error if available"
}
| Status | Meaning |
|---|---|
| 400 | Missing or invalid params — check url is present and valid, type is video or audio |
| 403 | Content requires authentication or is private — the platform needs a login to access this content |
| 404 | Content not found or no longer available — the media was deleted or taken down |
| 422 | URL not supported — the platform or URL format is not recognised by yt-dlp |
| 429 | Batch limit exceeded — /batch accepts a maximum of 10 URLs per request |
| 500 | Unexpected error — an internal yt-dlp or server error occurred |