Download YouTube videos
from your own code.

curl -H "X-API-Key: $VIDPICKR_API_KEY" \
  "https://api.vidpickr.com/v1/info?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ"

# 1. Set your key
export VIDPICKR_API_KEY="vpk_live_..."

# 2. Resolve the URL — capture the tokens we'll need next
INFO=$(curl -s -H "X-API-Key: $VIDPICKR_API_KEY" \
  "https://api.vidpickr.com/v1/info?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ")
V_TOKEN=$(echo "$INFO" | jq -r '.resolutions[] | select(.height==1080) | .video_only[0].download_token')
A_TOKEN=$(echo "$INFO" | jq -r '.audio_only | sort_by(-.bitrate) | .[0].download_token')

# 3. Stream both tracks in parallel, then mux with ffmpeg
curl -s -H "X-API-Key: $VIDPICKR_API_KEY" -o v.mp4 \
  "https://api.vidpickr.com/v1/stream?token=$V_TOKEN" &
curl -s -H "X-API-Key: $VIDPICKR_API_KEY" -o a.m4a \
  "https://api.vidpickr.com/v1/stream?token=$A_TOKEN" &
wait
ffmpeg -y -i v.mp4 -i a.m4a -c copy out.mp4 && rm v.mp4 a.m4a
echo "wrote out.mp4"

curl -H "X-API-Key: vpk_live_..." \
  "https://api.vidpickr.com/v1/info?url=..."

async function call(url) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await fetch(url, { headers: { "X-API-Key": KEY } });
    if (res.status !== 429) return res;
    const retryAfter = parseInt(res.headers.get("Retry-After") || "5", 10);
    const jitter = Math.random() * 500;
    await new Promise((r) => setTimeout(r, retryAfter * 1000 + jitter));
  }
  throw new Error("rate-limited too many times");
}

# An error response (HTTP 429)
{
  "error": {
    "code": "rate_limited",
    "message": "too many requests, retry in 14s"
  }
}

# v1 (current)
curl "https://api.vidpickr.com/v1/info?url=..."

# Future versions will live alongside:
# curl "https://api.vidpickr.com/api/v2/info?url=..."

$ curl -H "X-API-Key: vpk_live_..." \
    "https://api.vidpickr.com/v1/info?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ"
{
  "title": "Never Gonna Give You Up",
  "duration_sec": 213,
  "platform": "youtube",
  "thumbnail": "https://i.ytimg.com/vi_webp/dQw4w9WgXcQ/maxresdefault.webp",
  "resolutions": [
    {
      "height": 1080,
      "video_only": [
        {
          "ext": "mp4",
          "vcodec": "av01.0.08M.08",
          "size_mb": 28.4,
          "download_token": "v1.eyJWIjoidjEiLCJUIjoiYXYwMSIsIkUiOjE3..."
        },
        {
          "ext": "webm",
          "vcodec": "vp09.00.50.08",
          "size_mb": 35.1,
          "download_token": "v1.eyJWIjoidjEiLCJUIjoidnA5IiwiRSI6MTc..."
        }
      ]
    },
    { "height": 720, "video_only": [ /* ... */ ] },
    { "height": 480, "video_only": [ /* ... */ ] }
  ],
  "audio_only": [
    {
      "ext": "m4a",
      "acodec": "mp4a.40.2",
      "bitrate": 128,
      "size_mb": 3.2,
      "download_token": "a1.eyJWIjoiYTEiLCJUIjoiYWFjIiwiRSI6MTc..."
    },
    {
      "ext": "webm",
      "acodec": "opus",
      "bitrate": 160,
      "size_mb": 4.1,
      "download_token": "a1.eyJWIjoiYTEiLCJUIjoib3B1cyIsIkUiOjE3..."
    }
  ],
  "subtitles": [
    { "language": "en", "kind": "manual", "download_token": "s1..." },
    { "language": "tr", "kind": "auto",   "download_token": "s1..." }
  ]
}

