功能介绍
音乐评分为用户提供多维度唱歌打分能力，目前支持的打分维度包括：音准、节奏，具备以下特性：
高实时性：能够以演唱时长 1/6-1/8 倍的时间内完成全部指标的评估
高准确性：能够准确评估用户每一句演唱的音准、节奏等核心指标
高适配性：能够实现对男声、女声、童声、少年声、老年声等各种音色的演唱评分
接口说明
请求方式：
POST（HTTP）
请求地址：
https://api.mediax.tencent.com/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
是
SmartContentDescriptor
智能能力的描述，默认：空
- outputPrefix
否
string
输出文件前缀，小于 20 字符，默认：空
- vocalScore
是
object
音乐评分选项
-- rawAudio
否
object
评判标准文件。未经标准化处理的原始音频文件，与standardAudio字段二选一填写
--- url
否
string
原始音频文件源 url 地址，与 source 字段二选一填写
--- source
否
object
原始音频文件仓库源设置，与 url 字段二选一填写
---- contentId
是
string
仓库 ID
---- path
是
string
源路径
-- standardAudio
否
object
评判标准文件。原始音频经标准化处理后的相关文件，与rawAudio字段二选一填写
--- midi
是
object
MIDI文件
---- url
否
string
MIDI文件源 url 地址，与 source 字段二选一填写
---- source
否
object
MIDI文件仓库源设置，与 url 字段二选一填写
----- contentId
是
string
仓库 ID
----- path
是
string
源路径
--- alignWav
是
object
开头无静音音频文件
---- url
否
string
开头无静音音频文件源 url 地址，与 source 字段二选一填写
---- source
否
object
开头无静音音频文件仓库源设置，与 url 字段二选一填写
----- contentId
是
string
仓库 ID
----- path
是
string
源路径
--- standardWav
是
object
标准化音频文件
---- url
否
string
标准化音频文件源 url 地址，与 source 字段二选一填写
---- source
否
object
标准化音频文件仓库源设置，与 url 字段二选一填写
----- contentId
是
string
仓库 ID
----- path
是
string
源路径
请求示例：
{
"action": "CreateJob",
"secretId": "{secretId}",
"secretKey": "{secretKey}",
"createJobRequest": {
"customId": "{customId}",
"callback": "{callback}",
"inputs": [{ "url": "{url}" }],
"outputs": [
{
"inputSelectors": [0],
"smartContentDescriptor": {
"outputPrefix": "{outputPrefix}",
"vocalScore": {
"standardAudio": {
"midi": {"url":"{url}"},
"standardWav": {"url":"{url}"},
"alignWav": {"url":"{url}"}
}
}
}
}
]
}
}
返回示例：
{
"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": {
"outputPrefix": "{outputPrefix}",
"vocalScore": {
"standardAudio": {
"midi": {"url":"{url}"},
"standardWav": {"url":"{url}"},
"alignWav": {"url":"{url}"}
}
}
}
}
],
"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 结构体，其中的 vocalScore 字段存储评分结果json字符串，包括音准评分PitchPerformance，范围0-100，节奏评分RhythemPerformance，范围0-100。
1. 主动查询，根据用户在新建任务时传入的自定义 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": {
"outputPrefix": "{outputPrefix}",
"vocalScore": {
"standardAudio": {
"midi": {"url":"{url}"},
"standardWav": {"url":"{url}"},
"alignWav": {"url":"{url}"}
}
}
},
"smartContentResult": {
"vocalScore": "{ \"PitchPerformance\":70.0850183393764, \"RhythemPerformance\":99.99999999999999 }"
}
}
]
}
],
"total": 1
}
}
2. 主动查询，根据新建任务时回包带的 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": {
"outputPrefix": "{outputPrefix}",
"vocalScore": {
"standardAudio": {
"midi": {"url":"{url}"},
"standardWav": {"url":"{url}"},
"alignWav": {"url":"{url}"}
}
}
},
"smartContentResult": {
"vocalScore": "{ \"PitchPerformance\":70.0850183393764, \"RhythemPerformance\":99.99999999999999 }"
}
}
]
}
}
}
3. 被动回调
会将进入完成态（COMPLETED/ERROR）的任务的整个 Job 结构体发送到用户在创建任务时指定的 callback 字段对应的地址，Job 结构体见主动查询的示例（getJobResponse 下）
cURL 示例
新建任务
curl --location --request POST 'https://api.mediax.tencent.com/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": {
"outputPrefix": "{outputPrefix}",
"vocalScore": {
"standardAudio": {
"midi": {"url":"{url}"},
"standardWav": {"url":"{url}"},
"alignWav": {"url":"{url}"}
}
}
}
}
]
}
}'
查询任务
# 根据customId
curl --location --request POST 'https://api.mediax.tencent.com/job' \
--header 'Content-Type: application/json' \
--data-raw '{
"action": "ListJobs",
"secretId": "{secretId}",
"secretKey": "{secretKey}",
"listJobsRequest": {
"customId": "{customId}"
}
}'
# 根据id
curl --location --request POST 'https://api.mediax.tencent.com/job' \
--header 'Content-Type: application/json' \
--data-raw '{
"action": "GetJob",
"secretId": "{secretId}",
"secretKey": "{secretKey}",
"getJobRequest": {
"id": "{id}"
}
}'