API за изтегляне от YouTube

Същото, което прави панелът, но от твоя код: бот, сайт, скрипт или друга услуга. Видео със звук, видео без звук или MP3, с избор на качество, кодек и битрейт.

• Заявките и отговорите са JSON в UTF-8. Съобщенията са на български, а кодовете за грешки са стабилни английски низове, за да ги проверяваш в кода.
• Времената са в ISO 8601, UTC (2026-10-26T14:11:55Z), размерите са в байтове.
• Работи само през HTTPS. Всеки отговор има хедър X-Request-Id; посочвай го, ако нещо се обърка.

Какво от панела има в API-то

Входът в YouTube акаунта на агента става с мишка и клавиатура в отдалечения браузър, затова е само в панела. Създаването и управлението на API ключове, както и паролата на панела, са нарочно само в панела. Така откраднат ключ не може да създаде нови ключове или да заключи собственика навън.

Бърз старт

1. В панела отвори Настройки → API ключове → Нов ключ, дай име, остави правото „Изтегляне“ и копирай ключа. Показва се само веднъж.
2. Пусни задача и изчакай до 2 минути да е готова (wait=120):
   bash

   export YTP_KEY="ytp_…"   # ключът от панела
   
   curl -sS "https://yt.kg-scripts.com/api/v1/jobs?wait=120" \
     -H "Authorization: Bearer $YTP_KEY" \
     -H "Content-Type: application/json" \
     -d '{"url": "https://youtu.be/jNQXAC9IVRw", "mode": "audio", "bitrate": 320}'

3. От отговора вземи file.signed_url и изтегли файла. Този линк не изисква ключ:
   bash

   curl -OJ "https://yt.kg-scripts.com/api/v1/files/CT4el5nMMU2I.1793027515.PaiFOjLd8oim630Jpj-E_NpD"

Ако видеото е дълго и не стане за 2 минути, отговорът идва със "status": "downloading". Тогава питай GET /jobs/{id}?wait=60, докато стане done.

Автентикация

Всяка заявка (освен /health, /openapi.json и подписаните линкове) изисква API ключ в хедър:

Authorization: Bearer ytp_sxpitw…Ew2w
# или
X-API-Key: ytp_sxpitw…Ew2w

Ключът е ytp_ + 43 случайни символа (256 бита). Сървърът не пази самия ключ, а само негов HMAC-SHA256 хеш, затова ключът се показва само веднъж, при създаване. Ако го загубиш, генерирай нов.

Управление на ключовете (в панела)

Права

GET /me работи с всеки валиден ключ. Без нужното право отговорът е 403 insufficient_scope. Давай на всеки ключ само правата, които наистина му трябват; за бот обикновено стига download.

Всеки ключ вижда само своите задачи. Чужда задача връща 404, сякаш не съществува.

Лимити

Всеки отговор с ключ носи текущото състояние на лимита:

X-RateLimit-Limit: 60        # заявки в минута за този ключ
X-RateLimit-Remaining: 59    # колко остават в момента
X-RateLimit-Reset: 1         # след колко секунди лимитът е пак пълен
Retry-After: 20              # само при 429: след колко секунди да опиташ пак

Лимитът на заявките е „кофа с жетони“: 60 в минута означава до 60 заявки наведнъж, после по една на секунда. При 429 винаги чакай колкото казва Retry-After.

Ограничения на видеата

• Само линкове от YouTube (youtube.com, youtu.be, music.youtube.com, Shorts) или 11-символно ID на видео.
• Без плейлисти и излъчвания на живо. Видеото трябва да е до 4 часа.
• Сървърът тегли до 2 файла едновременно за всички потребители; останалите задачи чакат на опашка (queue_position).
• Готовите файлове се пазят 60 минути, после задачата става expired.

Грешки

Всяка грешка има един и същ формат и подходящ HTTP статус:

{
  "error": {
    "code": "insufficient_scope",
    "message": "Ключът няма право „admin“.",
    "details": { "required": "admin", "granted": ["download"] }
  },
  "request_id": "req_d49e108786469149"
}

Проверявай error.code, не текста: съобщенията може да се променят, а кодовете остават.

Когато грешка възникне по време на изтеглянето (след като задачата е приета), заявката е успешна, а задачата е със "status": "error" и error.code от горната таблица (youtube_blocked, video_unavailable и т.н.).

