RESTful API Reference v2.0 (Node.js & Express)

Dokumentasi API ZellDownloader

Panduan lengkap integrasi API untuk Search (Pencarian), Download (Metadata & Link Unduhan), dan Play (Direct MP3 Streaming) siap pakai untuk Bot WhatsApp, Telegram, maupun Web Client.

🔑 Autentikasi 🛡️ Rate Limit & Whitelist 🔍 Search API 📥 Download API 🎵 Play API (Streaming) ⚠️ Error Codes

Aturan Autentikasi & Proteksi Password

Sistem proteksi password dikonfigurasi melalui variabel SITE_PASSWORD di file .env. Anda dapat memasukkan 1 password ataupun banyak password/token sekaligus dengan memisahkannya menggunakan tanda koma (contoh: SITE_PASSWORD=key_bot1,key_bot2,admin123).

Metode Pengiriman	Contoh Penggunaan	Keterangan
Query Parameter	`?apikey=YOUR_API_KEY` atau `?password=YOUR_API_KEY`	Paling mudah digunakan saat memanggil via browser atau bot URL.
HTTP Header	`x-auth-token: YOUR_API_KEY`	Direkomendasikan untuk request REST API server-to-server.
Bearer Token	`Authorization: Bearer YOUR_API_KEY`	Standar authorization header RFC 6750.
Browser Cookie	`Cookie: auth_token=YOUR_API_KEY`	Otomatis disimpan saat login melalui modal password di Web UI (aktif 7 hari).

💡 Catatan Penting: Endpoint Search (/api/search/...) bersifat 100% Bebas / Gratis (Public) tanpa memerlukan API key. Proteksi API key hanya diberlakukan pada saat mengeksekusi Download atau Play audio/video.

Rate Limiting & Whitelist IP (Proteksi Anti-Spam & DOS)

Untuk menjaga performa server tetap stabil dan aman saat SITE_PASSWORD dikosongkan/tidak digunakan, sistem dilengkapi dengan Rate Limiter in-memory mandiri dan fitur IP Whitelist.

Kategori Permintaan	Batas Bawaan	Pengaturan .env	Keterangan
Umum / Search / Info	60 req / menit	`RATE_LIMIT_MAX=60`	Membatasi permintaan pencarian dan metadata video.
Download & Play Media	15 req / menit	`RATE_LIMIT_DOWNLOAD_MAX=15`	Membatasi proses ekstraksi yt-dlp & ffmpeg yang memakan CPU/bandwidth.
Localhost & LAN Whitelist	UNLIMITED (Bebas)	`WHITELIST_LOCAL_IPS=true`	Otomatis membebaskan IP lokal (`127.0.0.1`, `::1`, subnet `192.168.x.x`, dll).
Custom Whitelist IPs	UNLIMITED (Bebas)	`WHITELIST_IPS=127.0.0.1, ...`	Daftar IP publik/admin yang dibebaskan dari segala bentuk batasan rate limit.

Cek Status Kuota Rate Limit IP Anda

GET /api/rate-limit

Kategori 1: Search API (Publik & Tanpa Key)

GET /api/search/youtube

Public (Tanpa API Key)

Alias: /search/youtube, /api/v1/search/youtube, /api/search?type=youtube, /search?type=youtube

