Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/coah80/yoink/llms.txt

Use this file to discover all available pages before exploring further.

Yoink downloads video, audio, and images from dozens of platforms through a layered pipeline that maximises reliability. When one provider fails, the next one takes over automatically — all without any manual intervention from you.

​
How the download pipeline works

Every download starts with a URL validation check and a concurrency gate before any network request is made. Yoink enforces a maximum of 3 concurrent jobs per client (MaxJobsPerClient = 3) and a hard cap of 8 GB per file (FileSizeLimit = 8 × 1024 × 1024 × 1024 bytes) and 4 hours of video duration (MaxVideoDuration = 4 × 60 × 60 seconds). For YouTube, the full fallback chain is:
  1. yt-dlp — primary downloader with format selection and merge
  2. yt-dlp with proxy — retried automatically when a proxy is configured
  3. Cobalt API — final fallback for YouTube when both yt-dlp attempts fail
For every other platform, yt-dlp is used directly. Twitter/X and Instagram have dedicated extractors that fall back to yt-dlp if they fail.

​
Starting a download

GET /api/download
ParameterRequiredValues
url✓Any supported URL
formatvideo (default), audio, photo
quality2160p, 1440p, 1080p (default), 720p, 480p, 360p
containermp4 (default), webm, mkv, mov
audioFormatmp3 (default), m4a, opus, wav, flac
audioBitrate64, 96, 128, 192, 256, 320 (default)
progressIdCorrelate with SSE progress stream
clientIdPer-client job tracking
twitterGifstrue (default) / false — auto-convert Twitter GIFs
playlisttrue — download the full playlist; false (default) — download a single video from the URL

​
Fetching metadata first

Before presenting format options to a user, fetch metadata for a URL: 
GET /api/metadata?url=<url>&playlist=true|false
Metadata is cached in memory for 10 minutes. The response includes title, ext, uploader, duration, thumbnail, and isPlaylist. For YouTube clips it additionally includes clipStartTime, clipEndTime, and clipDuration.

​
Format and quality reference

Video Containers

ContainerMIME type
mp4video/mp4
webmvideo/webm
mkvvideo/x-matroska
movvideo/quicktime

Audio Formats

FormatMIME type
mp3audio/mpeg
m4aaudio/mp4
opusaudio/opus
wavaudio/wav
flacaudio/flac

​
Quality options

QualityMax height
2160p2160 px
1440p1440 px
1080p1080 px
720p720 px
480p480 px
360p360 px
yt-dlp format selection prefers AVC (h264) video with AAC audio so the result plays back without re-encoding on most devices.

​
Platform-specific behaviour

  • Metadata is fetched via Cobalt first; yt-dlp is used as a fallback.
  • Clips (/clip/ URLs): Yoink parses the clip’s startTimeMs / endTimeMs, downloads the full video via yt-dlp --download-sections, and trims with ffmpeg if the section download fails.
  • Thumbnail downloads use the photo format. Yoink tries maxresdefault.jpg → sddefault.jpg → hqdefault.jpg in order.
  • Regular videos and slideshows are downloaded via the tikwm extractor.
  • Music/sound URLs (/music/ paths) are downloaded as audio-only.
  • Slideshows are returned as MP4 files.
  • Downloaded via the fxtwitter extractor with yt-dlp as a fallback.
  • Auto-GIF detection: When twitterGifs=true, Yoink probes files under 20 MB and converts native GIF-type videos to real .gif files automatically.
  • Uses a dedicated Cobalt-based Instagram extractor, falling back to yt-dlp.
yt-dlp is used directly. Any site supported by yt-dlp works out of the box.

​
Real-time progress via SSE

Track download progress without polling by subscribing to the Server-Sent Events stream: 
GET /api/progress/{id}
Each event includes a status field (starting, downloading, processing, complete, or error) and a percent value from 0–100. Pass the same progressId to the download request and this endpoint to correlate them. 
const es = new EventSource(`/api/progress/${progressId}`);
es.onmessage = (e) => {
  const { status, percent, message } = JSON.parse(e.data);
  console.log(`${status}: ${percent}% — ${message}`);
};

​
Limits at a glance

LimitValue
Max file size8 GB
Max video duration4 hours
Max concurrent jobs per client3
Metadata cache TTL10 minutes
If you exceed the concurrent job limit, the API returns HTTP 429 with an error message indicating the current maximum. Start a new download only after an existing one completes.
Use format=photo on a YouTube URL to download the highest-resolution thumbnail available as a JPEG — no video download required.

Build docs developers (and LLMs) love

Get started for freeTalk to us