Задачи и състояния

Всяко изтегляне е задача. Сървърът сам минава през маршрутите (директно → WARP → проксита → cookies), ако YouTube блокира някой от тях; опитите се виждат в attempts.

stage уточнява стъпката: queued, extracting, cached, downloading, merging, converting, cover, metadata, muting, finishing.

Как да чакаш

Не питай в цикъл без пауза. Ползвай параметъра wait (до 120 секунди): сървърът държи заявката отворена, докато задачата приключи или времето изтече, и чак тогава отговаря. Така една заявка на минута стига за всяко видео.

Изтегляне на файла

Когато задачата е done, обектът file дава два начина:

• Името на файла е в Content-Disposition (UTF-8, работи и с кирилица); с curl ползвай -OJ.
• Поддържа се Range, затова прекъснато изтегляне може да продължи (curl -C -, мениджъри за изтегляне).
• Подписаният линк спира да работи, ако ключът, създал задачата, бъде изключен или изтрит.
• Файлът се пази 60 минути от завършването. Изтегли го и го запиши при себе си.

Ендпойнти

{ "ok": true, "version": "1.0" }

curl -sS https://yt.kg-scripts.com/api/v1/me -H "Authorization: Bearer $YTP_KEY"

{
  "id": "key_06b66cabe167",
  "name": "Discord бот",
  "hint": "ytp_sxpitw…Ew2w",
  "scopes": ["download"],
  "created_at": "2026-10-26T14:11:45Z",
  "expires_at": "2027-01-24T14:11:45Z",
  "ip_allowlist": [],
  "limits": { "rate_per_min": 60, "jobs_per_hour": 30, "max_active": 3 },
  "usage": { "requests_total": 128, "active_jobs": 1, "jobs_last_hour": 4 }
}

curl -sS https://yt.kg-scripts.com/api/v1/info \
  -H "Authorization: Bearer $YTP_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://youtu.be/jNQXAC9IVRw"}'

{
  "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
  "video_id": "jNQXAC9IVRw",
  "title": "Me at the zoo",
  "uploader": "jawed",
  "duration_seconds": 19,
  "thumbnail": "https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg",
  "is_live": false,
  "live_status": "not_live",
  "formats": {
    "video": {
      "h264": [ { "quality": 240, "fps": 15, "size_bytes": 635110 }, { "quality": 144, "fps": 15, "size_bytes": 195278 } ],
      "vp9":  [ { "quality": 240, "fps": 15, "size_bytes": 293080 }, { "quality": 144, "fps": 15, "size_bytes": 185292 } ],
      "av1":  [ { "quality": 240, "fps": 15, "size_bytes": 223779 } ]
    },
    "audio": { "m4a_bytes": 309288, "opus_bytes": 252182 }
  },
  "route": "warp",
  "used_cookies": false,
  "cached_until": "2026-10-26T14:41:51Z"
}

curl -sS "https://yt.kg-scripts.com/api/v1/jobs?wait=60" \
  -H "Authorization: Bearer $YTP_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://youtu.be/aqz-KE-bpKQ", "mode": "video", "quality": "1080", "codec": "h264"}'

curl -sS "https://yt.kg-scripts.com/api/v1/jobs?wait=60" \
  -H "Authorization: Bearer $YTP_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://youtu.be/aqz-KE-bpKQ", "mode": "mute", "quality": "2160", "codec": "vp9"}'

curl -sS "https://yt.kg-scripts.com/api/v1/jobs?wait=60" \
  -H "Authorization: Bearer $YTP_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://youtu.be/jNQXAC9IVRw", "mode": "audio", "bitrate": 320}'

