Free Music · 音频管理与分发系统

Free Music 提供标准的 RESTful API，任何支持 HTTP 请求的编程语言或框架均可接入。首页默认从数据库中随机展示 10 首未封锁音频，点击顶部“随机”按钮即可进入随机播放模式。

获取 API Token鉴权调用接口解析返回数据集成到应用

接口分类

鉴权接口（需 API Token）：上传音频、获取列表、搜索、获取详情
公开接口（无需 Token）：流式播放、随机音频（/api/audio/random）、歌单分页（/api/playlist）、总数统计（/api/total）
后台接口（需登录会话）：管理音频、日志、统计（仅限后台管理页面使用）

上传音频文件

POST /api/upload

HTTP

POST /api/upload HTTP/1.1
Host: your-domain
Authorization: Bearer YOUR_API_TOKEN
Content-Type: multipart/form-data

字段说明：
  file    (必填) 音频文件，≤20MB
  title   (可选) 标题，覆盖 TG 自动识别
  artist  (可选) 艺术家
  album   (可选) 专辑

成功响应：

JSON

{
  "success": true,
  "code": 200,
  "id": 12,
  "url": "https://your-domain/api/stream/12",
  "name": "song.mp3",
  "title": "My Song",
  "artist": "Artist",
  "format": "mp3",
  "size": 5242880,
  "duration": 180
}

返回字段说明

id	音频唯一标识，用于后续查询和播放
url	流式播放完整链接，可直接用于 audio 标签
format	文件格式（mp3/flac/wav 等）
size	文件大小（字节）
duration	时长（秒），部分格式可能为估算值

获取音频列表

GET /api/audio

HTTP

GET /api/audio?page=0&pageSize=20&sort=time&order=desc&format=mp3&q=keyword HTTP/1.1
Host: your-domain
Authorization: Bearer YOUR_API_TOKEN

查询参数：
  page      (默认0)     页码，从0开始
  pageSize  (默认20)    每页条数，最大100
  sort      (默认time)  排序：time / total / size / duration / title
  order     (默认desc)  方向：asc / desc
  format    (可选)      格式筛选，如 mp3 / flac
  q         (可选)      搜索关键词（匹配标题/艺术家/专辑/文件名）
  cursor    (可选)      上一页最后一条id，深页分页优化

获取音频详情

GET /api/audio/[id]

将 [id] 替换为音频 ID（如 12），返回该音频的完整元数据。

搜索音频

GET /api/audio/search?q=keyword

在 title / artist / album / file_name 字段上模糊匹配，支持分页参数。

公开接口（无需 Token）

GET /api/stream/[id]—流式播放，支持 HTTP Range 请求，可直接用于 audio 标签

GET /api/audio/random?exclude=<id>—随机获取一条未封锁的音频；可选 exclude 参数排除指定 ID，避免连续重复

GET /api/playlist?page=0&pageSize=20&sort=time&order=desc—歌单分页查询，返回 data / page / pageSize / total / totalPages / hasMore

GET /api/total—获取音频总数，返回 { success: true, total: number }

音频管理与分发系统

ラストダンスあなたと

[game]ラムネ（弹珠汽水）

Confident (Single Version)

Closer

上万种侮辱诋毁你的词语 ft.Feezy直火帮

Dizzy Tizzy

重生之小小的一片云

茶语山水

谪仙-橙光《沧海仙途》主题曲

여름의 속도

API 接入教程

上传音频文件

获取音频列表

获取音频详情

搜索音频

公开接口（无需 Token）