专辑模块 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
}
字段类型说明
codeint1=成功,0=失败,401=未授权
msgstring提示信息
datamixed返回数据,错误时为 null

1. 保存步骤1:基本信息

POST /api_v1/album/saveBasicInfo

保存专辑步骤1的基本信息(新建或更新)。

请求参数:

参数类型必填说明
album_idint否专辑ID,更新时传入,默认 0(新建)
name_cnstring否中文名称
versionstring否版本
artistsstring是主要艺人列表,JSON 数组字符串,如 ["许嵩", "周杰伦"]
genre_mainint是音乐风格下标,对应 music_style_cn() 数组索引,如 0=另类音乐
languageint是语言下标,对应 album_language(2) 数组索引,如 0=简体中文(Chinese)
labelstring是厂牌名字(非ID),需与 think_label 表中当前用户的厂牌名称一致
cover_pathstring是封面 OSS 路径
dynamic_cover_1_1string否动态封面 1:1 比例 OSS 路径
dynamic_cover_3_4string否动态封面 3:4 比例 OSS 路径
first_release_datestring是首次发行日期(格式:YYYY-MM-DD),如 "2025-01-01"
expected_release_datestring是预期发行日期(格式:YYYY-MM-DD),如 "2025-02-01"
release_statusint是发行状态:0=尚未发行,1=已经发行
p_line_yearstring是P Line 年份,如 "2025"
p_linestring是P Line 版权信息,如 "2025 某某唱片公司"
c_line_yearstring是C Line 年份,如 "2025"
c_linestring是C Line 版权信息,如 "2025 某某文化传媒公司"
messagestring否留言(给审核人员)
upc_eanstring否UPC/EAN 编码
descriptionstring否专辑描述
featuring_jsonstring否Featuring 艺人列表,JSON 数组字符串,如 ["艺名1","艺名2"]
localized_languagesstring否本地化语言 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_cnmax:100中文名称不超过100个字符
versionmax:100版本不超过100个字符
genre_main`require\number`音乐风格下标必填,下标越界则报错
language`require\number`语言下标必填,下标越界则报错
labelrequire厂牌名字必填,需在 think_label 表中存在
cover_pathrequire封面必填
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_eanmax: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
事务使用数据库事务,任何步骤失败自动回滚

存储字段映射:

请求参数数据库字段存储格式
artistsartistsJSON数组(过滤空值后按顺序重新索引)
featuring_jsonfeaturingJSON数组(过滤空值)
localized_languageslocalized_languagesJSON数组(language 下标 → 语言名称)
labellabel_id字符串(厂牌名字,非ID)
release_statusrelease_status中文:0→"尚未发行",1→"已经发行"
genre_maingenre_main英文(通过下标查 music_style_en())
—genre_sub英文(与 genre_main 相同)
languagelanguage字符串(通过下标查 album_language(2))
messagemessage字符串(留言)

2. 保存歌曲信息

POST /api_v1/album/saveSong

为指定专辑添加或更新歌曲。

请求参数:

