you-music/API_V1_README.md

YouMusic Public API v1

Public API endpoints for YouMusic that can be accessed with API key authentication.

Authentication

All v1 API endpoints require an API key passed in the X-API-Key header.

Getting an API Key

1. Log into YouMusic web interface
2. Navigate to Settings → API Keys
3. Click "Generate New Key"
4. Copy and save the generated key (starts with ym_)

Base URL

• Development: http://localhost:8000/api/v1
• Production: https://music.junv.cc/api/v1

Endpoints

Create Auto-Download Job

Create a new auto-download job to search and download a song.

Endpoint: POST /auto-download/job

Headers:

Content-Type: application/json
X-API-Key: your_api_key_here

Request Body:

{
  "song_name": "Shape of You - Ed Sheeran"
}

Response (201 Created):

{
  "id": 123,
  "song_name": "Shape of You - Ed Sheeran",
  "status": "pending",
  "search_results": null,
  "selected_result": null,
  "selected_result_index": null,
  "priority": false,
  "error_message": null,
  "music_id": null,
  "confirmed": false,
  "is_duplicate": false,
  "duplicate_music_id": null,
  "created_at": "2025-10-31T03:29:29.867851",
  "updated_at": "2025-10-31T03:29:29.867856"
}

Status Values:

• pending: Job created, waiting to start
• searching: Searching for the song
• downloading: Downloading the song
• completed: Download completed successfully
• failed: Download failed (check error_message)
• cancelled: Job was cancelled
• waiting_confirmation: Duplicate detected, needs confirmation

Get Job Status

Check the status of a download job.

Endpoint: GET /auto-download/jobs/{job_id}

Headers:

X-API-Key: your_api_key_here

Response (200 OK):

{
  "id": 123,
  "song_name": "Shape of You - Ed Sheeran",
  "status": "completed",
  "search_results": "[...]",
  "selected_result": "{...}",
  "selected_result_index": 0,
  "priority": true,
  "error_message": null,
  "music_id": 456,
  "confirmed": false,
  "is_duplicate": false,
  "duplicate_music_id": null,
  "created_at": "2025-10-31T03:29:29.867851",
  "updated_at": "2025-10-31T03:30:45.123456"
}

Features

Automatic Song Selection

The API automatically:

1. Searches YouTube and Bilibili
2. Filters out short clips (< 90 seconds) to avoid samples
3. Prioritizes results with "official" or "官方" in the title
4. Downloads the best match
5. Extracts metadata (title, artist, album, duration)
6. Stores in your music library

Duplicate Detection

If a song already exists in your library:

• Job status becomes waiting_confirmation
• is_duplicate is set to true
• duplicate_music_id contains the existing song's ID

Example Usage

cURL

# Create a download job
curl -X POST "https://music.junv.cc/api/v1/auto-download/job" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ym_your_api_key_here" \
  -d '{"song_name":"Bohemian Rhapsody - Queen"}'

# Check job status
curl "https://music.junv.cc/api/v1/auto-download/jobs/123" \
  -H "X-API-Key: ym_your_api_key_here"

Python

import requests

API_KEY = "ym_your_api_key_here"
BASE_URL = "https://music.junv.cc/api/v1"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# Create job
response = requests.post(
    f"{BASE_URL}/auto-download/job",
    json={"song_name": "Bohemian Rhapsody - Queen"},
    headers=headers
)
job = response.json()
print(f"Job created: {job['id']}")

# Check status
import time
while True:
    response = requests.get(
        f"{BASE_URL}/auto-download/jobs/{job['id']}",
        headers=headers
    )
    job = response.json()
    print(f"Status: {job['status']}")

    if job['status'] in ['completed', 'failed']:
        break

    time.sleep(5)

JavaScript/Node.js

const axios = require('axios');

const API_KEY = 'ym_your_api_key_here';
const BASE_URL = 'https://music.junv.cc/api/v1';

const headers = {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
};

// Create job
async function createJob(songName) {
    const response = await axios.post(
        `${BASE_URL}/auto-download/job`,
        { song_name: songName },
        { headers }
    );
    return response.data;
}

// Check status
async function getJobStatus(jobId) {
    const response = await axios.get(
        `${BASE_URL}/auto-download/jobs/${jobId}`,
        { headers }
    );
    return response.data;
}

// Usage
(async () => {
    const job = await createJob('Bohemian Rhapsody - Queen');

    while (true) {
        const status = await getJobStatus(job.id);

        if (['completed', 'failed'].includes(status.status)) {
            break;
        }

        await new Promise(resolve => setTimeout(resolve, 5000));
    }
})();

Error Responses

401 Unauthorized

{
  "detail": "API key required"
}

or

{
  "detail": "Invalid API key"
}

or

{
  "detail": "API key expired"
}

404 Not Found

{
  "detail": "Job not found"
}

Rate Limiting

Currently no rate limiting is enforced, but please be respectful:

• Don't create more than 10 jobs per minute
• Wait for jobs to complete before creating new ones for the same song

Support

For issues or questions:

• Check the main YouMusic documentation
• View API docs at /docs (Swagger UI)
• View job status in the web interface at /downloads

Changelog

v1.0.0 (2025-10-31)

• Initial public API release
• Auto-download job creation
• Job status checking
• API key authentication
• Duplicate detection
• 90-second minimum duration filter