Music Tag

功能介绍

音乐标签能力通过对音乐进行多维度分析，自动生成各个维度下的分类标签及概率值，目前支持的七大维度维度包括：

人声
情绪
语种
风格
场景
背景音乐
强度

接口说明

请求方式：

POST（HTTP）

请求地址：

http://service-mqk0mc83-1257411467.bj.apigw.tencentcs.com/release/job

请求头：

Content-Type: application/json

请求流程：

接口包括‘创建任务’，‘查询任务’。创建任务后，用户可以主动查询任务来知晓任务结果，也可以在创建任务时输入回调地址（callback），则任务在完成后会自动回调该地址

其他要求：

文件格式：建议采用常见音频格式，如 mp3、wav

创建任务

参数说明

参数	是否必须	类型	说明
action	是	string	公共参数，此处为 CreateJob
secretId	是	string	公共参数，用户 SecretId
secretKey	是	string	公共参数，用户 SecretKey
createJobRequest	是	object
- inputs	是	Array of Input	Input，输入结构体数组
- outputs	是	Array of Output	Output，输出结构体数组
- callback	否	string	回调地址，默认：不开启回调
- customId	否	string	用户自定义任务 ID，小于 64 字符
- timeout	否	int	任务超时时间，单位秒。超过超时时间后任务会被置为 ERROR

Input

参数	是否必须	类型	说明
url	否	string	源 url 地址，与 source 字段二选一填写
source	否	object	仓库源设置，与 url 字段二选一填写
- contentId	是	string	仓库 ID
- path	是	string	源路径

注意：source, url 两个字段有且只有一个

Output

参数	是否必须	类型	说明
inputSelectors	是	Array of int	该输出的输入源
smartContentDescriptor	是	object	智能能力的描述，默认：空
- musicTagV2	是	object
-- tagType	是	Array of string	1. 输入范围: ["vocal", "language", "mood", "genre", "scene", "bgm", "intensity", "all"]2. 输入说明 - all 表示调用全部类型的标签 - 可以根据维度名称，组合调用各个子维度的标签 - all 选项和子选项不能同时出现

- vocal，2类人声标签
- language，21类语种标签
- mood，11类情绪标签
- genre，37类风格标签
- scene，36类场景标签
- bgm，2类背景音乐标签
- intensity，2类强度标签
- all，获取7大维度标签

请求示例：

{
  "action": "CreateJob",
  "secretId": "{secretId}",
  "secretKey": "{secretKey}",
  "createJobRequest": {
    "customId": "{customId}",
    "callback": "{callback}",
    "inputs": [
      {
        "url": "{url}"
      }
    ],
    "outputs": [
      {
        "inputSelectors": [0],
        "smartContentDescriptor": {
          "musicTagV2": {
            "tagType": ["mood", "vocal", "language", "scene", "genre", "bgm"]
          }
        }
      }
    ]
  }
}

返回示例：

{
  "requestId": "ac004192-110b-46e3-ade8-4e449df84d60",
  "createJobResponse": {
    "job": {
      "id": "13f342e4-6866-450e-b44e-3151431c578b",
      "state": 1, // 见下方state说明
      "customId": "{customId}",
      "callback": "{callback}",
      "inputs": [
        {
          "url": "{url}"
        }
      ],
      "outputs": [
        {
          "inputSelectors": [0],
          "smartContentDescriptor": {
            "musicTagV2": {
              "tagType": ["mood", "vocal", "language", "scene", "genre", "bgm"]
            }
          }
        }
      ],
      "timing": {
        "createdAt": "1603432763000",
        "startedAt": "0",
        "completedAt": "0"
      }
    }
  }
}

State

值	含义
1	SUBMITTED
2	PROCESSING
3	COMPLETED
4	ERROR
5	CANCELED

获取任务信息

获取方式：分为主动获取和被动回调。

主动获取按照 id 的类别有两种查询接口，一种是根据用户自定义 id 查询，由于平台无法保证该 id 的唯一性，故返回 Job 数组（见 1）；另一种是通过创建任务后的回包中的 id 查询（见 2）
被动回调需要在创建任务时填写 callback 字段，平台在任务进入完成态（COMPLETED/ERROR）后会将 Job 结构体发送给 callback 所指的地址（见 3），平台方推荐使用被动回调的方式获取任务结果。

在音乐标签能力中，如果查询到的任务成功（state=3），则任务的 Output 中会携带 smartContentResult 结构体，其中的 audioTagger 字段是一个结果对象数组，每个结果对象有标签类型（tagType），标签名称（tag），概率（probility）

主动查询，根据用户在新建任务时传入的自定义 customId

请求示例：

{
  "action": "ListJobs",
  "secretId": "{secretId}",
  "secretKey": "{secretKey}",
  "listJobsRequest": {
    "customId": "{customId}"
  }
}

注：listJobs 回包中携带的 jobs 是一个数组

返回示例：

