MediaTools API
Docs Self‑hosted media downloader & converter API

MediaTools API Documentation

API ini menyediakan endpoint untuk download & preview media dari platform populer (TikTok, Instagram, Facebook, YouTube) serta konversi dokumen/gambar ke berbagai format. Dirancang tanpa autentikasi, cukup panggil endpoint yang kamu butuhkan dari frontend atau backend.

Base URL

http://localhost:3001/api

Sesuaikan PORT dengan nilai di .env ketika menjalankan server Express.

Health Check

GET /api/health

Respon: { "ok": true }

GET /tiktok/metadata

TikTok · Ambil metadata video

Endpoint ini melakukan scraping metadata video TikTok (judul, penulis, durasi, jumlah views, dan lain‑lain). Cocok digunakan untuk menampilkan detail sebelum user mengunduh video/audio atau gambar.

Query Parameters

application/json
url String Required

URL video TikTok yang valid. Bisa berupa link penuh (contoh: https://www.tiktok.com/@user/video/123) atau short link https://vm.tiktok.com/....

Returns

Mengembalikan objek TikTokMetadata jika sukses. Jika URL tidak valid atau scraping gagal, mengembalikan error JSON dengan kode status yang sesuai.

200 OK

Response body berisi metadata lengkap video (id, text, author, durasi, jumlah views, dll.).

Endpoint TikTok lainnya

  • GET /tiktok/preview-video — stream video untuk preview.
  • GET /tiktok/download — download video utama.
  • GET /tiktok/download-story — download konten story (jika tersedia).
  • GET /tiktok/download-image?url=<tiktok_url>&index=0 — download gambar untuk post foto/slide.
  • GET /tiktok/download-mp3 — download audio MP3 dari video.

Instagram · Post, Reels, Carousel & Stories

Post, reel, carousel: metadata lalu stream lewat mediaUrl. Stories: URL /stories/username/ID/ dan session backend (cookie) wajib.

Endpoint utama

  • GET /instagram/metadata?url=<instagram_url>
  • GET /instagram/preview-video?mediaUrl=<cdn_url_dari_metadata>
  • GET /instagram/download-video?mediaUrl=<cdn_url>
  • GET /instagram/preview-image?mediaUrl=<cdn_url>
  • GET /instagram/download-image?mediaUrl=<cdn_url>

Facebook · Video publik

Fokus pada download video dari postingan publik (Feed / Reels).

Endpoint utama

  • GET /facebook/metadata?url=<facebook_url>
  • GET /facebook/preview-video?url=<facebook_url>
  • GET /facebook/download?url=<facebook_url>

YouTube · Video & Audio

Mendukung preview, download video dengan pilihan kualitas, serta download audio MP3.

Endpoint utama

  • GET /youtube/metadata?url=<youtube_url>
  • GET /youtube/preview-video?url=<youtube_url>&quality=<itag>
  • GET /youtube/download?url=<youtube_url>&quality=<itag>
  • GET /youtube/download-mp3?url=<youtube_url>

Converter Dokumen & Gambar

Endpoint untuk konversi dokumen menggunakan multipart/form-data dengan field file "file".

Endpoint utama

  • POST /convert/document — konversi: PDF, DOCX, XLSX, PPTX, JPG, JPEG, PNG, WEBP, HTML/HTM ke PDF atau DOCX.
  • POST /convert/pdf-to-excel — PDF → XLSX.
  • POST /convert/pdf-to-ppt — PDF → PPTX.

file (form-data) — file yang akan dikonversi.

targetFormat (opsional, "pdf" atau "docx") — hanya untuk /convert/document.

Maksimum ukuran file ±50MB (dibatasi oleh konfigurasi Multer).

Error & Status Code

Pola error di seluruh endpoint relatif konsisten:

  • 400 Bad Request — URL tidak valid, format tidak didukung, atau kombinasi parameter salah.
  • 500 Internal Server Error — kegagalan konversi atau scraping di sisi server.
  • 502 Bad Gateway — gagal mengambil stream video/audio/gambar dari sumber.

Body error biasanya memiliki shape: {"{ error: string; message?: string; }"}