Include your key as the X-API-Key header in all API requests:
# Fetch video info with your key curl -s -X POST "http://localhost:5000/api/info" \ -H "Content-Type: application/json" \ -H "X-API-Key: YOUR_KEY" \ -d '{"url":"https://youtu.be/dQw4w9WgXcQ"}'
____ ___ ___ ___ | _ \ / _ \ / __\/ __| | | ) | (_) | (__ \__ \ |____/ \___/ \___/|___/
# Check server health curl -s "http://localhost:5000/health" | jq # Example response: { "ok": true, "hasCookies": true }
curl -s "http://localhost:5000/api/version" | jq # Example response: { "version": "2026.07.04", "engine": "YouTube Download Engine" }
# Get full info for a video curl -s -X POST "http://localhost:5000/api/info" \ -H "Content-Type: application/json" \ -d '{"url":"https://youtu.be/dQw4w9WgXcQ"}' \ | jq '{title, duration, view_count, format_count}' # List only 1080p formats curl -s -X POST "http://localhost:5000/api/info" \ -H "Content-Type: application/json" \ -d '{"url":"https://youtu.be/dQw4w9WgXcQ"}' \ | jq '.formats[] | select(.height==1080) | {format_id, label, vcodec, acodec, filesize_human}' # Response fields: # id, title, description, thumbnail, duration, duration_string # channel, uploader, channel_follower_count, view_count, like_count # upload_date, age_limit, tags[], chapters[], subtitles[] # format_count, formats[] (sorted best-first)
stream_type: "single" for combined streams or "merged" when video and audio are separate (720p+). For merged types, use /api/stream to download.# Resolve best available quality curl -s -X POST "http://localhost:5000/api/download" \ -H "Content-Type: application/json" \ -d '{"url":"https://youtu.be/dQw4w9WgXcQ"}' # Resolve a specific format by ID (get IDs from /api/info) curl -s -X POST "http://localhost:5000/api/download" \ -H "Content-Type: application/json" \ -d '{"url":"https://youtu.be/dQw4w9WgXcQ","format_id":"137"}' # Resolve by quality index (0 = best from /api/info formats[]) curl -s -X POST "http://localhost:5000/api/download" \ -H "Content-Type: application/json" \ -d '{"url":"https://youtu.be/dQw4w9WgXcQ","quality_index":0}'
# Download best quality as MP4 curl -L -o "video.mp4" \ "http://localhost:5000/api/stream?url=https://youtu.be/dQw4w9WgXcQ" # Download specific format (1080p = format_id 137) curl -L -o "video_1080p.mp4" \ "http://localhost:5000/api/stream?url=https://youtu.be/dQw4w9WgXcQ&format_id=137&title=RickRoll" # Stream directly into ffplay (watch without saving) curl -sL \ "http://localhost:5000/api/stream?url=https://youtu.be/dQw4w9WgXcQ" \ | ffplay - # Query parameters: # url (required) YouTube video URL # format_id (optional) format ID from /api/info # title (optional) Output filename hint
format_id — downloads that exact format via yt-dlp, uploads the file to
Catbox (or Litterbox for anonymous uploads), and returns the CDN URL as stream_url.
Also returns video_url / audio_url (direct Google CDN links, expire ~6 h).format_id — returns metadata + all available formats with proxy
stream_url values (use a specific format_id call to get the Catbox link for one format).CATBOX_USERHASH env var for a registered catbox.moe
account (permanent links). Without it, files are uploaded to Litterbox with a 72-hour expiry.
Files over 200 MB fall back to the proxy stream_url automatically.
| Param | Required | Description |
|---|---|---|
url |
✅ Yes | YouTube video URL |
format_id |
Optional | Format ID from /api/info. When provided, downloads & uploads that format to Catbox and returns its CDN URL as stream_url. |
# Get all formats (metadata listing, no Catbox upload) curl -s \ "http://localhost:5000/api/getdls?url=https://youtu.be/dQw4w9WgXcQ" \ | jq '{title,format_count,formats:[.formats[]|{format_id,label,stream_url}]}' # Upload format 18 (360p combined) to Catbox → get permanent CDN stream_url curl -s \ "http://localhost:5000/api/getdls?url=https://youtu.be/dQw4w9WgXcQ&format_id=18" \ | jq '{title,stream_type,stream_url}' # Example response (with format_id) # { # "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)", # "stream_type": "single", # "stream_url": "https://litter.catbox.moe/uaslk2.mp4" # } # Full pipeline: pick 360p format, get Catbox link, download from CDN FMT=18 CDN=$(curl -s \ "http://localhost:5000/api/getdls?url=https://youtu.be/dQw4w9WgXcQ&format_id=$FMT" \ | jq -r '.stream_url') curl -L -o "video.mp4" "$CDN"
index field. Compatible with older API clients.curl -s \ "http://localhost:5000/api/media-items?url=https://youtu.be/dQw4w9WgXcQ" \ | jq '.[0:3]' # first 3 formats
#!/usr/bin/env bash # Full YouTube download workflow using the API BASE="http://localhost:5000" URL="https://youtu.be/dQw4w9WgXcQ" # 1. Fetch all format metadata INFO=$(curl -s -X POST "$BASE/api/info" \ -H "Content-Type: application/json" \ -d "{\"url\":\"$URL\"}") TITLE=$(echo "$INFO" | jq -r '.title') echo "Video: $TITLE" # 2. List available resolutions echo "$INFO" | jq -r \ '.formats[] | "\(.label)\t\(.ext)\t\(.filesize_human // "?")"' # 3. Get the format_id for 1080p FMT=$(echo "$INFO" | jq -r \ '.formats[] | select(.height==1080 and .kind=="video") | .format_id' \ | head -1) echo "Using format_id: $FMT" # 4. Download merged 1080p MP4 SAFE=$(echo "$TITLE" | tr -d '[/\\:*?"<>|]') curl -L -o "${SAFE}.mp4" \ "$BASE/api/stream?url=$(python3 -c "import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))" "$URL")&format_id=$FMT&title=$SAFE" echo "Saved: ${SAFE}.mp4"