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, and320k (HQ). - Automatic ID3 Tagging: Embeds track title, artist name, and high-res cover art thumbnail directly into the downloaded
.mp3file. - Smart Link Sanitizer: Automatically cleans complex playlist parameters, mix radio links (
&list=...&start_radio=1), YouTube Shorts, andyoutu.beshort 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: 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
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
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
Includes RFC 5987 formatted Content-Disposition header so browsers automatically save the file with the song's actual title:
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
Convenience endpoint for REST APIs that prefer JSON POST payloads. Returns track metadata together with the direct download URL endpoint.
JSON Request Body
{
"url": "https://www.youtube.com/watch?v=5SPzRfWHxo0",
"quality": "320k"
}
Sample 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
GET /api/info Live
Response JSON
Response will appear here...