参数类型必填说明
album_idint是所属专辑ID
song_idint否歌曲ID,更新时传入,默认 0(新建)
song_titlesstring是歌曲名称,如 "晴天"。后台转为 [{"title":"晴天"}] 格式存储
versionstring否版本
genre_mainint是音乐风格下标,同 saveBasicInfo,对应 music_style_cn() 索引
languageint是语言下标,对应 album_language(1) 数组索引
song_artistsstring是歌曲艺人 JSON 对象字符串,见下方详细说明
audio_pathstring否音频 OSS 路径
explicit_flagstring否脏标,默认 "无脏标",有脏标请传入 "有脏标"
lyricsstring条件必填歌词,语言下标=0 时可不填,不超过10000字符
catalog_numberstring否目录编号
isrcstring否ISRC 编码
localized_languagesstring否本地化语言 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必填,必须为数字
versionmax:100版本不超过100个字符
genre_main`require\number`音乐风格下标必填,下标越界则报错
language`require\number`语言下标必填,下标越界则报错
audio_pathmax:255音频路径不超过255个字符
song_artistsmax:2000歌曲艺人JSON不超过2000个字符
song_titlesmax:2000歌曲名称不超过2000个字符
explicit_flagmax:50脏标不超过50个字符
lyricsmax:10000歌词不超过10000个字符
pline—后端自动生成(拼接专辑 p_line_year p_line),前端无需提交
cline—后端自动生成(拼接专辑 c_line_year c_line),前端无需提交
catalog_numbermax:100目录编号不超过100个字符
isrcmax:50ISRC编码不超过50个字符
localized_languagesmax: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_titlessong_titlesJSON数组 [{"title":"..."}]
song_artistssong_artistsJSON对象
lyricslyrics字符串
—pline字符串(拼接专辑 p_line_year p_line)
—cline字符串(拼接专辑 c_line_year c_line)
localized_languageslocalized_languagesJSON数组(language 下标 → 语言名称)
genre_maingenre_main英文(通过下标查 music_style_en())
—genre_sub英文(与 genre_main 相同)
languagelanguage字符串(通过下标查 album_language(1))
album_idalbum_id整数
sortsort自动计算(按专辑内歌曲数量)

3. 提交审核

POST /api_v1/album/submitPublish

将已保存完整的专辑提交审核,状态从 draft / rejected 变更为 pending。

请求参数:

参数类型必填说明
album_idint是专辑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_idint是专辑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_idint是歌曲ID
album_idint是所属专辑ID

校验规则:

校验项说明
歌曲归属song_id 必须属于该专辑且属于当前用户
专辑归属album_id 必须属于当前用户
状态限制专辑状态为 pending/published/unpublished 时不可删除歌曲

成功响应:

{
    "code": 1,
    "msg": "删除成功",
    "data": []
}

错误响应:

{
    "code": 0,
    "msg": "歌曲不存在或无权操作"
}

6. 更新歌曲排序

POST /api_v1/album/updateSongSort

按传入的歌曲ID顺序更新歌曲的 sort 排序。

请求参数:

参数类型必填说明
album_idint是专辑ID
song_idsarray/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_idint是专辑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_v1api_v2
基础路径/api_v1/album/api_v2/album
鉴权方式API KeyOAuth 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
}
字段类型说明
codeint1=成功,0=失败,401=未授权
msgstring提示信息
datamixed返回数据,错误时为 null

1. 获取厂牌列表

GET /api_v1/label/index

查询当前 API Key 所属用户的厂牌列表,按 id 倒序排列。

请求参数:

参数类型必填说明
pageint否页码,默认 1,小于 1 时按 1 处理
page_sizeint否每页条数,默认 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
    }
}

返回字段:

字段类型说明
itemsarray厂牌列表
items[].idint厂牌ID
items[].namestring厂牌名称
items[].remarkstring备注
items[].is_defaultint是否默认厂牌:1=是,0=否
items[].create_timeint创建时间(Unix 时间戳,秒)
items[].update_timeint更新时间(Unix 时间戳,秒)
totalint总条数
current_pageint当前页码
last_pageint最后一页页码
if_account_typeint账号类型:1=企业认证,0=个人认证/未认证

业务逻辑:

场景行为
默认厂牌当前用户不存在默认厂牌时,自动创建一条默认厂牌(name = "小歌曲音乐分发平台",is_default = 1)后再返回列表

鉴权错误响应:

{
    "code": 0,
    "msg": "API Key 无效或已被禁用",
    "data": null,
    "url": "",
    "wait": 401
}

2. 添加厂牌

POST /api_v1/label/add

为当前用户新增一个厂牌。

请求参数:

参数类型必填说明
namestring是厂牌名称,最长 100 字符,同一用户下不可重名
remarkstring否备注,最长 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

获取指定厂牌详情(用于编辑回显)。

请求参数:

参数类型必填说明
idint是厂牌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)。

请求参数:

参数类型必填说明
idint是厂牌ID,必须属于当前 API Key 用户
remarkstring是新备注,不能为空,最长 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