如何使用API接口异步检测语音内容_内容安全(Content Moderation)-阿里云帮助中心

本文介绍了使用API接口异步检测语音内容的方法。语音内容审核帮助您检测音频文件或语音流（例如直播流）中的风险或违规内容，例如垃圾信息、广告、涉政、暴恐、辱骂、色情、灌水、违禁、无意义等内容。

（语音异步检测）使用说明

业务接口：/green/voice/asyncscan，表示语音异步检测。

您可以调用该接口创建语音异步检测任务。关于如何构造HTTP请求，请参见请求结构；您也可以直接选用已构造好的HTTP请求，更多信息，请参见SDK概览。

说明

语音检测默认识别中文普通话，如需识别其他语种（例如，英语、日语、西班牙语、阿拉伯语、法语、印尼语、越南语）或方言（粤语、四川话、湖北话、陕西话、山西话、河南话、东北话、天津话、甘肃话、贵州话、云南话、江西话、广西话、云南话、湖南话、山东话、苏州话、浙江话、上海话、闽南语），请联系商务经理。

计费信息：
该接口为收费接口。关于计费方式，请参见内容安全产品定价。
返回结果：
异步检测任务不会实时返回检测结果，您需要通过callback或者轮询的方式获取检测结果。检测结果最长保留一小时。
- callback获取检测结果：提交异步检测任务时，在请求参数中传入callback参数，用来自动接收检测结果。具体操作，请参见（异步检测）请求参数。
- 轮询获取检测结果：提交异步检测任务时，无需传入callback参数；提交异步检测任务后，调用结果查询接口获取检测结果。更多信息，请参见（语音异步检测结果查询）使用说明。
音频文件要求：
- 音频文件大小小于200 MB。
- 支持的音频文件格式：MP3、WAV、AAC、WMA、OGG、M4A、AMR、AUDIO、M3U8。
- 支持以下包含音频的视频文件格式：AVI、FLV、MP4、MPG、ASF、WMV、MOV、RMVB、RM。
语音流要求：
- 语音流时长小于24小时。
- 支持的语音流协议：HTTP、RTMP、RTSP。
- 支持的语音流格式：M3U8、FLV。

QPS限制

本接口的单用户QPS限制为50次/秒，并发审核路数限制为20路（即同一时间只能处理20个任务，如需要提升并发路数请咨询您的商务经理）。超过限制，API调用会被限流，这可能会影响您的业务，请合理调用。

说明

如果您对时效性要求不高，推荐您开启近线检测模式（offline），近线检测模式会在您提交任务的24小时内开始检测。

（异步检测）请求参数

