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**:
```json
{
  "song_name": "Shape of You - Ed Sheeran"
}
```

**Response** (201 Created):
```json
{
  "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):
```json
{
  "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

```bash
# 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

```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

```javascript
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
```json
{
  "detail": "API key required"
}
```
or
```json
{
  "detail": "Invalid API key"
}
```
or
```json
{
  "detail": "API key expired"
}
```

### 404 Not Found
```json
{
  "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