专辑模块 API 接口文档(api_v1)
基本信息
- 基础路径:
/api_v1/album - 数据格式: JSON
- 认证方式: API Key
鉴权说明
所有接口均使用 API Key 鉴权,在请求头中传入:
Authorization: Bearer <api_key>
Content-Type: application/x-www-form-urlencoded注意:
- API Key 通过/api_v1/apikey/create接口创建(需先通过 OAuth 2.0 Bearer Token 认证)
- 与api_v2使用 OAuth 2.0 Bearer Token 不同,api_v1使用的是 API Key
通用响应格式
{
"code": 1,
"msg": "success",
"data": null
}| 字段 | 类型 | 说明 |
|---|---|---|
| code | int | 1=成功,0=失败,401=未授权 |
| msg | string | 提示信息 |
| data | mixed | 返回数据,错误时为 null |
1. 保存步骤1:基本信息
POST /api_v1/album/saveBasicInfo
保存专辑步骤1的基本信息(新建或更新)。
请求参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| album_id | int | 否 | 专辑ID,更新时传入,默认 0(新建) |
| name_cn | string | 否 | 中文名称 |
| version | string | 否 | 版本 |
| artists | string | 是 | 主要艺人列表,JSON 数组字符串,如 ["许嵩", "周杰伦"] |
| genre_main | int | 是 | 音乐风格下标,对应 music_style_cn() 数组索引,如 0=另类音乐 |
| language | int | 是 | 语言下标,对应 album_language(2) 数组索引,如 0=简体中文(Chinese) |
| label | string | 是 | 厂牌名字(非ID),需与 think_label 表中当前用户的厂牌名称一致 |
| cover_path | string | 是 | 封面 OSS 路径 |
| dynamic_cover_1_1 | string | 否 | 动态封面 1:1 比例 OSS 路径 |
| dynamic_cover_3_4 | string | 否 | 动态封面 3:4 比例 OSS 路径 |
| first_release_date | string | 是 | 首次发行日期(格式:YYYY-MM-DD),如 "2025-01-01" |
| expected_release_date | string | 是 | 预期发行日期(格式:YYYY-MM-DD),如 "2025-02-01" |
| release_status | int | 是 | 发行状态:0=尚未发行,1=已经发行 |
| p_line_year | string | 是 | P Line 年份,如 "2025" |
| p_line | string | 是 | P Line 版权信息,如 "2025 某某唱片公司" |
| c_line_year | string | 是 | C Line 年份,如 "2025" |
| c_line | string | 是 | C Line 版权信息,如 "2025 某某文化传媒公司" |
| message | string | 否 | 留言(给审核人员) |
| upc_ean | string | 否 | UPC/EAN 编码 |
| description | string | 否 | 专辑描述 |
| featuring_json | string | 否 | Featuring 艺人列表,JSON 数组字符串,如 ["艺名1","艺名2"] |
| localized_languages | string | 否 | 本地化语言 JSON 数组字符串。可为空;格式 [{"title":"标题","language":下标}],language 为 album_language(2) 的数组下标。不传默认为 "[]" |
genre_main 参数说明:
用户传入 music_style_cn() 数组的下标(从 0 开始),后台根据下标从 music_style_en() 取英文值同时存入 genre_main 和 genre_sub。示例:
genre_main=0 → music_style_cn()[0]="另类音乐" → music_style_en()[0]="alternative"language 参数说明:
用户传入 album_language(2) 数组的下标(从 0 开始),后台根据下标取值存入数据库。可选值可通过 /api_v1/index/albumLanguage 接口获取。示例:
language=0 → album_language(2)[0]="简体中文(Chinese)"
language=2 → album_language(2)[2]="英语(English)"artists 参数说明:
artists 为 JSON 数组字符串,至少包含一个非空艺人。示例:
artists=["许嵩","周杰伦"]featuring_json 参数说明:
Featuring 艺人(合作艺人)列表,需传 JSON 数组字符串。featuring 中的艺人不能与主要艺人重复。示例:
featuring_json=["feat_艺人1","feat_艺人2"]localized_languages 参数说明:
本地化语言专辑标题列表,需传 JSON 数组字符串。language 为 album_language(2) 的下标,后台自动转换为对应的语言名称存入数据库。示例:
localized_languages=[{"title":"测试繁体","language":1},{"title":"测试","language":2}]验证规则:
| 字段 | 规则 | 说明 | ||
|---|---|---|---|---|
| name_cn | max:100 | 中文名称不超过100个字符 | ||
| version | max:100 | 版本不超过100个字符 | ||
| genre_main | `require\ | number` | 音乐风格下标必填,下标越界则报错 | |
| language | `require\ | number` | 语言下标必填,下标越界则报错 | |
| label | require | 厂牌名字必填,需在 think_label 表中存在 | ||
| cover_path | require | 封面必填 | ||
| first_release_date | `require\ | regex:/^\d{4}-\d{2}-\d{2}$/` | 必填,格式 YYYY-MM-DD | |
| expected_release_date | `require\ | regex:/^\d{4}-\d{2}-\d{2}$/` | 必填,格式 YYYY-MM-DD | |
| release_status | `require\ | in:0,1` | 必填,仅允许 0 或 1 | |
| p_line_year | `require\ | number\ | between:1900,2100` | 必填,数字,1900-2100 |
| p_line | `require\ | max:200` | 必填,不超过200个字符 | |
| c_line_year | `require\ | number\ | between:1900,2100` | 必填,数字,1900-2100 |
| c_line | `require\ | max:200` | 必填,不超过200个字符 | |
| upc_ean | max:30 | 不超过30个字符 | ||
| artists | 业务校验 | JSON 数组字符串,至少包含一个非空艺人 | ||
| featuring_json | 业务校验 | JSON 数组字符串,艺人不能与主要艺人重复 | ||
| localized_languages | 业务校验 | 可为空;有内容时校验 JSON 格式、title 必填、language 为 album_language(2) 的有效下标 |
成功响应:
{
"code": 1,
"msg": "保存成功",
"data": {
"album_id": 123
}
}错误响应:
{
"code": 0,
"msg": "音乐风格不在可选范围内"
}{
"code": 0,
"msg": "语言不在可选范围内"
}{
"code": 0,
"msg": "P线年份必须在1900-2100之间"
}{
"code": 0,
"msg": "发行状态值无效,请传入 0 或 1"
}{
"code": 0,
"msg": "厂牌「某某唱片」不存在,请先创建"
}{
"code": 0,
"msg": "请至少添加一个主要艺人"
}{
"code": 0,
"msg": "featuring 艺人不能与主要艺人重复"
}{
"code": 0,
"msg": "创建专辑失败"
}鉴权错误响应:
{
"code": 0,
"msg": "请提供有效的 API Key",
"data": null,
"url": "",
"wait": 401
}{
"code": 0,
"msg": "API Key 无效或已被禁用",
"data": null,
"url": "",
"wait": 401
}业务逻辑:
| 场景 | 行为 |
|---|---|
| 新建 | album_id 为 0 或不传 → 新增一条 status = draft 的专辑记录 → 返回新专辑 ID |
| 更新 | 传入 album_id > 0 → 校验归属(user_id 匹配)及专辑状态(pending/published/unpublished 不可修改)→ 更新记录 → 返回原专辑 ID |
| 事务 | 使用数据库事务,任何步骤失败自动回滚 |
存储字段映射:
| 请求参数 | 数据库字段 | 存储格式 |
|---|---|---|
| artists | artists | JSON数组(过滤空值后按顺序重新索引) |
| featuring_json | featuring | JSON数组(过滤空值) |
| localized_languages | localized_languages | JSON数组(language 下标 → 语言名称) |
| label | label_id | 字符串(厂牌名字,非ID) |
| release_status | release_status | 中文:0→"尚未发行",1→"已经发行" |
| genre_main | genre_main | 英文(通过下标查 music_style_en()) |
| — | genre_sub | 英文(与 genre_main 相同) |
| language | language | 字符串(通过下标查 album_language(2)) |
| message | message | 字符串(留言) |
2. 保存歌曲信息
POST /api_v1/album/saveSong
为指定专辑添加或更新歌曲。
请求参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| album_id | int | 是 | 所属专辑ID |
| song_id | int | 否 | 歌曲ID,更新时传入,默认 0(新建) |
| song_titles | string | 是 | 歌曲名称,如 "晴天"。后台转为 [{"title":"晴天"}] 格式存储 |
| version | string | 否 | 版本 |
| genre_main | int | 是 | 音乐风格下标,同 saveBasicInfo,对应 music_style_cn() 索引 |
| language | int | 是 | 语言下标,对应 album_language(1) 数组索引 |
| song_artists | string | 是 | 歌曲艺人 JSON 对象字符串,见下方详细说明 |
| audio_path | string | 否 | 音频 OSS 路径 |
| explicit_flag | string | 否 | 脏标,默认 "无脏标",有脏标请传入 "有脏标" |
| lyrics | string | 条件必填 | 歌词,语言下标=0 时可不填,不超过10000字符 |
| catalog_number | string | 否 | 目录编号 |
| isrc | string | 否 | ISRC 编码 |
| localized_languages | string | 否 | 本地化语言 JSON 数组,language 为下标,同 saveBasicInfo,默认为 "[]" |
song_artists 参数说明:
song_artists 为 JSON 对象字符串,包含以下字段:
| 字段 | 必填 | 说明 |
|---|---|---|
| performer | 是 | 主要艺人,如 "周杰伦" |
| composer | 是 | 作曲,多个用逗号分隔,如 "浩林,周杰伦" |
| lyricist | 条件必填 | 歌词作者,语言下标=0 时可不填 |
| producer | 是 | 制作人 |
| arranger | 否 | 编曲 |
| featuring | 否 | 合作艺人 |
示例:
song_artists={"performer":"周杰伦","composer":"浩林,周杰伦","lyricist":"方文山","producer":"周杰伦","arranger":"林迈可","featuring":""}艺人姓名校验规则:
每个多人字段(composer、lyricist 等)以逗号分隔多个艺人,每个艺人姓名单独校验:
| 语言类型 | 规则 | 示例 |
|---|---|---|
| 中文 | 不少于 2 个汉字 | "周" 拒绝,"周杰伦" 通过 |
| 英文 | 完整名+姓,首字母大写 | "John" 拒绝,"John Smith" 通过 |
| 混合 | 禁止中英混排 | "John 周杰伦" 拒绝 |
| 其他 | 不少于 2 个字符,必须包含字母 | "가나" 通过,"123" 拒绝 |
验证规则:
| 字段 | 规则 | 说明 | |
|---|---|---|---|
| album_id | `require\ | number` | 专辑ID必填,必须为数字 |
| version | max:100 | 版本不超过100个字符 | |
| genre_main | `require\ | number` | 音乐风格下标必填,下标越界则报错 |
| language | `require\ | number` | 语言下标必填,下标越界则报错 |
| audio_path | max:255 | 音频路径不超过255个字符 | |
| song_artists | max:2000 | 歌曲艺人JSON不超过2000个字符 | |
| song_titles | max:2000 | 歌曲名称不超过2000个字符 | |
| explicit_flag | max:50 | 脏标不超过50个字符 | |
| lyrics | max:10000 | 歌词不超过10000个字符 | |
| pline | — | 后端自动生成(拼接专辑 p_line_year p_line),前端无需提交 | |
| cline | — | 后端自动生成(拼接专辑 c_line_year c_line),前端无需提交 | |
| catalog_number | max:100 | 目录编号不超过100个字符 | |
| isrc | max:50 | ISRC编码不超过50个字符 | |
| localized_languages | max:5000 | 本地化语言不超过5000个字符 | |
| song_titles | 业务校验 | 不能为空 | |
| song_artists | 业务校验 | JSON 对象,必填字段见上方;艺人姓名需通过校验规则 | |
| lyrics | 业务校验 | 语言下标≠0 时必填 |
成功响应:
{
"code": 1,
"msg": "保存成功",
"data": {
"song_id": 456
}
}错误响应:
{
"code": 0,
"msg": "请至少添加一个歌曲名称"
}{
"code": 0,
"msg": "创建专辑失败"
}{
"code": 0,
"msg": "艺人中文姓名「周」需不少于2个汉字"
}{
"code": 0,
"msg": "艺人英文姓名「John」需包含完整的名+姓,且首字母大写"
}{
"code": 0,
"msg": "请添加作曲"
}{
"code": 0,
"msg": "请添加歌曲艺人"
}业务逻辑:
| 场景 | 行为 |
|---|---|
| 新建 | song_id 为空或 0 → 新增一条 status=draft 的歌曲记录,自动计算 sort 排序 |
| 更新 | 传入 song_id > 0 → 校验歌曲归属(album_id、user_id 匹配)→ 更新对应歌曲记录 |
| 状态限制 | 专辑状态为 pending/published/unpublished 时不可新增或修改歌曲 |
| 事务 | 使用数据库事务,失败自动回滚 |
存储字段映射:
| 请求参数 | 数据库字段 | 存储格式 |
|---|---|---|
| song_titles | song_titles | JSON数组 [{"title":"..."}] |
| song_artists | song_artists | JSON对象 |
| lyrics | lyrics | 字符串 |
| — | pline | 字符串(拼接专辑 p_line_year p_line) |
| — | cline | 字符串(拼接专辑 c_line_year c_line) |
| localized_languages | localized_languages | JSON数组(language 下标 → 语言名称) |
| genre_main | genre_main | 英文(通过下标查 music_style_en()) |
| — | genre_sub | 英文(与 genre_main 相同) |
| language | language | 字符串(通过下标查 album_language(1)) |
| album_id | album_id | 整数 |
| sort | sort | 自动计算(按专辑内歌曲数量) |
3. 提交审核
POST /api_v1/album/submitPublish
将已保存完整的专辑提交审核,状态从 draft / rejected 变更为 pending。
请求参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| album_id | int | 是 | 专辑ID |
校验规则:
| 校验项 | 说明 |
|---|---|
| 专辑归属 | album_id 必须属于当前用户 |
| 状态限制 | 状态为 pending 或 published 时不可重复提交 |
| 歌曲数量 | 至少包含一首歌曲 |
| 单曲一致性 | 专辑仅一首歌曲时:专辑名=歌曲名、音乐风格一致、主要艺人及 featuring 与歌曲一致 |
成功响应:
{
"code": 1,
"msg": "提交审核成功",
"data": []
}错误响应:
{
"code": 0,
"msg": "专辑不存在或您没有权限"
}{
"code": 0,
"msg": "该专辑已经提交或已发布,不能重复操作"
}{
"code": 0,
"msg": "请至少添加一首歌曲"
}业务逻辑:
| 操作 | 行为 |
|---|---|
| 提交审核 | status 从 draft 或 rejected → pending,更新 updated_at |
4. 获取专辑及歌曲列表
GET /api_v1/album/songs
查询专辑信息和歌曲列表。该接口为 GET 请求。
请求参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| album_id | int | 是 | 专辑ID |
成功响应:
{
"code": 1,
"msg": "",
"data": {
"album": {
"id": 1,
"user_id": 1,
"name_cn": "测试专辑",
"version": "",
"cover_path": "/uploads/cover/abc.jpg",
"dynamic_cover_1_1": "",
"dynamic_cover_3_4": "",
"genre_main": "pop",
"genre_sub": "pop",
"artists": ["许嵩", "周杰伦"],
"featuring": ["feat_艺人1"],
"language": "简体中文(Chinese)",
"label_id": "某某唱片",
"first_release_date": "2025-01-01",
"expected_release_date": "2025-02-01",
"release_status": "尚未发行",
"p_line_year": "2025",
"p_line": "2025 某某唱片公司",
"c_line_year": "2025",
"c_line": "2025 某某文化传媒公司",
"message": "",
"upc_ean": "",
"description": "",
"localized_languages": [
{"title": "测试繁体", "language": "繁体中文(Traditional)"},
{"title": "Test", "language": "英语(English)"}
],
"status": "draft",
"updated_at": "2025-01-15 10:30:00",
"created_at": "2025-01-15 10:00:00"
},
"songs": [
{
"id": 10,
"album_id": 1,
"user_id": 1,
"version": "",
"genre_main": "pop",
"genre_sub": "pop",
"audio_path": "/uploads/audio/xyz.mp3",
"language": "中文(Chinese)",
"song_artists": {
"performer": "周杰伦",
"composer": "浩林,周杰伦",
"lyricist": "方文山",
"producer": "周杰伦",
"arranger": "林迈可",
"featuring": "",
...
},
"song_titles": "晴天",
"explicit_flag": "无脏标",
"lyrics": "歌词内容...",
"pline": "",
"cline": "",
"catalog_number": "",
"isrc": "",
"localized_languages": [],
"sort": 0,
"updated_at": "2025-01-15 10:30:00",
"created_at": "2025-01-15 10:00:00"
}
]
}
}songs 数组按 sort 升序排列。
错误响应:
{
"code": 0,
"msg": "专辑不存在"
}5. 删除歌曲
POST /api_v1/album/deleteSong
删除指定歌曲。
请求参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| song_id | int | 是 | 歌曲ID |
| album_id | int | 是 | 所属专辑ID |
校验规则:
| 校验项 | 说明 |
|---|---|
| 歌曲归属 | song_id 必须属于该专辑且属于当前用户 |
| 专辑归属 | album_id 必须属于当前用户 |
| 状态限制 | 专辑状态为 pending/published/unpublished 时不可删除歌曲 |
成功响应:
{
"code": 1,
"msg": "删除成功",
"data": []
}错误响应:
{
"code": 0,
"msg": "歌曲不存在或无权操作"
}6. 更新歌曲排序
POST /api_v1/album/updateSongSort
按传入的歌曲ID顺序更新歌曲的 sort 排序。
请求参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| album_id | int | 是 | 专辑ID |
| song_ids | array/string | 是 | 歌曲ID数组,按新顺序排列,如 [3,1,2];也支持 JSON 数组字符串 "[3,1,2]" |
校验规则:
| 校验项 | 说明 |
|---|---|
| 专辑归属 | album_id 必须属于当前用户 |
| ID 有效性 | song_ids 中所有ID必须属于该专辑下的歌曲 |
| 状态限制 | 专辑状态为 pending/published/unpublished 时不可调整歌曲排序 |
成功响应:
{
"code": 1,
"msg": "排序保存成功",
"data": []
}错误响应:
{
"code": 0,
"msg": "专辑不存在"
}{
"code": 0,
"msg": "歌曲参数错误"
}7. 删除专辑
POST /api_v1/album/delete
删除指定专辑及其下所有歌曲,并清理 OSS 上的专辑封面与所有歌曲音频文件。
请求参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| album_id | int | 是 | 专辑ID |
校验规则:
| 校验项 | 说明 |
|---|---|
| 专辑归属 | album_id 必须属于当前用户 |
| 状态限制 | 专辑状态为 pending/published/unpublished 时不可删除 |
成功响应:
{
"code": 1,
"msg": "删除成功",
"data": []
}错误响应:
{
"code": 0,
"msg": "专辑不存在或您没有权限"
}附录
访问路径
GET /api_v1/album/songs
POST /api_v1/album/saveBasicInfo
POST /api_v1/album/saveSong
POST /api_v1/album/submitPublish
POST /api_v1/album/deleteSong
POST /api_v1/album/updateSongSort
POST /api_v1/album/delete与 api_v2 对比
| 项目 | api_v1 | api_v2 |
|---|---|---|
| 基础路径 | /api_v1/album | /api_v2/album |
| 鉴权方式 | API Key | OAuth 2.0 Bearer Token |
| 鉴权请求头 | Authorization: Bearer <api_key> | Authorization: Bearer <token> |
| 风格传值 | int 下标 | string 中文名 |
| 接口数量 | 7(持续增加中) | 22 |
数据参考
1. 音乐风格列表 (music_style_cn)
用户通过下标(从 0 开始)传入。后台查 music_style_en() 存英文。
0: 另类音乐
1: 另类音乐 : 独立流行
2: 另类音乐 : 独立摇滚
3: 另类音乐 : 摇滚
4: 氛围 : 新世纪
5: 氛围 : 新世纪/冥想
6: 动漫
7: 蓝调
8: 蓝调 : 传统蓝调
9: 儿童音乐
10: 儿童音乐 : 经典
11: 儿童音乐 : 节日
12: 儿童音乐 : 故事
13: 中文 : 中国古典
14: 中文 : 中国笛子
15: 中文 : 中国地方民歌
16: 中文 : 中国弦乐
17: 古典
18: 古典 : 古风
19: 古典 : 巴洛克
20: 古典 : 室内乐
21: 古典 : 音乐会
22: 古典 : 现代作品
23: 古典 : 歌剧
24: 古典 : 管弦乐
25: 古典 : 钢琴
26: 古典 : 浪漫主义
27: 喜剧
28: 乡村
29: 乡村 : 蓝草
30: 乡村 : 当代
31: 乡村 : 酒吧音乐
32: 乡村 : 纳什维尔
33: 乡村 : 流行
34: 乡村 : 广场舞
35: 轻音乐
36: 电子
37: 实验
38: 民谣
39: 放克 : R&B
40: 嘻哈 : 说唱
41: 节日 : 圣诞
42: 励志
43: 器乐
44: 爵士
45: 爵士 : 比波普
46: 爵士 : 大乐队
47: 爵士 : 经典
48: 爵士 : 传统
49: 爵士 : 世界
50: 卡拉OK
51: 拉丁
52: 拉丁 : 流行
53: 拉丁 : 拉丁都市
54: 音乐剧
55: 新世纪
56: 流行
57: 流行 : 粤语流行
58: 流行 : 日本流行音乐
59: 流行 : 韩国流行音乐
60: 流行 : 华语流行
61: 流行 : 唱作人
62: 朋克
63: 节奏布鲁斯
64: 雷鬼
65: 摇滚
66: 摇滚 : 经典
67: 摇滚 : 摇滚乐
68: 斯卡
69: 灵魂乐
70: 原声带
71: 原声带 : 动漫
72: 原声带 : 电影
73: 原声带 : 音乐剧
74: 原声带 : 电视
75: 原声带 : 游戏
76: 灵歌
77: 口语
78: 口语 : 演讲
79: 陷阱音乐
80: 人声 : 怀旧
81: 世界音乐
82: 世界音乐 : 非洲
83: 世界音乐 : 美洲
84: 世界音乐 : 阿拉伯
85: 世界音乐 : 阿拉伯/阿拉伯流行
86: 世界音乐 : 阿拉伯/埃及/埃及嘻哈
87: 世界音乐 : 阿拉伯/埃及/马赫拉加纳特
88: 世界音乐 : 阿拉伯/伊斯兰
89: 世界音乐 : 阿拉伯/海湾
90: 世界音乐 : 阿拉伯/海湾/海湾贾尔萨特
91: 世界音乐 : 阿拉伯/海湾/海湾沙拉特
92: 世界音乐 : 阿拉伯/黎凡特
93: 世界音乐 : 阿拉伯/黎凡特/达布克
94: 世界音乐 : 阿拉伯/马格里布雷伊
95: 世界音乐 : 阿拉伯/北非
96: 世界音乐 : 亚洲/中亚
97: 世界音乐 : 亚洲/中国
98: 世界音乐 : 亚洲/印度
99: 世界音乐 : 亚洲/日本
100: 世界音乐 : 亚洲/南亚
101: 世界音乐 : 澳洲/太平洋
102: 世界音乐 : 民族
103: 世界音乐 : 欧洲2. 语言列表 (album_language)
saveBasicInfo 使用 album_language(2),即下方列表。
saveSong 使用 album_language(1),前两项为 0: 纯音乐、1: 中文(Chinese),其余与下方下标对应(整体 +2 偏移;album_language(2) 的 0 = album_language(1) 的 2)。
album_language(2) 下标:
0: 简体中文(Chinese)
1: 繁体中文(Traditional)
2: 英语(English)
3: 阿乔利语(Acoli)
4: 南非语(Afrikaans)
5: 阿坎语(Akan)
6: 阿姆哈拉语(Amharic)
7: 阿拉伯语(Arabic)
8: 亚美尼亚语(Armenian)
9: 巴托努语(Baatonum)
10: 班巴拉语(Bambara)
11: 巴斯克语(Basque)
12: 巴萨语(Bassa)
13: 孟加拉语(Bengali)
14: 贝宁语(Benin)
15: 布列塔尼语(Breton)
16: 保加利亚语(Bulgarian)
17: 粤语(Cantonese)
18: 加泰罗尼亚语(Catalan)
19: 教会斯拉夫语(Church Slavic)
20: 科西嘉语(Corsican)
21: 奥尔语--瓜德罗普克里(Guadeloupe)
22: 奥尔语--马提尼克克里(Martinique)
23: 奥尔语--留尼汪克里(Reunion)
24: 克罗地亚语(Croatian)
25: 捷克语(Czech)
26: 丹麦语(Danish)
27: 迪塔马里语(Ditammari)
28: 德曼语(dmn)
29: 杜阿拉语(Duala)
30: 荷兰语(Dutch)
31: 迪尤拉语--布基纳法索(Burkina Faso)
32: 迪尤拉语--科特迪瓦(Cote d'Ivoire)
33: 爱沙尼亚语(Estonian)
34: 芬兰语(Finnish)
35: 丰语(Fon)
36: 法语(French)
37: 富拉语--布基纳法索(Burkina Faso)
38: 富拉语--几内亚(Guinea)
39: 富拉语--马里(Mali)
40: 富拉语--尼日利亚(Nigeria)
41: 富拉语--塞内加尔(Senegal)
42: 富尔富尔德语(Fulfulde)
43: 盖尔语(Gaelic)
44: 加利西亚语(Galician)
45: 格鲁吉亚语(Georgian)
46: 德语(German)
47: 加纳皮钦英语(Ghanaian Pidgin English)
48: 希腊语(Greek)
49: 圭亚那克里奥尔法语(Guianese Creole French)
50: 海地语(Haitian)
51: 客家语(Hakka)
52: 希伯来语(Hebrew)
53: 印地语(Hindi)
54: 洪布里塞尼桑海语(Humburi Senni Songhay)
55: 匈牙利语(Hungarian)
56: 冰岛语(Icelandic)
57: 印度尼西亚语(Indonesian)
58: 爱尔兰语(Irish)
59: 意大利语(Italian)
60: 日语(Japanese)
61: 哈萨克语(Kazakh)
62: 金邦杜语(Kimbundu)
63: 韩语(Korean)
64: 科伊拉奇尼桑海语(Koyra Chiini Songhay)
65: 老挝语(Lao)
66: 拉丁语(Latin)
67: 拉脱维亚语(Latvian)
68: 林加拉语--安哥拉(Angola)
69: 林加拉语--中非(Central African Republic)
70: 林加拉语--刚果(金)(Democratic Republic of the Congo)
71: 林加拉语--刚果(布)(Republic of the Congo)
72: 立陶宛语(Lithuanian)
73: 马达加斯加语(Malagasy)
74: 马来语(Malay)
75: 满语(Manchu)
76: 毛利语(Maori)
77: 闽南语(Minnan)
78: 蒙古语(Mongolian)
79: 多语言(Multilingual)
80: 那不勒斯语(Neapolitan)
81: 恩加齐贾科摩罗语(Ngazidja Comorian)
82: 恩杰比语(Njebi)
83: 北恩德贝莱语(North Ndebele)
84: 北索托语(Northern Sotho)
85: 挪威语(Norwegian)
86: 奥克语(Occitan)
87: 巴利语(Pali)
88: 波斯语(Persian)
89: 波兰语(Polish)
90: 葡萄牙语(Portuguese)
91: 旁遮普语(Punjabi)
92: 罗马尼亚语(Romanian)
93: 俄语(Russian)
94: 梵语(Sanskrit)
95: 绍纳语(Shona)
96: 僧伽罗语(Sinhala)
97: 斯洛伐克语(Slovak)
98: 斯洛文尼亚语(Slovenian)
99: 索马里语(Somali)
100: 索宁克语--冈比亚(Gambia)
101: 索宁克语--马里(Mali)
102: 索宁克语--毛里塔尼亚(Mauritania)
103: 索宁克语--塞内加尔(Senegal)
104: 南索托语(Southern Sotho)
105: 西班牙语(Spanish)
106: 拉丁美洲西班牙语(Spanish (Latin America)*)
107: 苏苏语--几内亚(Guinea)
108: 苏苏语--塞拉利昂(Sierra Leone)
109: 斯瓦希里语--刚果(金)(Democratic Republic of the Congo)
110: 斯瓦希里语--肯尼亚(Kenya)
111: 斯瓦希里语--乌干达(Uganda)
112: 瑞典语(Swedish)
113: 他加禄语(Tagalog)
114: 塔马谢克语(Tamasheq)
115: 泰米尔语(Tamil)
116: 泰卢固语(Telugu)
117: 泰语(Thai)
118: 藏语(Tibetan)
119: 聪加语(Tsonga)
120: 茨瓦纳语(Tswana)
121: 土耳其语(Turkish)
122: 维吾尔语(Uighur)
123: 乌克兰语(Ukrainian)
124: 未定义(Undefined)
125: 乌尔都语(Urdu)
126: 越南语(Vietnamese)
127: 瓦马语(Waama)
128: 威尔士语(Welsh)
129: 沃洛夫语--冈比亚(Gambia)
130: 沃洛夫语--毛里塔尼亚(Mauritania)
131: 沃洛夫语--塞内加尔(Senegal)
132: 科萨语(Xhosa)
133: 约鲁巴语(Yoruba)
134: 祖鲁语(Zulu)
135: 其他语言(Other)3. 多重角色列表 (mutiple_role_cn)
song_artists JSON 中可选的额外角色字段,用于扩展艺人信息。
Songwriter 组:
harmonic_composer : Harmony Arranging(和声编写)
adapter : Adapter(改编者)
author : Author(作者)
librettist : Librettist(编剧)
licensed_verse : Licensed Verse(授权主歌)
orchestrator : Orchestrator(配器师)
vocal_adaptation : Vocal Adaptation(声乐改编)
Production & Engineering 组:
recording_engineer : Recording Engineer(录音师)
mixing_engineer : Mixing Engineer(混音师)
mastering_engineer : Mastering Engineer(母带工程师)
cover_art_designer : Cover Art Designer(封面设计师)
audio_editing_engineer: Audio Editing Engineer(音频编辑)
cover_photography : Cover Photography(封面摄影)
assistant_engineer : Assistant Engineer(助理工程师)
atmos_mastering_engineer: Atmos Mastering Engineer(全景声母带工程师)
atmos_mixing_engineer: Atmos Mixing Engineer(全景声混音师)
co_producer : Co-Producer(联合制作人)
guitar_technician : Guitar Technician(吉他技师)
licensed_beat : Licensed Beat(授权 Beat)
production_assistant : Production Assistant(制作助理)
sound_engineer : Sound Engineer(音响工程师)
transcriber : Transcriber(转录员)
vocal_editing_engineer: Vocal Editing Engineer(人声编辑)
vocal_engineer : Vocal Engineer(声乐工程师)
vocal_producer : Vocal Producer(配唱制作人)
Performer 组:
accordion : Accordion(手风琴)
harmonic : Harmonic(和声)
band : Band(乐队)
bass : Bass(贝斯)
bassoon : Bassoon(巴松管)
bell : Bell(铃铛)
cello : Cello(大提琴)
choir : Choir(合唱团)
drums : Drums(鼓)
flute : Flute(竖笛/长笛)
guitar : Guitar(吉他)
harmonica : Harmonica(圆号)
keyboard : Keyboard(键盘)
piano : Piano(钢琴)
rap : Rap(说唱)
sampling : Sampling(采样)
saxophone : Saxophone(萨克斯)
synthesizer : Synthesizer(合成器)
ring_drums : Ring Drums(铃鼓)
long_horn : Long Horn(长号)
short_horn : Short Horn(小号)
violin : Violin(小提琴/竖琴/中提琴)
old_style_cello : Old Style Cello(古大提琴)
whistle : Whistle(口哨)
woodwind : Woodwind(木琴)
vocalist : Vocalist(主唱)
mixed_performer : Mixed Performer(混合表演者)
arrangement_programming: Arrangement Programming(编曲编程)
pipe_organ : Pipe Organ(管风琴)
hits : Hits(打击乐)
Admin 组:
project_planning : Project Planning(企划/策划)
coordinator : Coordinator(统筹)
supervisor : Supervisor(监制)
executive_producer : Executive Producer(出品/出品人)
music_director : Music Director(音乐总监)
promotion : Promotion(宣发)
responsible_editor : Responsible Editor(责任编辑)厂牌模块 API(api_v1)
基本信息
- 基础路径:
/api_v1/label - 数据格式: JSON
- 认证方式: API Key
- 接口性质: 公开接口(供外部系统调用,仅凭 API Key 鉴权,不依赖登录态)
鉴权说明
所有接口均使用 API Key 鉴权,在请求头中传入(与专辑模块完全一致):
Authorization: Bearer <api_key>
Content-Type: application/x-www-form-urlencoded注意:
- API Key 通过/api_v1/apikey/create接口创建(需先通过 OAuth 2.0 Bearer Token 认证)
- 所有厂牌数据均按 API Key 解析出的用户隔离,客户端无需也无法指定user_id
- 鉴权失败返回 HTTP 401,响应体code为0,wait为401
数据安全说明
由于是公开接口,接口层做了以下限制:
| 措施 | 说明 |
|---|---|
| 用户数据隔离 | 查询、更新均以 API Key 解析出的 user_id 作为条件,无法访问他人厂牌 |
| 越权防护 | detail / update 传入的 id 必须属于当前用户,否则统一提示“厂牌不存在或无权限” |
| 输出字段白名单 | 仅返回 id、name、remark、is_default、create_time、update_time,不返回 user_id 等内部字段 |
| 分页上限 | page_size 最大 50,防止单次拉取大量数据;page 小于 1 时按 1 处理 |
| 文本清洗与长度限制 | name、remark 去除首尾空白并过滤 HTML 标签;name 最长 100 字符,remark 最长 255 字符 |
| 默认厂牌保护 | 系统默认厂牌(is_default=1)不允许查询详情和修改 |
| 写操作资格校验 | 添加厂牌要求实名认证状态为 approved 且账号类型为 enterprise |
通用响应格式
{
"code": 1,
"msg": "success",
"data": null
}| 字段 | 类型 | 说明 |
|---|---|---|
| code | int | 1=成功,0=失败,401=未授权 |
| msg | string | 提示信息 |
| data | mixed | 返回数据,错误时为 null |
1. 获取厂牌列表
GET /api_v1/label/index
查询当前 API Key 所属用户的厂牌列表,按 id 倒序排列。
请求参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| page | int | 否 | 页码,默认 1,小于 1 时按 1 处理 |
| page_size | int | 否 | 每页条数,默认 10,最大 50(超出按 50 处理) |
成功响应:
{
"code": 1,
"msg": "",
"data": {
"items": [
{
"id": 1,
"name": "小歌曲音乐分发平台",
"remark": "默认厂牌,无法修改或删除",
"is_default": 1,
"create_time": 1735689600,
"update_time": 1735689600
},
{
"id": 2,
"name": "某某唱片",
"remark": "厂牌备注",
"is_default": 0,
"create_time": 1735689600,
"update_time": 1735689600
}
],
"total": 2,
"current_page": 1,
"last_page": 1,
"if_account_type": 1
}
}返回字段:
| 字段 | 类型 | 说明 |
|---|---|---|
| items | array | 厂牌列表 |
| items[].id | int | 厂牌ID |
| items[].name | string | 厂牌名称 |
| items[].remark | string | 备注 |
| items[].is_default | int | 是否默认厂牌:1=是,0=否 |
| items[].create_time | int | 创建时间(Unix 时间戳,秒) |
| items[].update_time | int | 更新时间(Unix 时间戳,秒) |
| total | int | 总条数 |
| current_page | int | 当前页码 |
| last_page | int | 最后一页页码 |
| if_account_type | int | 账号类型:1=企业认证,0=个人认证/未认证 |
业务逻辑:
| 场景 | 行为 |
|---|---|
| 默认厂牌 | 当前用户不存在默认厂牌时,自动创建一条默认厂牌(name = "小歌曲音乐分发平台",is_default = 1)后再返回列表 |
鉴权错误响应:
{
"code": 0,
"msg": "API Key 无效或已被禁用",
"data": null,
"url": "",
"wait": 401
}2. 添加厂牌
POST /api_v1/label/add
为当前用户新增一个厂牌。
请求参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | string | 是 | 厂牌名称,最长 100 字符,同一用户下不可重名 |
| remark | string | 否 | 备注,最长 255 字符,默认空字符串 |
验证规则:
| 字段 | 规则 | 说明 |
|---|---|---|
| name | 业务校验 | 去空白、过滤 HTML 标签后不能为空,且不超过 100 字符 |
| remark | 业务校验 | 去空白、过滤 HTML 标签后不超过 255 字符 |
前置校验:
| 校验项 | 不满足时的提示 |
|---|---|
| 实名认证 | 未认证或审核未通过(status != approved)→ “请先完成实名认证” |
| 账号类型 | 非企业认证(type != enterprise)→ “仅限企业用户才能添加厂牌” |
| 重名校验 | 当前用户已存在同名厂牌 → “厂牌名称已存在” |
成功响应:
{
"code": 1,
"msg": "添加厂牌成功",
"data": {
"id": 3
}
}错误响应:
{
"code": 0,
"msg": "请先完成实名认证"
}业务逻辑:
| 场景 | 行为 |
|---|---|
| 新增 | 校验通过后写入 think_label,is_default 默认 0,返回新厂牌 ID |
| 存储 | name、remark 经过过滤后原样存储,时间字段为 Unix 时间戳 |
3. 获取厂牌详情
GET /api_v1/label/detail
获取指定厂牌详情(用于编辑回显)。
请求参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | int | 是 | 厂牌ID,必须属于当前 API Key 用户 |
成功响应:
{
"code": 1,
"msg": "",
"data": {
"id": 2,
"name": "某某唱片",
"remark": "厂牌备注",
"is_default": 0,
"create_time": 1735689600,
"update_time": 1735689600
}
}错误响应:
{
"code": 0,
"msg": "厂牌ID不能为空"
}校验规则:
| 校验项 | 说明 |
|---|---|
| ID 有效性 | id 必须为正整数 |
| 归属校验 | id 必须属于当前用户,否则统一提示“厂牌不存在或无权限”(不区分不存在与越权) |
| 默认厂牌 | is_default=1 的默认厂牌不允许查看详情 |
4. 更新厂牌
POST /api_v1/label/update
更新厂牌信息,仅允许修改备注(remark)。
请求参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | int | 是 | 厂牌ID,必须属于当前 API Key 用户 |
| remark | string | 是 | 新备注,不能为空,最长 255 字符 |
验证规则:
| 字段 | 规则 | 说明 |
|---|---|---|
| id | 业务校验 | 必须为正整数 |
| remark | 业务校验 | 去空白、过滤 HTML 标签后不能为空,且不超过 255 字符 |
成功响应:
{
"code": 1,
"msg": "更新厂牌成功",
"data": []
}错误响应:
{
"code": 0,
"msg": "参数错误"
}校验规则:
| 校验项 | 说明 |
|---|---|
| 参数完整性 | id 与 remark 均为必填,缺失或清洗后为空返回“参数错误” |
| 归属校验 | 更新条件同时包含 id 与 user_id,双重保证不越权 |
| 默认厂牌 | is_default=1 的默认厂牌不允许修改 |
| 可改字段 | 仅 remark 可更新,同时刷新 update_time,name 不可通过该接口修改 |
附录
访问路径
GET /api_v1/label/index
POST /api_v1/label/add
GET /api_v1/label/detail
POST /api_v1/label/update