# 团子轻函数

# 调用

# 介绍和限制

团子轻函数是一系列轻便、快速的函数，包含多个功能，皆使用统一的接口调用方式，每个功能抽象为“输入”和“输出”，您只需要提交正确的输入、函数名称，即可获得指定的“输出”。
本文档首先介绍轻函数的使用方法，不同的功能的调用的URL、输入和输出不同，除此之外均相同，文档的末尾将列出不同功能的输入和输出。

# 流程

抽象的来说，轻函数需要您的“输入”文件，执行，并返回“输出”文件，整个流程如下：

创建上传通道：在使用轻函数之前，您需要创建一条临时的上传通道（channel），该通道用于提交即将上传输入文件的选项。
上传文件：您需要将一个或多个文件上传到团子指定的动态URL内，作为“输入”。
执行轻函数：输入文件上传完毕后，您需要调用接口来执行轻函数。
查询文件处理情况：您可以查询文件的处理状态，获取文件的一些基本信息，当函数执行完毕后，该接口也会返回输出文件。

# 限制

轻函数的执行速度和当前的服务器负载有关，大多数处理将在 5 秒左右完成，在负载较高时可能延迟到 1 分钟左右的处理时间。
请勿过快调用接口，以免被自动限制，本页面全部接口限制最大QPS（每秒可调用接口次数）：5次
轻函数的输出文件仅保存1天，请在获取到输出文件后及时下载，过期后将无法获取。
上传的文件请遵守当地法律法规以及团子的《协议条款》 (opens new window)，不得上传侵权文件。

# 轻函数列表

目前已实现的功能（点击函数名称查看详情）：

音质损伤分析：详细分析音频是否损伤或存在有损压缩。

# 创建上传通道

在使用团子轻函数之前，你必须创建一条临时一次性的上传通道（channel），你可以在通道里提交即将上传的文件的选项，当服务器确认无误后将返回该通道的信息，持有这些信息就可以上传文件了。

创建通道不会扣费，只会预测余额是否不足且传递一些配置信息。

请求地址：

POST https://api.tuanziai.com/lite-method/{method-name}/upload/channel

URL参数：

参数名	类型	必须	默认	描述
method-name	string	是		轻函数的名称，当前支持的轻函数名称请参考轻函数列表。

POST请求体参数：

参数名	类型	必须	默认	描述
uploadVersion	int	是		上传行为版本号，固定为`2`，必填，否则无法上传。
filename	string	是		您自定的标识（可以是文件的文件名或任何字符），在查询文件时，该字段将原封不动的返回给您。
useFreeNum	boolean	否	true	是否使用免费点数扣除本次计算任务，默认为`true`，为`false`时则消耗付费点数。

请求举例：

POST https://api.tuanziai.com/lite-method/audio-tool-lossy-check/upload/channel

{
	"uploadVersion": 2,
	"filename": "example",
    "useFreeNum": true
}

返回结果：

参数名	类型	必须	默认	描述
files	object	是		返回的需要补充的输入内容，详情见files字段。
channel	string	是		上传的通道号，持有此通道号用来获取上传结果。

# files字段

files是一个object类型的字段，可能包含了未知的1个或多个键，每个键代表了“要补充的输入”。键的数量和名称取决于当前轻函数的输入，如音质损伤分析只有一个键名为input。

每个键对应的值为一个object，值的内容包含了以下内容：

键名	类型	必须	描述
url	string	是	上传的动态URL，您需要将文件上传到此URL。
form	object	是	上传到URL时需要携带的表单信息，无需关心此内容。

返回举例：

{
	"code": 0,
	"message": "success",
	"data": {
		"channel": "25ff1dbf0d504d65bf1dbf0d50ed65da",
		"files": {
            "input": { //键名称（具体取决于轻函数）
	            "url": "xxxxx", 
	            "form": {
		            "xxxxx": "xxxxx",// 上传时表单信息
		            "xxxxx": "xxxxx"
                }
            }
        }
	}
}

可能的错误：

code	message	描述
-10	余额不足	你没有足够的余额来进行运算，请在开放平台充值后再试。

# 接下来做什么：

在获取到返回结果之后，你可以通过该通道进行上传文件了。

# 上传输入文件

您需要将一个或多个文件（取决于当前的轻函数所需的输入文件数量）上传至团子指定的动态URL内。

该动态URL取自创建上传通道返回的url字段，同时还需要在上传文件时携带动态的表单信息，该信息取自创建上传通道返回的form字段。

# 如何创建表单

您需要构建一个http表单（而非和团子其他请求那样的JSON）