名称	类型	是否必选	示例值	描述
bizType	String	否	default	该字段用于标识您的业务场景。您可以通过内容安全控制台创建业务场景（具体操作，请参见自定义机审标准）。
scenes	StringArray	是	antispam	检测场景，唯一取值：antispam。
live	Boolean	否	false	是否为语音流（例如直播流）检测。取值： true：表示语音流检测。 false（默认）：表示音频文件检测。说明如果需要检测语音流，该值必须传入true。
offline	Boolean	否	false	是否为近线检测模式。取值： true：表示近线检测模式。近线检测模式下，您提交的任务不保证能够实时处理，但是可以排队并在24小时内开始检测。 false（默认）：表示实时检测模式。对于超过了并发路数限制的检测请求会直接拒绝。说明该参数仅适用于音频文件检测，不适用于语音流检测。
callback	String	否	http://aliyundoc.com	检测结果回调通知您的URL，支持使用HTTP和HTTPS协议的地址。该字段为空时，您必须定时轮询检测结果。 callback接口必须支持POST方法、UTF-8编码的传输数据，以及表单参数checksum和content。内容安全按照以下规则和格式设置checksum和content，调用您的callback接口返回检测结果。 checksum：字符串格式，由`用户uid + seed + content`拼成字符串，通过SHA256算法生成。用户UID即阿里云账号ID，可以在阿里云控制台查询。为防篡改，您可以在获取到推送结果时，按上述算法生成字符串，与checksum做一次校验。说明用户UID必须是阿里云账号的UID，而不是RAM用户的UID。 content：JSON字符串格式，请自行解析反转成JSON对象。关于content结果的示例，请参见查询检测结果的返回示例。说明您的服务端callback接口收到内容安全推送的结果后，如果返回的HTTP状态码为200，则表示接收成功，其他的HTTP状态码均视为接收失败。接收失败时，内容安全将最多重复推送16次检测结果，直到接收成功。重复推送16次后仍未接收成功，则不再推送，建议您检查callback接口的状态。
seed	String	否	abc****	随机字符串，该值用于回调通知请求中的签名。由英文字母、数字、下划线（_）组成，不超过64个字符。由您自定义，用于在接收到内容安全的回调通知时校验请求由阿里云内容安全服务发起。说明当使用callback时，该字段必须提供。
cryptType	String	否	SHA256	使用回调通知时（callback），设置对回调通知内容进行加密的算法。内容安全会将返回结果（由`用户uid + seed + content`拼接的字符串）按照您设置的加密算法加密后，再发送到您的回调通知地址。取值： SHA256（默认）：使用SHA256加密算法。 SM3：使用国密HMAC-SM3加密算法，返回十六进制的字符串，且字符串由小写字母和数字组成。例如，abc经国密SM3加密后返回66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0。
tasks	JSONArray	是		指定检测对象，JSON数组中的每个元素是一个检测任务结构体。最多支持100个元素，即每次提交100条内容进行检测，支持100个元素的前提是需要将并发任务调整到100个以上。关于每个元素的具体结构描述，请参见task。

表 1. task
名称	类型	是否必选	示例值	描述
clientInfo	JSONObject	否	{"userId":"12023****","userNick":"Mike","userType":"others"}	客户端信息，请参见公共参数中的公共查询参数。服务器会把全局的clientInfo和此处独立的clientInfo合并。说明独立的clientInfo优先级更高。
dataId	String	否	1a90c9d6-6a81-42db-bbe1-e36102f3****	检测对象对应的数据ID。由大小写英文字母、数字、下划线（_）、短划线（-）、英文句号（.）组成，不超过128个字符，可以用于唯一标识您的业务数据。
liveId	String	否	liveId1****	语音直播流的ID。该参数用于语音直播任务去重，防止重复检测，如果传递该参数，会根据`uid+bizType+liveId`判断是否存在检测中的直播任务。如果存在，就直接返回已存在的直播检测taskId，不发起新的任务。
url	String	否	http://aliyundoc.com/test.flv	检测对象的URL。公网HTTP/HTTPS URL，且长度不超过2048个字符。阿里云OSS提供的文件路径。您需要先授权内容安全访问OSS存储空间，仅限相同区域的OSS空间。更多信息，请参见授权内容安全访问OSS存储空间。文件路径格式：oss://<bucket-name>.<endpoint>/<object-name>

（异步检测）返回数据

名称	类型	示例值	描述
code	Integer	200	错误码，和HTTP状态码一致。更多信息，请参见公共错误码。
msg	String	OK	请求消息的响应消息。
dataId	String	1a90c9d6-6a81-42db-bbe1-e36102f3****	检测对象对应的数据ID。说明如果在检测请求参数中传入了dataId，则此处返回对应的dataId。
taskId	String	voice3VayNFGf43J6S9mHYp1HYJ-12****	检测任务的ID。

（异步检测）示例

请求示例

http(s)://[Endpoint]/green/voice/asyncscan
&<公共请求参数>
{
    "scenes": [
        "antispam"
    ],
    "live": true,
    "tasks": [
        {
            "dataId": "1a90c9d6-6a81-42db-bbe1-e36102f3****",
            "url": "http://aliyundoc.com/test.flv"
        }
    ]
}

正常返回示例