{
  "id": "CT4el5nMMU2I",
  "status": "done",
  "stage": "done",
  "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
  "video_id": "jNQXAC9IVRw",
  "title": "Me at the zoo",
  "thumbnail": "https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg",
  "options": { "mode": "audio", "quality": "max", "codec": "h264", "bitrate": 320 },
  "progress": {
    "percent": 100.0,
    "speed_bps": null,
    "eta_seconds": null,
    "streams": {
      "audio": { "downloaded_bytes": 252182, "total_bytes": 252182, "done": true, "percent": 100.0 }
    }
  },
  "queue_position": null,
  "route": "Cloudflare WARP",
  "attempts": [ { "route": "warp", "cookies": false, "result": "ok", "duration_ms": 3611 } ],
  "error": null,
  "file": {
    "name": "Me at the zoo.mp3",
    "size_bytes": 787656,
    "url": "https://yt.kg-scripts.com/api/v1/jobs/CT4el5nMMU2I/file",
    "signed_url": "https://yt.kg-scripts.com/api/v1/files/CT4el5nMMU2I.1793027515.PaiFOjLd8oim630Jpj-E_NpD",
    "expires_at": "2026-10-26T15:11:55Z"
  },
  "created_at": "2026-10-26T14:11:51Z",
  "finished_at": "2026-10-26T14:11:55Z"
}

{ "jobs": [ { "id": "CT4el5nMMU2I", "status": "done", "…": "…" } ], "total": 1 }

curl -sS "https://yt.kg-scripts.com/api/v1/jobs/CT4el5nMMU2I?wait=60" -H "Authorization: Bearer $YTP_KEY"

curl -sS -OJ https://yt.kg-scripts.com/api/v1/jobs/CT4el5nMMU2I/file -H "Authorization: Bearer $YTP_KEY"

{
  "routes": [
    {
      "name": "direct", "label": "Директно (IP на сървъра)", "proxy": null,
      "state": "cooling", "cooldown_seconds": 891,
      "exit_ip": "92.5.15.231", "location": "DE",
      "successes": 0, "consecutive_blocks": 1, "last_ok_at": null,
      "last_error": "Sign in to confirm you’re not a bot. This helps protect our community.",
      "last_error_at": "2026-10-26T14:11:47Z"
    },
    {
      "name": "warp", "label": "Cloudflare WARP", "proxy": "socks5://warp:1080",
      "state": "ok", "cooldown_seconds": 0,
      "exit_ip": "2a09:bac1:1e00:8::3a2:29", "location": "DE",
      "successes": 2, "consecutive_blocks": 0, "last_ok_at": "2026-10-26T14:11:55Z",
      "last_error": null, "last_error_at": null
    }
  ],
  "cookies": { "present": true, "youtube_cookies": 35, "logged_in": true, "uploaded_at": "2026-10-26T14:05:19Z", "valid": false },
  "agent": {
    "present": true, "alive": true, "ready": true, "browser": "running", "logged_in": true, "valid": true,
    "cookies_exported_at": "2026-10-26T17:02:10Z", "login_checked_at": "2026-10-26T17:02:10Z",
    "last_reload_at": "2026-10-26T16:41:03Z", "chromium": "Chrome/156.0.8078.47", "error": null
  },
  "cookies_in_use": "agent",
  "po_token": { "enabled": true, "ok": true, "version": "2.0.2" },
  "ytdlp": {
    "version": "2026.10.23.233055", "channel": "nightly", "updating": false,
    "last_update_at": "2026-10-26T14:11:46Z", "last_result": "Вече е последна версия (2026.10.23.233055)",
    "auto_update_hours": 12
  },
  "queue": { "active": 0, "waiting": 0, "max_concurrent": 2 }
}

curl -sS -X PATCH https://yt.kg-scripts.com/api/v1/settings \
  -H "Authorization: Bearer $YTP_ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{"proxies": ["socks5://user:pass@198.51.100.20:1080"], "cookies_mode": "fallback"}'

{
  "use_direct": true,
  "use_warp": true,
  "warp_available": true,
  "proxies": ["socks5://user:***@198.51.100.20:1080"],
  "env_proxies": [],
  "cookies_mode": "fallback",
  "cookies_source": "agent"
}

{
  "results": [
    { "route": "direct", "cookies": false, "result": "blocked", "duration_ms": 1962,
      "error": "Sign in to confirm you’re not a bot. This helps protect our community." },
    { "route": "warp", "cookies": false, "result": "ok", "duration_ms": 3991 }
  ],
  "routes": [ "…същият формат като в /status…" ]
}

curl -sS -X PUT https://yt.kg-scripts.com/api/v1/cookies \
  -H "Authorization: Bearer $YTP_ADMIN_KEY" -H "Content-Type: text/plain" \
  --data-binary @cookies.txt

{ "present": true, "youtube_cookies": 35, "logged_in": true, "uploaded_at": "2026-10-26T14:05:19Z", "valid": null, "agent_import": true }

