PhumTech API v2.1 Docs
Service Operational
Web Downloader

YouTube Music API Documentation

Welcome to the official PhumTech YouTube to MP3 REST API. Easily convert YouTube tracks into high-fidelity .mp3 files with embedded ID3 artwork & track metadata for mobile apps, web services, and scripts.

โšก Key Features

  • 2-Step Fast Flow: Step 1 extracts instant track info; Step 2 downloads the MP3 file.
  • Custom Audio Bitrates: Supports 64k, 128k, 160k, 192k, 256k, and 320k (HQ).
  • Automatic ID3 Tagging: Embeds track title, artist name, and high-res cover art thumbnail directly into the downloaded .mp3 file.
  • Smart Link Sanitizer: Automatically cleans complex playlist parameters, mix radio links (&list=...&start_radio=1), YouTube Shorts, and youtu.be short links.
  • Universal CORS Enabled: Direct client-side calls allowed from Flutter, React Native, iOS, Android, and Web browsers.

๐Ÿš€ 2-Step Integration Workflow

The API separates metadata fetching from audio streaming so your app can show instant track previews to users before initiating the full download.

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” Step 1: GET /api/info?url=... โ”‚ โ”‚ โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–บ [ Return Track JSON Details ] โ”‚ Mobile / Web App โ”‚ โ”‚ โ”‚ โ”‚ Step 2: GET /api/download?url=...&quality=... โ–ผ โ”‚ โ”‚ โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–บ [ Stream MP3 Binary + ID3 Tags ] โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Step 1: Fetch Track Preview

Send a GET /api/info?url=... request. Returns title, artist, thumbnail URL, and available bitrates in milliseconds without downloading the audio file.

Step 2: Download & Stream MP3

Direct the user or media player to GET /api/download?url=...&quality=320k to download or stream the converted audio with proper filename headers.

๐Ÿ”‘ Authentication & Base URL

Base Production URL: https://music-downloader.phumtech.com

Public API endpoints (/api/info and /api/download) require no API keys or tokens. You can integrate directly into front-end clients, mobile apps, or backend servers.

GET /api/info

GET /api/info
Step 1: Fetch Track Metadata

Extracts track details (title, artist, cover image thumbnail, duration) from any YouTube link without downloading media.

Query Parameters

Parameter Type Required Description & Example
url string REQUIRED Full YouTube URL, short URL (youtu.be), Shorts, or 11-char ID.
e.g. https://www.youtube.com/watch?v=5SPzRfWHxo0

Sample Request & Response

{
  "status": "success",
  "data": {
    "id": "5SPzRfWHxo0",
    "title": "TEPPISETH - 4STARLOVE",
    "artist": "Tep Piseth",
    "duration": 265,
    "duration_formatted": "04:25",
    "thumbnail": "https://i.ytimg.com/vi/5SPzRfWHxo0/hqdefault.jpg",
    "url": "https://www.youtube.com/watch?v=5SPzRfWHxo0",
    "available_bitrates": [
      "64kbps",
      "128kbps",
      "160kbps",
      "192kbps",
      "256kbps",
      "320kbps (HQ)"
    ]
  }
}

GET /api/download

GET /api/download
Step 2: Stream MP3 Audio

Converts the requested YouTube video audio into MP3, embeds ID3 metadata tags (title, artist, artwork), and streams the binary file directly.

Query Parameters

Parameter Type Required Description & Options
url string REQUIRED Target YouTube URL or video ID.
quality string OPTIONAL Audio bitrate quality.
Options: 64k, 128k, 160k, 192k, 256k, 320k (Default: 320k).

Response Headers & Stream

200 OK โ€” Binary Stream (audio/mpeg)

Includes RFC 5987 formatted Content-Disposition header so browsers automatically save the file with the song's actual title:

HTTP Headers Output
HTTP/1.1 200 OK
Content-Type: audio/mpeg
Content-Disposition: attachment; filename="TEPPISETH - 4STARLOVE.mp3"; filename*=UTF-8''TEPPISETH%20-%204STARLOVE.mp3
Content-Length: 10612480
Access-Control-Expose-Headers: Content-Disposition

POST /api/convert

POST /api/convert
All-in-One Metadata & Download Link

Convenience endpoint for REST APIs that prefer JSON POST payloads. Returns track metadata together with the direct download URL endpoint.

JSON Request Body

application/json
{
  "url": "https://www.youtube.com/watch?v=5SPzRfWHxo0",
  "quality": "320k"
}

Sample Response

200 OK Response
{
  "status": "success",
  "metadata": {
    "id": "5SPzRfWHxo0",
    "title": "TEPPISETH - 4STARLOVE",
    "artist": "Tep Piseth",
    "duration_formatted": "04:25",
    "thumbnail": "https://i.ytimg.com/vi/5SPzRfWHxo0/hqdefault.jpg",
    "url": "https://www.youtube.com/watch?v=5SPzRfWHxo0"
  },
  "selected_quality": "320k",
  "download_url": "/api/download?url=https://www.youtube.com/watch?v=5SPzRfWHxo0&quality=320k"
}

๐Ÿ’ป Code Examples (Flutter, JS, Python, cURL)

Ready-to-use code snippets for mobile and backend developer integrations.

import 'package:http/http.dart' as http;
import 'dart:convert';

class MusicDownloaderService {
  static const String baseUrl = 'https://music-downloader.phumtech.com';

  // Step 1: Fetch Track Metadata
  static Future<Map<String, dynamic>?> fetchTrackInfo(String youtubeUrl) async {
    final uri = Uri.parse('$baseUrl/api/info?url=${Uri.encodeComponent(youtubeUrl)}');
    final response = await http.get(uri);

    if (response.statusCode == 200) {
      final json = jsonDecode(response.body);
      return json['data'];
    }
    return null;
  }

  // Step 2: Get Direct Download URL
  static String getDownloadUrl(String youtubeUrl, {String quality = '320k'}) {
    return '$baseUrl/api/download?url=${Uri.encodeComponent(youtubeUrl)}&quality=$quality';
  }
}

๐Ÿ›ก๏ธ Error Handling & Status Codes

All endpoints return standardized JSON errors when requests fail or YouTube experiences temporary load.

Status Code Reason Response Payload
400 Bad Request Missing or invalid YouTube URL parameter {"detail": "System is busy! Try again later."}
500 Internal Error Extraction timeout or system busy {"detail": "System is busy! Try again later."}

๐Ÿงช Interactive API Sandbox

Test GET /api/info Live

Response JSON

Response will appear here...