{
    "msg": "OK",
    "code": 200,
    "requestId": "33921869-CF8A-4E62-8C31-44F37341****",
    "data": [
        {
            "code": 200,
            "msg": "OK",
            "dataId": "1a90c9d6-6a81-42db-bbe1-e36102f3****",
            "taskId": "voice3VayNFGf43J6S9mHYp1HYJ-12****"
        }
    ]
}

（语音异步检测结果查询）使用说明

业务接口：/green/voice/results，表示查询语音异步检测结果。

您可以调用该接口查询语音异步检测任务的结果。如果您在提交语音异步检测任务时未设置callback地址，则需要调用该接口轮询检测结果。关于如何构造HTTP请求，请参见请求结构；您也可以直接选用已构造好的HTTP请求，更多信息，请参见SDK概览。

计费信息：
该接口不计费。
查询超时：
- 对于音频文件检测任务，每次查询或者通过callback方式都会返回已检测完的语音检测结果（仅返回已检测完成的任务检测结果）。建议您将查询间隔设置为30秒，检测结果保留4个小时，并及时查询并保存结果。
- 对于语音流检测任务，每次轮询会返回最近10段检测到的语音内容检测结果，建议您将查询间隔设置为30秒；如果通过callback的方式获取语音流检测结果，系统每次检测出语音内容后都会发送回调通知。

QPS限制

本接口的单用户QPS限制为50次/秒。超过限制，API调用会被限流，这可能会影响您的业务，请合理调用。

（结果查询）请求参数

名称	类型	是否必选	示例值	描述
body	JSONArray	是	voice3VayNFGf43J6S9mHYp1HYJ-12****	要查询的检测任务的taskId列表。数组中的元素个数不超过100个。您在提交检测任务后，可以从返回数据中获取检测任务的taskId。

（结果查询）返回数据

名称	类型	示例值	描述
code	Integer	200	错误码，和HTTP状态码一致。 200：表示检测成功。 280：表示处理中，需要继续轮询。其他：表示任务失败。更多信息，请参见公共错误码。说明只有返回280表示任务还在进行，需要继续轮询该任务的检测结果。返回其他值均表示该语音检测任务已结束。如果实际上该语音检测没有结束，而是因为网络异常等原因异常结束，您可以重新提交语音异步检测任务。
msg	String	OK	请求参数的响应信息。
dataId	String	1a90c9d6-6a81-42db-bbe1-e36102f3****	检测对象对应的数据ID。说明如果在检测请求参数中传入了dataId，则此处返回对应的dataId。
taskId	String	voice3VayNFGf43J6S9mHYp1HYJ-12****	该检测任务的ID。
url	String	https://aliyundoc.com	检测对象的URL。公网HTTP/HTTPS URL，且长度不超过2048个字符。阿里云OSS提供的文件路径。您需要先授权内容安全访问OSS存储空间，仅限相同区域的OSS空间。更多信息，请参见授权内容安全访问OSS存储空间。文件路径格式：oss://<bucket-name>.<endpoint>/<object-name>
new_url	String	https://example.com	如果检测内容为语音流，检测结束后会转存文件地址。签名时间为30分钟，需要及时转存。说明默认该字段不返回。如果需要使用，请联系商务经理。如果开启了语音证据转存，则返回转存的音频文件（包含语音流）的OSS URL链接。更多信息，请参见检测结果。
results	JSONArray		检测成功（code=200）时，返回的检测结果。该结果包含一个或多个元素，每个元素是个结构体，对应一个场景。关于每个元素的结构描述，请参见result。