{
  "version": "2026.10.23.233055",
  "channel": "nightly",
  "updating": false,
  "last_update_at": "2026-10-26T14:11:46Z",
  "last_result": "Вече е последна версия (2026.10.23.233055)",
  "auto_update_hours": 12
}

Примери с код

Цялостен пример: пуска задача, изчаква я с wait, спазва Retry-After при лимит и записва файла. Ключът се чете от променливата YTP_KEY, не е написан в кода.

# pip install requests
import os
import time

import requests

API = "https://yt.kg-scripts.com/api/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['YTP_KEY']}"


def call(method, path, **kwargs):
    while True:
        r = session.request(method, API + path, timeout=150, **kwargs)
        if r.status_code == 429:  # лимит: чакаме колкото казва сървърът
            time.sleep(int(r.headers.get("Retry-After", "5")))
            continue
        if r.status_code >= 400:
            err = r.json()["error"]
            raise RuntimeError(f"{err['code']}: {err['message']}")
        return r


def download(url, **options):
    job = call("POST", "/jobs", params={"wait": 60}, json={"url": url, **options}).json()
    while job["status"] in ("queued", "starting", "downloading", "processing"):
        job = call("GET", f"/jobs/{job['id']}", params={"wait": 60}).json()
    if job["status"] != "done":
        raise RuntimeError(f"{job['error']['code']}: {job['error']['message']}")

    with call("GET", f"/jobs/{job['id']}/file", stream=True) as r, open(job["file"]["name"], "wb") as out:
        for chunk in r.iter_content(1 << 20):
            out.write(chunk)
    return job["file"]["name"]


print(download("https://youtu.be/aqz-KE-bpKQ", mode="video", quality="1080", codec="h264"))
print(download("https://youtu.be/jNQXAC9IVRw", mode="audio", bitrate=320))

// Node.js 18+ (вграден fetch), запази като .mjs
import { createWriteStream } from "node:fs";
import { Readable } from "node:stream";
import { pipeline } from "node:stream/promises";

const API = "https://yt.kg-scripts.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.YTP_KEY}` };
const sleep = (s) => new Promise((r) => setTimeout(r, s * 1000));

async function call(method, path, body) {
  for (;;) {
    const res = await fetch(API + path, {
      method,
      headers: body ? { ...headers, "Content-Type": "application/json" } : headers,
      body: body && JSON.stringify(body),
    });
    if (res.status === 429) { await sleep(Number(res.headers.get("retry-after")) || 5); continue; }
    if (!res.ok) {
      const { error } = await res.json();
      throw new Error(`${error.code}: ${error.message}`);
    }
    return res;
  }
}

async function download(url, options = {}) {
  let job = await (await call("POST", "/jobs?wait=60", { url, ...options })).json();
  while (["queued", "starting", "downloading", "processing"].includes(job.status)) {
    job = await (await call("GET", `/jobs/${job.id}?wait=60`)).json();
  }
  if (job.status !== "done") throw new Error(`${job.error?.code}: ${job.error?.message}`);

  const file = await call("GET", `/jobs/${job.id}/file`);
  await pipeline(Readable.fromWeb(file.body), createWriteStream(job.file.name));
  return job.file.name;
}

console.log(await download("https://youtu.be/aqz-KE-bpKQ", { mode: "mute", quality: "720", codec: "vp9" }));
console.log(await download("https://youtu.be/jNQXAC9IVRw", { mode: "audio", bitrate: 192 }));

<?php
// PHP 8+ с разширение curl
const API = 'https://yt.kg-scripts.com/api/v1';

function ytp(string $method, string $path, ?array $body = null): array
{
    while (true) {
        $ch = curl_init(API . $path);
        $headers = ['Authorization: Bearer ' . getenv('YTP_KEY')];
        $opts = [CURLOPT_CUSTOMREQUEST => $method, CURLOPT_RETURNTRANSFER => true,
                 CURLOPT_TIMEOUT => 150, CURLOPT_HEADER => true];
        if ($body !== null) {
            $headers[] = 'Content-Type: application/json';
            $opts[CURLOPT_POSTFIELDS] = json_encode($body);
        }
        $opts[CURLOPT_HTTPHEADER] = $headers;
        curl_setopt_array($ch, $opts);
        $raw = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
        $head = substr($raw, 0, curl_getinfo($ch, CURLINFO_HEADER_SIZE));
        $data = json_decode(substr($raw, strlen($head)), true);
        curl_close($ch);

        if ($status === 429) {  // лимит: чакаме колкото казва сървърът
            preg_match('/^retry-after:\s*(\d+)/mi', $head, $m);
            sleep((int)($m[1] ?? 5));
            continue;
        }
        if ($status >= 400) {
            throw new RuntimeException($data['error']['code'] . ': ' . $data['error']['message']);
        }
        return $data;
    }
}