{
  "requestId": "c9845a99-34e3-4b0f-80f5-f0a2a0ee8896",
  "listJobsResponse": {
    "jobs": [
      {
        "id": "a95e9d74-6602-4405-a3fc-6408a76bcc98",
        "state": 3,
        "customId": "{customId}",
        "callback": "{callback}",
        "timing": {
          "createdAt": "1610513575000",
          "startedAt": "1610513575000",
          "completedAt": "1610513618000"
        },
        "inputs": [
          {
            "url": "{url}"
          }
        ],
        "outputs": [
          {
            "inputSelectors": [0],
            "smartContentDescriptor": {
              "musicTagV2": {
                "tagType": ["mood", "vocal", "language", "scene", "genre", "bgm"]
              }
            },
            "smartContentResult": {
              "musigTagV2": {
                "musicTagV2": {
                  "vocal": {
                    "label": "声乐",
                    "prob": "1.0000"
                  },
                  "language": {
                    "label": "其他",
                    "prob": "0.0817"
                  },
                  "mood": {
                    "label": "兴奋",
                    "prob": "0.2953"
                  },
                  "genre": {
                    "label": "壮族",
                    "prob": "0.7710"
                  },
                  "scene": {
                    "label": "祈祷",
                    "prob": "0.8886"
                  },
                  "intensity": {}
                }
              }
            }
          }
        ]
      }
    ],
    "total": 1
  }
}

主动查询，根据新建任务时回包带的 id

请求示例：

{
  "action": "GetJob",
  "secretId": "{secretId}",
  "secretKey": "{secretKey}",
  "getJobRequest": {
    "id": "{id}"
  }
}

返回示例：

{
  "requestId": "c9845a99-34e3-4b0f-80f5-f0a2a0ee8896",
  "getJobResponse": {
    "job": {
      "id": "a95e9d74-6602-4405-a3fc-6408a76bcc98",
      "state": 3,
      "customId": "{customId}",
      "callback": "{callback}",
      "timing": {
        "createdAt": "1610513575000",
        "startedAt": "1610513575000",
        "completedAt": "1610513618000"
      },
      "inputs": [
        {
          "url": "{url}"
        }
      ],
      "outputs": [
        {
          "inputSelectors": [0],
          "smartContentDescriptor": {
            "musicTagV2": {
              "tagType": ["mood", "vocal", "language", "scene", "genre", "bgm"]
            }
          },
          "smartContentResult": {
            "musigTagV2": {
              "musicTagV2": {
                "vocal": {
                  "label": "声乐",
                  "prob": "1.0000"
                },
                "language": {
                  "label": "其他",
                  "prob": "0.0817"
                },
                "mood": {
                  "label": "兴奋",
                  "prob": "0.2953"
                },
                "genre": {
                  "label": "壮族",
                  "prob": "0.7710"
                },
                "scene": {
                  "label": "祈祷",
                  "prob": "0.8886"
                },
                "intensity": {}
              }
            }
          }
        }
      ]
    }
  }
}

被动回调

会将进入完成态（COMPLETED/ERROR）的任务的整个 Job 结构体发送到用户在创建任务时指定的 callback 字段对应的地址，Job 结构体见主动查询的示例（getJobResponse 下）

cURL 示例

新建任务

curl --location --request POST 'http://service-mqk0mc83-1257411467.bj.apigw.tencentcs.com/release/test/job' \
--header 'Content-Type: application/json' \
--data-raw '{
    "action": "CreateJob",
    "secretId": "{secretId}",
    "secretKey": "{secretKey}",
    "createJobRequest": {
        "customId": "{customId}",
        "callback": "{callback}",
        "inputs": [{
                "url": "{url}"
            }],
        "outputs": [
            {
                "inputSelectors": [0],
                "smartContentDescriptor": {
                    "audioTagger": {
                        "tags": [1, 2, 3]
                    }
                }
            }]
    }
}'

查询任务

# 根据customId
curl --location --request POST 'http://service-mqk0mc83-1257411467.bj.apigw.tencentcs.com/release/test/job' \
--header 'Content-Type: application/json' \
--data-raw '{
    "action": "ListJobs",
    "secretId": "{secretId}",
    "secretKey": "{secretKey}",
    "listJobsRequest": {
        "customId": "{customId}"
    }
}'

# 根据id
curl --location --request POST 'http://service-mqk0mc83-1257411467.bj.apigw.tencentcs.com/release/test/job' \
--header 'Content-Type: application/json' \
--data-raw '{
    "action": "GetJob",
    "secretId": "{secretId}",
    "secretKey": "{secretKey}",
    "getJobRequest": {
        "id": "{id}"
    }
}'

附录：目前支持的标签

音乐标签模型列表
标签模型	种类	标签字段
vocal	2	声乐
		纯音乐
language	21	俄语
		印尼语
		国语
		德语
		意大利语
		日语
		法语
		泰语
		爪哇语
		瑞典语
		粤语
		纯音乐
		缅甸语
		英语
		葡萄牙语
		西班牙语
		越南语
		阿拉伯语
		韩语
		马来语
		其他
mood	11	伤感
		兴奋
		安静
		宣泄
		浪漫
		欢快
		怀旧
		恐怖
		恢弘
		放空
		滑稽
genre	37	8bit 像素风
		ACG
		Bossa
		中国基督教歌曲
		中国禅修
		古风
		乡村
		佛教
		儿童
		加勒比风格
		印度
		古典
		古装原声
		另类
		史诗
		嘻哈
		壮族
		巴西
		布鲁斯
		彝族
		拉丁
		摇滚
		朋克
		民谣
		泰国
		爵士
		电子
		硬核
		舞曲
		节奏布鲁斯
		蒙古
		藏族
		轻音乐
		金属
		陕北民歌
		雷鬼
		韩国流行
scene	25	东方禅修
		中国风
		二次元
		健身
		像素风音效
		儿歌
		八音盒
		咖啡厅
		喜庆
		夜店
		大合唱
		宠物
		情歌
		旅行
		校园
		歌剧
		游戏
		瑜伽
		睡前
		祈祷
		纯自然
		航拍
		花滑
		草原
		跑步
		钢琴纯音
bgm	2	有背景音乐
		无背景音乐
intensity	2	兴奋
		舒缓