表 2. result
名称	类型	示例值	描述
scene	String	antispam	检测场景，和调用请求中的场景对应。唯一取值：antispam。
label	String	customized	检测结果的分类。取值： normal：正常文本 spam：含垃圾信息 ad：广告 politics：涉政 terrorism：暴恐 abuse：辱骂 porn：色情 flood：灌水 contraband：违禁 meaningless：无意义 harmful：不良场景（支持拜金炫富、追星应援、负面情绪、负面诱导等检测场景） customized：自定义（例如命中自定义关键词）
suggestion	String	block	建议您执行的后续操作。取值： pass：结果正常，无需进行其余操作。 review：结果不确定，需要进行人工审核。 block：结果违规，建议直接删除或者限制公开。
rate	Float	99.91	置信度分数，取值范围：0（表示置信度最低）~100（表示置信度最高）。如果suggestion为pass，则置信度越高，表示内容正常的可能性越高；如果suggestion为review或block，则置信度越高，表示内容违规的可能性越高。重要建议您参考suggestion和label（或者部分接口返回的sublabel）结果用于内容违规判定。
details	JSONArray		语音对应的文本详情。每一句文本对应一个元素，包含一个或者多个元素。关于每个元素的结构描述，请参见detail。说明如果您开启了语音证据转存，且检测对象为语音流，则返回转存的语音分片的OSS URL链接。更多信息，请参见检测结果。

表 3. detail
名称	类型	示例值	描述
startTime	Integer	0	句子开始的时间，单位：秒。
endTime	Integer	4065	句子结束的时间，单位：秒。
text	String	恶心的	语音转换成文本的结果。
label	String	customized	检测结果的分类。取值： normal：正常文本 spam：含垃圾信息 ad：广告 politics：涉政 terrorism：暴恐 abuse：辱骂 porn：色情 flood：灌水 contraband：违禁 meaningless：无意义 harmful：不良场景（支持拜金炫富、追星应援、负面情绪、负面诱导等检测场景） customized：自定义（例如命中自定义关键词）
persons	JSONArray	[{"name":"敏感人名A"}]	声纹识别结果，如果命中了敏感人物的声纹，则会返回该字段。具体结构如下： name：字符串类型，通过语音识别的敏感人物信息。说明默认不返回该字段。如果有需要，请联系商务经理。
hintWords	JSONArray	"[{"context":"敏感词"}]"	语音中包含的文本命中的风险关键词信息，用于提示您违规的原因，可能返回多个命中的关键词。具体结构描述，请参见hintWords。
keyword	String	恶心	如果命中了用户自定义关键词，返回命中的关键词。
libName	String	test	如果命中了用户自定义关键词，返回关键词所在的词库。
url	String	https://aliyundoc.com	如果检测的内容是语音流，表示该段文本对应的语音流的临时访问地址。该地址有效时间为30分钟，需要及时转存。说明默认该字段不返回，如果需要，请联系商务经理。

表 4. hintWords
名称	类型	示例值	描述
context	String	恶心的	语音中文本命中的风险关键词内容。

（结果查询）示例

请求示例

http(s)://[Endpoint]/green/voice/results
&<公共请求参数>
[
    "voice3VayNFGf43J6S9mHYp1HYJ-12****"
]

正常返回示例

{
    "msg": "OK",
    "code": 200,
    "data": [
        {
            "code": 200,
            "dataId": "1a90c9d6-6a81-42db-bbe1-e36102f3****",
            "results": [
                {
                    "rate": 99.91,
                    "suggestion": "block",
                    "details": [
                        {
                            "libName": "test",
                            "startTime": 0,
                            "endTime": 4065,
                            "label": "customized",
                            "text": "恶心的",
                            "keyword": "恶心"
                        },
                        {
                            "startTime": 4430,
                            "endTime": 10065,
                            "label": "review",
                            "persons": [
                                {
                                    "name": "敏感人名A"
                                }
                            ],
                            "text": "测试"
                        },
                        {
                            "libName": "语音测试",
                            "startTime": 11670,
                            "endTime": 14685,
                            "label": "customized",
                            "text": "超低折扣，大甩卖",
                            "keyword": "甩卖"
                        },
                        {
                            "startTime": 14685,
                            "endTime": 16065,
                            "label": "ad",
                            "text": "你好"
                        }
                    ],
                    "label": "customized"
                }
            ],
            "taskId": "voice3VayNFGf43J6S9mHYp1HYJ-12****"
        }
    ],
    "requestId": "5A7A6198-6960-4DDC-B67E-58A6F1A4****"
}