$job = ytp('POST', '/jobs?wait=60', ['url' => 'https://youtu.be/jNQXAC9IVRw', 'mode' => 'audio']);
while (in_array($job['status'], ['queued', 'starting', 'downloading', 'processing'], true)) {
    $job = ytp('GET', "/jobs/{$job['id']}?wait=60");
}
if ($job['status'] !== 'done') {
    exit($job['error']['message'] . PHP_EOL);
}

// подписаният линк не съдържа ключа: може да се даде директно на посетителя
echo $job['file']['signed_url'] . PHP_EOL;

#!/usr/bin/env bash
# употреба: YTP_KEY=ytp_… ./ytp.sh <линк> [video|mute|audio]
set -euo pipefail
API=https://yt.kg-scripts.com/api/v1
AUTH="Authorization: Bearer $YTP_KEY"

body=$(jq -n --arg url "$1" --arg mode "${2:-video}" '{url: $url, mode: $mode}')
job=$(curl -sS --fail-with-body "$API/jobs?wait=60" -H "$AUTH" -H 'Content-Type: application/json' -d "$body")
id=$(jq -r .id <<<"$job")

while [[ $(jq -r .status <<<"$job") =~ ^(queued|starting|downloading|processing)$ ]]; do
  job=$(curl -sS --fail-with-body "$API/jobs/$id?wait=60" -H "$AUTH")
done

if [[ $(jq -r .status <<<"$job") != done ]]; then
  jq -r '.error.code + ": " + .error.message' <<<"$job" >&2
  exit 1
fi
curl -sS -OJ "$(jq -r .file.signed_url <<<"$job")"
echo "Записано: $(jq -r .file.name <<<"$job")"

Сигурност

Какво прави сървърът

• Ключовете са 256-битови и се пазят само като HMAC-SHA256 хеш с таен ключ на сървъра. Изтекла база с ключове не стига, за да се ползват.
• Ключ, изпратен в URL, се изключва автоматично. Ключовете не се логват.
• Права по ключ, срок, списък с разрешени IP адреси и отделни лимити за всеки ключ.
• Блокиране на IP след 20 невалидни ключа за 10 минути, плюс лимит на заявките от IP на ниво nginx.
• Всеки ключ вижда само своите задачи и файлове. Подписаните линкове са HMAC подписани, изтичат с файла и спират с ключа.
• Журнал на всяка заявка (време, IP, ендпойнт, статус), видим в панела, плюс постоянен одит лог на сървъра.
• Ключовете се управляват само от панела, с потвърждение с парола. API ключ не може да създава или променя ключове.
• Строга проверка на входа: само линкове от YouTube, непознати полета се отказват, ограничени размери на заявките.
• Само HTTPS (TLS 1.2/1.3, HSTS). Панелът е защитен от CSRF, clickjacking и XSS (Content-Security-Policy).

Какво трябва да правиш ти

• Дръж ключа на сървъра, в променлива на средата или менажер на тайни. Никога не го слагай в код за браузър, мобилно приложение или публично хранилище.
• Отделен ключ за всяка програма, с минималните права. Ако нещо изтече, спираш само него.
• Ако програмата е на сървър със статичен IP, ограничи ключа до този IP.
• Слагай срок на ключовете и ги сменяй периодично („Нов таен ключ“).
• Ако видиш непознати IP адреси в журнала, натисни „Изключи“ веднага, после генерирай нов таен ключ.
• Давай на потребителите signed_url, не file.url с ключа.

OpenAPI

Машинно четимо описание на API-то, например за Postman, Insomnia или генератор на клиенти:

https://yt.kg-scripts.com/api/v1/openapi.json

В Postman: Import → Link, после в колекцията задай Authorization → Bearer Token с ключа.