Pencarian langsung video YouTube melalui Innertube API dengan kecepatan respons instan (~200ms). Mengembalikan link YouTube asli (https://www.youtube.com/watch?v=...).

Parameter	Tipe	Status	Default	Keterangan
q	string	Wajib	-	Kata kunci pencarian video / lagu YouTube. (Contoh: `sheila on 7 dan`)
limit	integer	Opsional	`8`	Jumlah maksimal hasil video (antara `1` hingga `20`).
type	string	Opsional	`all`	Pilihan filter: `all` (video umum & musik) atau `audio` (audio/lagu saja).

Contoh Request (cURL)

curl -X GET "http://localhost:8000/search/youtube?q=sheila+on+7+dan&limit=2"

Contoh Response Sukses (200 OK)

{
  "status": true,
  "process_time": "0.32s",
  "platform": "YouTube",
  "query": "sheila on 7 dan",
  "count": 2,
  "results": [
    {
      "title": "Sheila On 7 - Dan (Official Music Video)",
      "uploader": "Sony Music Entertainment Indonesia",
      "duration_str": "4:44",
      "thumbnail": "https://i.ytimg.com/vi/dGcGbF4ex5o/hqdefault.jpg",
      "url": "https://www.youtube.com/watch?v=dGcGbF4ex5o"
    },
    {
      "title": "Sheila On 7 - Dan (Lyric Video)",
      "uploader": "Sony Music Entertainment Indonesia",
      "duration_str": "4:42",
      "thumbnail": "https://i.ytimg.com/vi/Ch3l_Q9PxpQ/hqdefault.jpg",
      "url": "https://www.youtube.com/watch?v=Ch3l_Q9PxpQ"
    }
  ]
}

Kategori 2: Download API

GET /api/youtube

Perlu API Key jika aktif

Alias: /youtube, /api/download/youtube, /download/youtube, /api/v1/youtube

Mengambil metadata video YouTube, direct link download, dan inline link stream. Jika parameter download=true diberikan, endpoint ini langsung mengalirkan binary file unduhan ke client (attachment). Jika stream=true, server langsung streaming media secara inline dengan HTTP Range support.

Parameter	Tipe	Status	Default	Keterangan
url	string	Wajib salah satu	-	Link video YouTube (contoh: `https://www.youtube.com/watch?v=dGcGbF4ex5o` atau `https://youtu.be/...`).
q	string	Wajib salah satu	-	Alternatif jika tidak membawa URL: Judul lagu / video YouTube yang dicari.
type	string	Opsional	`mp3`	Pilihan format: `mp3` (Audio) atau `mp4` (Video).
quality	string	Opsional	`192k` / `720p`	Bitrate audio jika mp3 (`320k`, `256k`, `192k`, `128k`) atau resolusi video jika mp4 (`1080p`, `720p`, `480p`, `360p`).
download	boolean	Opsional	`false`	Jika `false`: kembalikan JSON info & link `download`. Jika `true`: server langsung streaming file unduhan (attachment).
stream	boolean	Opsional	`false`	Jika `true`: server langsung streaming media inline (support range & seek audio/video player).
apikey	string	Kondisional	-	Wajib diisi dengan nilai `SITE_PASSWORD` jika sistem memproteksi aksi unduhan.

1. Contoh Request Mendapatkan JSON & link download

curl -X GET "http://localhost:8000/youtube?url=https://www.youtube.com/watch?v=dGcGbF4ex5o&type=mp3&apikey=YOUR_API_KEY"

Contoh Response JSON (200 OK)

{
  "status": true,
  "process_time": "1.25s",
  "creator": "ZellRayy",
  "platform": "YouTube",
  "type": "audio",
  "result": {
    "id": "dGcGbF4ex5o",
    "title": "Sheila On 7 - Dan (Official Music Video)",
    "uploader": "Sony Music Entertainment Indonesia",
    "duration": 284,
    "duration_str": "4:44",
    "thumbnail": "https://i.ytimg.com/vi/dGcGbF4ex5o/hqdefault.jpg",
    "filename": "Sheila On 7 - Dan (Official Music Video) - ZellRayy.mp3",
    "filesize": 11283040,
    "url": "https://www.youtube.com/watch?v=dGcGbF4ex5o",
    "download": "http://localhost:8000/downloads/Sheila%20On%207%20-%20Dan%20(Official%20Music%20Video)%20-%20ZellRayy.mp3",
    "stream": "http://localhost:8000/stream/Sheila%20On%207%20-%20Dan%20(Official%20Music%20Video)%20-%20ZellRayy.mp3"
  }
}

2. Contoh Request Langsung Download File Media

curl -L "http://localhost:8000/youtube?url=https://www.youtube.com/watch?v=dGcGbF4ex5o&type=mp3&download=true&apikey=YOUR_API_KEY" --output "lagu.mp3"

Kategori 3: Play API (JSON Info & Instant YouTube Stream)

Router Play secara default mengembalikan respons JSON berisi metadata YouTube lengkap, link unduh, dan direct inline stream (field stream & download). Bila parameter download=true diberikan, server akan langsung mengalirkan file audio MP3 sebagai attachment. Bila stream=true, server langsung streaming media secara inline dengan HTTP Range support.

GET /api/ytplay

Perlu API Key jika aktif

Alias: /ytplay, /play, /api/play, /api/v1/ytplay, /api/v1/play

Mencari lagu di YouTube. Secara default mengembalikan JSON metadata beserta direct link download dan inline link stream. Jika download=true, server langsung streaming file audio MP3 (attachment). Jika stream=true, server langsung streaming audio inline (support range & seek audio player).

Parameter	Tipe	Status	Default	Keterangan
q	string	Wajib salah satu	-	Judul lagu YouTube yang dicari (contoh: `sheila on 7 dan`).
url	string	Wajib salah satu	-	Alternatif: URL video YouTube asli.
quality	string	Opsional	`320k`	Kualitas audio MP3: `320k`, `256k`, atau `128k`.
download	boolean	Opsional	`false`	`false` = kembalikan JSON info & link `download`. `true` = langsung stream/unduh file audio MP3 (attachment).
stream	boolean	Opsional	`false`	Jika `true`: server langsung streaming audio inline (support range & seek audio player).
apikey	string	Kondisional	-	Wajib diisi dengan nilai `SITE_PASSWORD` jika sistem diproteksi.

1. Contoh Request (Mendapatkan JSON & Link Download)

curl -X GET "http://localhost:8000/ytplay?q=sheila+on+7+dan&apikey=YOUR_API_KEY"

Contoh Response JSON (200 OK)

{
  "status": true,
  "process_time": "1.10s",
  "creator": "ZellRayy",
  "platform": "YouTube",
  "type": "audio",
  "result": {
    "id": "dGcGbF4ex5o",
    "title": "Sheila On 7 - Dan (Official Music Video)",
    "uploader": "Sony Music Entertainment Indonesia",
    "duration": 284,
    "duration_str": "4:44",
    "thumbnail": "https://i.ytimg.com/vi/dGcGbF4ex5o/hqdefault.jpg",
    "filename": "Sheila On 7 - Dan (Official Music Video) - ZellRayy.mp3",
    "filesize": 11283040,
    "url": "https://www.youtube.com/watch?v=dGcGbF4ex5o",
    "download": "http://localhost:8000/downloads/Sheila%20On%207%20-%20Dan%20(Official%20Music%20Video)%20-%20ZellRayy.mp3",
    "stream": "http://localhost:8000/stream/Sheila%20On%207%20-%20Dan%20(Official%20Music%20Video)%20-%20ZellRayy.mp3"
  }
}

2. Contoh Request Langsung Stream MP3 File (download=true)

curl -L "http://localhost:8000/ytplay?q=sheila+on+7+dan&download=true&apikey=YOUR_API_KEY" --output "Dan.mp3"

Standar Respon Error

Semua respons error dikembalikan dalam format JSON terstruktur dengan HTTP Status Code yang sesuai.

Status Code	Penyebab Error	Format Respons JSON
400 Bad Request	Parameter wajib tidak disertakan (misal parameter `q` atau `url` kosong).	`{"status": false, "error": "Query parameter 'q' is required"}`
401 Unauthorized	`SITE_PASSWORD` aktif tetapi request tidak menyertakan `apikey` yang valid.	`{"status": false, "error": "Unauthorized: Akses ditolak. Masukkan token atau password yang valid."}`
429 Too Many Requests	Batas laju permintaan (Rate Limit) terlampaui. Disertai header `Retry-After`.	`{"status": false, "error": "Terlalu banyak permintaan (Rate limit terlampaui)...", "retry_after": 35}`
404 Not Found	Tidak ditemukan video / track lagu untuk query yang dicari.	`{"status": false, "error": "No track found for: xyz..."}`
500 Internal Error	Kendala saat proses ekstraksi yt-dlp atau konversi ffmpeg.	`{"status": false, "error": "Failed to download media..."}`