鉴权与边界
在请求头携带 API Key：
x-api-key: YOUR_API_KEY- 生产环境必须配置非空
API_KEYS。 -
浏览器跨域必须来自
ALLOWED_ORIGINS中的精确 HTTPS origin（本地开发可使用 localhost HTTP）。 -
/v1/*响应附带cache-control: no-store与x-attribution。 - 服务不代理媒体流，只返回经过安全检查的上游链接。
GET
/v1/music/sources
返回当前部署允许的音源。
响应示例
{
"data": ["netease", "joox", "bilibili"],
"meta": { "count": 3 }
}GET
/v1/music/search
搜索曲目或专辑元数据。
| 参数 | 类型 | 说明 |
|---|---|---|
source |
string |
必须在允许列表内，如 netease /
joox / bilibili
|
name |
string | 1–120 字符，搜索关键词 |
count |
int | 1–50，默认 20 |
page |
int | 1–1000，默认 1 |
album |
bool text |
true / false，默认 false；true
时映射受控 album 模式
|
示例
curl -G '__ORIGIN__/v1/music/search' \
-H 'x-api-key: YOUR_API_KEY' \
--data-urlencode 'source=joox' \
--data-urlencode 'name=love' \
--data-urlencode 'count=5'GET
/v1/music/url
解析播放地址。返回的 URL 会经过安全校验。
| 参数 | 类型 | 说明 |
|---|---|---|
source |
string | 允许音源 |
id |
string | 曲目 ID，禁止控制字符，最长 256 |
br |
enum |
128 192 320
740 999，默认 999
|
GET
/v1/music/picture
获取封面图片 URL。
| 参数 | 类型 | 说明 |
|---|---|---|
source |
string | 允许音源 |
id |
string |
封面 ID（通常来自搜索结果的 pictureId）
|
size |
enum | 300 或 500，默认 300 |
GET
/v1/music/lyrics
获取歌词与可选翻译歌词。
| 参数 | 类型 | 说明 |
|---|---|---|
source |
string | 允许音源 |
id |
string | 歌词 ID（通常来自搜索结果的 lyricId） |
响应字段
{
"data": {
"lyric": "...",
"translatedLyric": null
},
"meta": { "source": "joox", "id": "..." }
}运维端点
GET /healthz— 进程存活，匿名可访问。-
GET /readyz— 缓存与配额依赖就绪，匿名可访问。 -
GET /metrics— Prometheus 指标；需要Authorization: Bearer <METRICS_BEARER_TOKEN>，否则返回 404。
常见错误
| HTTP | code | 含义 |
|---|---|---|
| 400 | BAD_REQUEST |
参数校验失败 |
| 401 | UNAUTHORIZED |
缺少或错误的 API Key |
| 429 |
RATE_LIMITED /
UPSTREAM_QUOTA_EXHAUSTED
|
客户端限流或上游配额耗尽 |
| 502/503 | UPSTREAM_* |
上游不可用、响应无效或条款未确认 |