创建上传通道返回的form字段为object类型，包含多个键与值，您无需关心其内容，仅需将这些键值对作为表单的键值对，同时在表单的最后一位添加一个file字段，值为要上传的文件。

# 文件的格式与限制

每个输入根据自身的类型，拥有不同的限制，具体请查阅当前轻函数的输入类型

类型	描述
音频类	服务器仅接收12分钟以内的、类型为`MP3` / `FLAC` / `WAV`的音频文件。输入音频一律归一化为 16bit / 44100SampleRate

请求地址：

POST 动态地址，值为“创建上传通道接口”返回结果中的"url"值。

请求参数：

参数名	类型	必须	默认	描述
form的键1	...	...	...	form的值1
form的键2	...	...	...	form的值2
...	...	...	...	...
file	File	是		要上传的文件，字段名必须为`file`否则服务器无法识别。该字段必须在表单最后的位置。

注意

必须将请求头的"Content-Type"的值设置为"multipart/form-data"
"file"字段必须在表单域最后一位，否则必定出错。
如报错Invalid Policy，代表上传参数有误，请检查上传参数的key-value是否正确，key必须注意大小写
如报错FieldItemTooLong，请将file的文件名改成全英文后再试。
其他问题请自行排查，参考链接：阿里云OSS - 400错误解决方案 (opens new window)，以及阿里云OSS - 调用PostObject接口的常见错误及解决方法 (opens new window)

请求举例：

POST https://dangoai.oss-accelerate.aliyuncs.com
	请使用表单模式调用此接口（"multipart/form-data"）。

<formdata>
	"xxxx": "xxxx",
	"xxxx": "xxxx",
	"xxxx": "xxxx",
	"file": <FILE>

返回结果：

(无返回，即便有，也无任何意义，无需解析此返回结果。查询文件是否上传成功、以及获取文件的处理情况请参考执行轻函数)

# 接下来做什么：

当一个或多个输入文件已经上传到指定URL后，即可请求团子执行轻函数了。

# 执行轻函数

您上传的文件位置并非在团子的服务器内，而是上传到了阿里云的OSS（一种类似云盘）上。故上传完文件后需要调用此接口用以检查文件，并启动文件的处理。

本接口可以查询一首歌的上传结果，并开始处理这首歌。验证文件是否有效，余额是否可用，且返回文件的ID，持有函数ID即可查询文件处理情况以及下载文件。

注意

一旦调用此接口，您就会开始扣除点数余额，不同轻函数的价格信息不同，具体的，请点击每个轻函数对应团子网站的功能页面，并在页面内找到工具与价格信息按钮并点击查看。
API调用不支持每日赠送的免费额度。
如本请求返回错误（如您的余额不足），请重新创建通道并重新上传文件，一条通道只能使用一次。

请求地址：

POST https://api.tuanziai.com/lite-method/{method-name}/upload/{channel}/result

URL参数：

参数名	类型	必须	默认	描述
method-name	string	是		轻函数的名称，当前支持的轻函数名称请参考轻函数列表。
channel	string	是		url参数，指32位长度字符串的上传通道，请通过创建上传通道获取。

请求举例：

POST https://api.tuanziai.com/lite-method/audio-tool-lossy-check/25ff1dbf0d504d65bf1dbf0d50ed65da/result

返回结果：

参数名	类型	必须	默认	描述
(根)	string	是		返回的文件methodId（32位长度），请妥善保存此ID以方便后面的下载文件等操作。

返回举例：

{
	"code": 0,
	"message": "success",
	"data": "33441abf7d3f4d3c841abf7d3f2d3c86"
}

可能的错误：

code	message	描述
-10	余额不足	你没有足够的余额来进行运算，请充值后再试。
-1	上传的音频文件不符合要求	音频类文件格式有问题，请上传支持的文件格式，或者你的音频文件可能损坏。
-1	缺少必须的文件	输入文件不完整或不存在，请检查上传的文件是否正确。
-1	上传的文件不允许超过x分钟，请考虑裁剪音频文件	文件过长，超过x分钟，请参考文件的格式与限制。
-100	-	参数错误，或通道不存在等其他原因。

# 接下来做什么：

函数开始运行后，稍等约5 ~ 60秒即可处理完成。这期间您可以通过轮询查询文件处理情况。

# 查询文件处理情况

通过本接口你可以获取到文件的状态（是否处理完成），以及文件的一些基本信息。

为了同时节省双方服务的带宽，一首歌根据时长最少也要 5 秒左右才会出现结果，所以在轮询本接口时可以添加一个 5 秒的延迟（即过了延迟时间再开始轮询），轮询频率请保持为 1 秒以上，否则可能触发服务器自动限流导致服务被暂停使用。

请求地址：