curl -H "X-API-Key: vpk_live_..." \
  -o video.mp4 \
  "https://api.vidpickr.com/v1/stream?token=v1.eyJWIjoidjEi..."

# Resolve the URL and grab the 1080p merge token
INFO=$(curl -s -H "X-API-Key: $VIDPICKR_API_KEY" \
  "https://api.vidpickr.com/v1/info?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ")
MERGE=$(echo "$INFO" | jq -r '.resolutions[] | select(.height==1080) | .download_token')

# Split into video-only + audio-only tokens
SPLIT=$(curl -s -H "X-API-Key: $VIDPICKR_API_KEY" \
  "https://api.vidpickr.com/v1/split_token?token=$MERGE")
V_TOK=$(echo "$SPLIT" | jq -r '.video_token')
A_TOK=$(echo "$SPLIT" | jq -r '.audio_token')

# Stream both, then mux with ffmpeg
curl -s -H "X-API-Key: $VIDPICKR_API_KEY" -o v.mp4 \
  "https://api.vidpickr.com/v1/stream?token=$V_TOK" &
curl -s -H "X-API-Key: $VIDPICKR_API_KEY" -o a.m4a \
  "https://api.vidpickr.com/v1/stream?token=$A_TOK" &
wait
ffmpeg -y -i v.mp4 -i a.m4a -c copy out.mp4

# Resolve, find the language track, download as SRT
INFO=$(curl -s -H "X-API-Key: $VIDPICKR_API_KEY" \
  "https://api.vidpickr.com/v1/info?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ")
TOKEN=$(echo "$INFO" | jq -r '.subtitles[] | select(.code=="en" and .is_auto==false) | .download_token')

# Default format is SRT
curl -s -H "X-API-Key: $VIDPICKR_API_KEY" \
  -o captions.srt \
  "https://api.vidpickr.com/v1/subtitle?token=$TOKEN"

# Or VTT / TXT
curl -s -H "X-API-Key: $VIDPICKR_API_KEY" \
  -o captions.vtt \
  "https://api.vidpickr.com/v1/subtitle?token=$TOKEN&format=vtt"

# Both files already downloaded via /v1/stream
ffmpeg -y -i video.mp4 -i audio.m4a -c copy out.mp4

# That's it. No re-encoding (the -c copy flag).
# Takes about a second per minute of source video.

await Promise.all([
  pull(video.download_token, "v.mp4"),
  pull(audio.download_token, "a.m4a"),
]);

import os, time, random, requests
from contextlib import contextmanager

API_KEY = os.environ["VIDPICKR_API_KEY"]
BASE = "https://api.vidpickr.com/v1"

def masked_key(k):
    return k[:9] + "..." + k[-4:]   # vpk_live_...abcd

def call_with_backoff(method, url, **kw):
    """Retries on 429 with Retry-After + jitter; retries once on 502."""
    for attempt in range(5):
        r = requests.request(method, url, headers={"X-API-Key": API_KEY}, **kw)
        if r.status_code == 429:
            wait = int(r.headers.get("Retry-After", "5"))
            time.sleep(wait + random.random() * 0.5)
            continue
        if r.status_code == 502 and attempt == 0:
            time.sleep(2)
            continue
        return r
    r.raise_for_status()
    return r

def resolve(youtube_url):
    return call_with_backoff("GET", f"{BASE}/info",
                              params={"url": youtube_url}).json()

@contextmanager
def stream_to(path, token):
    r = call_with_backoff("GET", f"{BASE}/stream",
                          params={"token": token}, stream=True)
    r.raise_for_status()
    with open(path, "wb") as f:
        for chunk in r.iter_content(chunk_size=1 << 20):
            f.write(chunk)
    yield path

# Three SDKs published — npm @vidpickr/sdk, pip vidpickr,
# go get github.com/vidpickr/sdk-go. The curl + ffmpeg pattern in
# Quickstart still works if you'd rather skip the SDK.