POST https://api.tuanziai.com/lite-method/{method-name}/{methodId}

URL参数：

参数名	类型	必须	默认	描述
method-name	string	是		轻函数的名称，当前支持的轻函数名称请参考轻函数列表。
methodId	string	是		url参数。函数的ID，这个字段通过执行轻函数接口返回的。此接口支持查询多个内容，您可以在多个ID直接用`英文逗号`隔开。

请求举例：

POST https://api.tuanziai.com/lite-method/audio-tool-lossy-check/33441abf7d3f4d3c841abf7d3f2d3c86
查询函数ID为"33441abf7d3f4d3c841abf7d3f2d3c86"的文件信息

POST https://api.tuanziai.com/lite-method/audio-tool-lossy-check/33441abf7d3f4d3c841abf7d3f2d3c86,25ff1dbf0d504d65bf1dbf0d50ed65da
查询函数ID为"334..."和"25f..."的文件信息

返回结果：

参数名	类型	必须	描述
status	int	是	文件当前处理状态。请参考文件状态
id	string	是	函数ID
methodName	string	是	函数名称
userFileName	string	是	文件的文件名（上传时由您提供的）
cost	int	是	函数扣除的点数
costType	string	是	值为`free`时该函数消耗的是免费点数，值为`pay`时消耗的是付费点数。
files	array[OutputFile]	是	输出文件（数组），仅在`status`为2时该字段存在，具体内容取决于当前轻函数的输出。files的详细定义请参考OutputFile部分。

# 文件状态

状态号	描述
0	文件仍在处理中
1	文件处理失败通常代表文件格式有问题。如果一首歌两次以上出现这个状态，可以联系我们进行排查。文件处理失败则会退回费用，不收费
2	文件处理成功，可以下载了

# OutputFile

键名	类型	描述
name	string	输出文件的名称。
url	string	输出文件的下载地址（链接有效期15分钟）。

返回举例：

{
    "code": 0,
    "message": "success",
    "data": {
        "status": 2,
        "id": "33441abf7d3f4d3c841abf7d3f2d3c86",
        "methodName": "audio-tool-lossy-check",
        "userFileName": "example",
        "cost": 10,
        "costType": "free",
	    "files": [
		    {
			    "name": "output.json",
			    "url": "xxxxx"
		    }
	    ]
    }
}

可能的错误：

code	message	描述
-10	文件已过期	文件已过期1天，已从服务器上永久删除无法获取信息。
-1	文件不存在	请检查methodId是否有误。

# 接下来做什么：

如果文件处理成功，您可以根据需要下载所需的输出文件，不同的轻函数的输出文件含义不同，具体需要查看当前轻函数的输出文件定义。

# 轻函数：音质损伤分析

# 名称（method-name）

audio-tool-lossy-check

# 介绍

该功能将分析输入的音频的损伤情况。

团子会输出到具体精确到区块的音质损伤值，音质损伤可能是因为遭遇过有损压缩、量化压缩、音频存在明显伪影，都会导致音质损伤。

# 输入

名称	类型	必须	描述
input	音频类	是	要分析的音频文件。

# 输出

名称	描述
output.json	文本，为JSON字符串，包含了音质损伤的分析结果，具体格式请参考音质损伤分析报告。

# 音质损伤分析报告

音质损伤分析报告为JSON格式，包含以下字段：

键名	类型	描述
audio_length	int	音频的帧数，除以`44100`为音频的秒数。
chunk_size	int	输出的采样帧数，通常为`44100`，即每秒分析一次（输入的采样率固定为44100），它决定了`result`的结果长度，请按照此字段解释result的每个值（而非按“秒”），团子无法保证chunk_size的值固定为44100。
version	string	算法的版本号和名称。
result	array[float]	数组，包含了每个采样点的音质损伤值，长度为`ceil(audio_length / chunk_size)`（意味着可能result的最后一个数值的是不满chunk_size长度的），数值范围为`-1 或 0 ~ 1`。-1为该区块为空音频（无法分析），0为损伤严重，1为无损。通常情况下可以认为`value < 0.3`时判断为有损区块，`value >= 0.3 && value < 0.75`时判断为怀疑区块，`value >= 0.75`时判断为无损区块。

# 示例

{
    //输入文件为3.226秒（142300 / 44100）
    "audio_length": 142300,
    //采样区块为1秒一次
    "chunk_size": 44100,
    //版本号
    "version": "2,dango-psyche-network",
    //结果数组（4条数据）
    //意味着[0-1秒的质量, 1-2秒的质量, 2-3秒的质量, 3-3.226秒的质量]
    "result": [0.15, 0.25, 0.9, 0.9]
}

← 混响回声移除