语音流异步接口

1. 接口介绍

客户通过语音流异步识别接口提交识别任务，图普拉取语音流进行切片，对语音片段进行识别检测，每隔一段时间通过回调通知客户识别结果。业务流程如下：

提示

图普采用 任务并发数 对异步接口进行并发控制，即任一时刻最多允许 N 个任务同时处理。在测试期间，任务并发数为 30（允许同时处理 30 个任务），正式使用或需要增加时请联系客户经理调整。当超出任务并发数后继续提交任务时，根据接口类型略有不同：
- 异步文件接口：可以正常提交任务，提交的任务排队等待处理；
- 异步流接口：提交任务时返回超出并发状态码（由于流的实时性要求，无法排队等待处理，因此无法继续提交）。
异步文件接口中，视频/语音文件建议小于 10GB，而文档文件须小于 500MB；异步流接口对流的时长没有限制，建议客户在流关闭时主动调用任务关闭接口。

2. 请求

2.1 请求地址

v3.1（推荐）
v3

区域	请求地址
国内	`https://api.speech.tuputech.com/v3.1/recognition/speech/stream/<secretId>`

区域	请求地址
国内	`https://api.speech.tuputech.com/v3/recognition/speech/stream/<secretId>`

提示

<secretId> 需替换为您的应用 SID，请联系客户经理为您开通及配置。关于 SID 详见常见问题（FAQ）。

2.2 请求方法

POST

2.3 请求头

Content-Type: application/json

2.4 超时时间及异常处理

建议配置超时时间 1 秒，在 HTTP 响应状态码非 200 或业务状态码不为 0 时进行重试。

2.5 请求参数说明 🔥

v3.1（推荐）
v3

参数名称	类型	是否必填	说明
`stream`	SpeechStream	是	语音流信息，详见 SpeechStream 参数说明
`tasks`	Array<String>	否	指定的任务 ID。通常单个应用（接口）下会配置多个识别任务，可根据业务需要指定其中的部分任务进行识别
`customInfo`	Object<String, Any>	否	自定义信息，用于给请求附加额外信息或扩展参数（比如：关联的信息）。目前支持的扩展参数： - `zego`：该参数有效时，拉取即构语音流进行审核，详见即构语音流异步接口
`timestamp`	Number	是	当前服务器的 Unix 时间戳
`nonce`	Number	是	随机数
`signature`	String	是	`RSA-SHA256` 算法签名。签名步骤：将参与签名的参数（`secretId`，`timestamp`，`nonce`）用英文半角逗号 `,` 拼接，得到 `SignString`；使用您的私钥以 `RSA-SHA256` 算法对 `SignString` 签名，然后进行 `Base64` 编码，得到 `signature` 字符串。点击数字证书下载私钥。私钥有 rsa 和 pkcs8 两种格式，通常 Golang，Python 使用 rsa 格式私钥，Java 使用 pkcs8 格式私钥点击签名及验证示例查看签名示例

SpeechStream 参数说明

参数名称	类型	是否必填	说明
`url`	String	是	语音流地址，需避免重复提交同一个语音流地址。 1. 支持的协议：`RTMP`、`HLS`、`HTTP-FLV`、`RTSP`； 2. 支持的编码格式：`AAC`、`AC-3`、`ADPCM`、`AMR`、`DSD`、`MP1`、`MP2`、`MP3`、`PCM`； 3. 支持的容器格式：`flv`、`mkv`、`mp5`、`rmvb`、`avi`、`wmv`、`wav`、`3gp`、`ts`、`mov`； 4. 识别即构语音流时，建议传入 `zego:<roomId>`，以保证同时只有一个房间在审核
`callback`	String	是	识别结果回调接口地址，用于接收 POST 回调
`returnPreSpeech`	Boolean	否	是否返回语音前一片段（时长为 10 秒）的语音链接；值为 `false` 时，只返回本片段语音链接。默认为 `false`
`callbackRule`	String	否	回调规则，主要影响审核场景的识别任务，如语音转译审核、低俗语音识别，默认为 `violation`。 `violation`：仅回调违规片段的识别结果； `all`：回调所有片段的识别结果

参数名称	类型	是否必填	说明
`speechStream`	Array<SpeechStream>	是	语音流信息，详见 SpeechStream 参数说明。由于兼容原因，数组长度需为 1
`timestamp`	Number	是	当前服务器的 Unix 时间戳
`nonce`	Number	是	随机数
`signature`	String	是	`RSA-SHA256` 算法签名。签名步骤：将参与签名的参数（`secretId`，`timestamp`，`nonce`）用英文半角逗号 `,` 拼接，得到 `SignString`；使用您的私钥以 `RSA-SHA256` 算法对 `SignString` 签名，然后进行 `Base64` 编码，得到 `signature` 字符串。点击数字证书下载私钥。私钥有 rsa 和 pkcs8 两种格式，通常 Golang，Python 使用 rsa 格式私钥，Java 使用 pkcs8 格式私钥点击签名及验证示例查看签名示例
`tasks`	Array<String>	否	指定的任务 ID。通常单个应用（接口）下会配置多个识别任务，可根据业务需要指定其中的部分任务进行识别

SpeechStream 参数说明

参数名称	类型	是否必填	说明
`url`	String	是	语音流地址，需避免重复提交同一个语音流地址。 1. 支持的协议：`RTMP`、`HLS`、`HTTP-FLV`、`RTSP`； 2. 支持的编码格式：`AAC`、`AC-3`、`ADPCM`、`AMR`、`DSD`、`MP1`、`MP2`、`MP3`、`PCM`； 3. 支持的容器格式：`flv`、`mkv`、`mp5`、`rmvb`、`avi`、`wmv`、`3gp`、`ts`、`mov`
`callback`	String	是	识别结果回调接口地址，用于接收 POST 回调
`returnPreSpeech`	Boolean	否	是否返回语音前一片段（时长为 10 秒）的语音链接；值为 `false` 时，只返回本片段语音链接。默认为 `false`
`callbackRules`	Number	否	回调规则，默认为 `0`。 `0`：仅回调违规片段的识别结果； `1`：回调所有片段的识别结果； `2`：结束时回调语音流结束状态； `3`：回调所有片段的识别结果，并在结束时回调语音流结束状态
`roomId`	String	否	房间 ID（指定时可在控制台根据此字段搜索识别结果）
`userId`	String	否	用户 ID（指定时可在控制台根据此字段搜索识别结果）
`forumId`	String	否	板块 ID（指定时可在控制台根据此字段搜索识别结果）
`customInfo`	Object	否	自定义信息，用于给请求附加额外信息（比如：关联的信息）

2.6 请求示例

v3.1（推荐）
v3

{
  "stream": {
    "url": "<url>",
    "callback": "<callback>",
    "returnPreSpeech": false,
    "callbackRule": "all"
  },
  "tasks": [
    "<taskId>"
  ],
  "customInfo": {
    "roomId": "<roomId>"
  },
  "timestamp": 1685000000,
  "nonce": 1685000000,
  "signature": "<signature>"
}

{
  "speechStream": [
    {
      "url": "<url>",
      "callback": "<callback>",
      "returnPreSpeech": false,
      "callbackRules": 1,
      "roomId": "<roomId>",
      "userId": "<userId>",
      "forumId": "<forumId>"
    }
  ],
  "tasks": [
    "<taskId>"
  ],
  "timestamp": 1685000000,
  "nonce": 1685000000,
  "signature": "<signature>"
}

3. 同步响应

3.1 响应参数说明 🔥🔥

参数名称类型说明

参数名称	类型	说明
`signature`	String	同步响应或回调请求签名，由图普使用私钥签名，在需要时，您可以通过图普公钥进行验签以确保此响应内容来自图普（与您调用接口时使用的公私钥不同）。验签步骤：取 `json` 字段内容为 `SignString`；将 `signature` 字段内容进行 `Base64` 解码，得到 `RawSignature`；使用图普公钥以 `SHA256` 算法验证 `RawSignature` 及 `SignString`
`json`	String	同步响应或回调请求经过 JSON 转义后的字符串，需进一步解析得到业务数据。字段内容示例：`{\"code\":0, \"message\":\"success\"}`；字段详见下述 JSON 参数说明；为方便展示，同步响应及回调请求的示例中，均为解析后的 JSON

signature

String

同步响应或回调请求签名，由图普使用私钥签名，在需要时，您可以通过图普公钥进行验签以确保此响应内容来自图普（与您调用接口时使用的公私钥不同）。验签步骤：

取 json 字段内容为 SignString；
将 signature 字段内容进行 Base64 解码，得到 RawSignature；
使用图普公钥以 SHA256 算法验证 RawSignature 及 SignString

json

String

同步响应或回调请求经过 JSON 转义后的字符串，需进一步解析得到业务数据。

字段内容示例：{\"code\":0, \"message\":\"success\"}；
字段详见下述 JSON 参数说明；
为方便展示，同步响应及回调请求的示例中，均为解析后的 JSON

JSON 参数说明

v3.1（推荐）
v3

参数名称	类型	是否必有	说明
`code`	Number	是	状态码，详见业务状态码
`message`	String	是	状态信息
`result`	Result	否	任务提交结果，详见 Result 参数说明
`nonce`	Number	是	随机数
`timestamp`	Number	是	当前服务器的 Unix 时间戳

Result 参数说明

参数名称	类型	是否必有	说明
`requestId`	String	是	任务唯一 ID，回调中携带该任务 ID。字符串长度 24~128
`url`	String	是	提交的语音流地址
`callback`	String	是	提交的识别结果回调接口地址

参数名称	类型	是否必有	说明
`result`	Array<Result>	否	返回结果，详见 Result 参数说明。由于兼容原因，数组长度为 1
`code`	Number	是	状态码，详见业务状态码
`message`	String	是	状态信息
`nonce`	Number	是	随机数
`timestamp`	Number	是	当前服务器的 Unix 时间戳

Result 参数说明

参数名称	类型	是否必有	说明
`requestId`	String	是	任务唯一 ID，回调中携带该任务 ID。字符串长度 24~128
`url`	String	是	提交的语音流地址
`callback`	String	是	提交的识别结果回调接口地址
`roomId`	String	否	提交的房间 ID
`userId`	String	否	提交的用户 ID
`forumId`	String	否	提交的板块 ID

3.2 响应示例

v3.1（推荐）
v3

{
  "result": {
    "requestId": "<requestId>",
    "url": "<url>",
    "callback": "<callback>"
  },
  "code": 0,
  "message": "success",
  "nonce": 1685000000,
  "timestamp": 1685000000
}

{
  "result": [
    {
      "requestId": "<requestId>",
      "url": "<url>",
      "callback": "<callback>",
      "roomId": "<roomId>",
      "userId": "<userId>",
      "forumId": "<forumId>"
    }
  ],
  "code": 0,
  "message": "success",
  "nonce": 1685000000,
  "timestamp": 1685000000
}

4. 回调请求

4.1 请求地址

callback 参数指定的地址。

4.2 请求方法

POST

4.3 请求头

Content-Type: application/json

4.4 超时时间及异常处理

回调超时时间 5 秒，在 HTTP 响应状态码非 200 时进行重试，最多重试 3 次。

建议客户在处理回调时进行异步处理，响应回调时可以返回字符串或 JSON，示例如下：

// JSON
{
  "message": "ok"
}

// 字符串
success

4.5 请求参数说明 🔥🔥🔥

参数名称类型说明

参数名称	类型	说明
`signature`	String	同步响应或回调请求签名，由图普使用私钥签名，在需要时，您可以通过图普公钥进行验签以确保此响应内容来自图普（与您调用接口时使用的公私钥不同）。验签步骤：取 `json` 字段内容为 `SignString`；将 `signature` 字段内容进行 `Base64` 解码，得到 `RawSignature`；使用图普公钥以 `SHA256` 算法验证 `RawSignature` 及 `SignString`
`json`	String	同步响应或回调请求经过 JSON 转义后的字符串，需进一步解析得到业务数据。字段内容示例：`{\"code\":0, \"message\":\"success\"}`；字段详见下述 JSON 参数说明；为方便展示，同步响应及回调请求的示例中，均为解析后的 JSON

signature

String

取 json 字段内容为 SignString；
将 signature 字段内容进行 Base64 解码，得到 RawSignature；
使用图普公钥以 SHA256 算法验证 RawSignature 及 SignString

json

String

同步响应或回调请求经过 JSON 转义后的字符串，需进一步解析得到业务数据。

字段内容示例：{\"code\":0, \"message\":\"success\"}；
字段详见下述 JSON 参数说明；
为方便展示，同步响应及回调请求的示例中，均为解析后的 JSON

JSON 参数说明

v3.1（推荐）
v3

参数名称	类型	是否必有	说明
`code`	Number	是	状态码，详见业务状态码
`requestId`	String	是	任务唯一 ID
`suggestion`	Int	是	建议的操作，详见汇总结果解析中的 Suggestion 处理建议说明
`riskType`	Int	是	风险类型，详见汇总结果解析中的 RiskType 风险类型说明
`<任务 ID>`	Object	是	识别任务的结果，每个识别任务会有全局固定不变的 `taskId` 和对应数据结构，详见下述链接： 1. 图片类任务结果 2. 文本类任务结果 3. 语音类任务结果
`customInfo`	Object	否	提交的自定义信息，请求参数中的 `customInfo`
`nonce`	Number	是	随机数
`timestamp`	Number	是	当前服务器的 Unix 时间戳

参数名称	类型	是否必有	说明
`code`	Number	是	状态码，详见业务状态码
`requestId`	String	是	任务唯一 ID
`roomId`	String	否	提交的房间 ID
`userId`	String	否	提交的用户 ID
`forumId`	String	否	提交的板块 ID
`<任务 ID>`	Object	是	识别任务的结果，每个识别任务会有全局固定不变的 `taskId` 和对应数据结构，详见下述链接： 1. 图片类任务结果 2. 文本类任务结果 3. 语音类任务结果

4.6 请求示例

v3.1（推荐）
v3

{
  "code": 0,
  "message": "success",
  "requestId": "<requestId>",
  "suggestion": 0,
  "riskType": 0,
  "5c8213b9bc807806aab0a574": {
    "segments": [
      {
        "label": 0,
        "review": false,
        "speechUrl": "https://static.tuputech.com/api/image/original/cloud-api/storage-0831/2023-05-31/15-7/ec3249c2c68c475da82acfa0e01da544/1685518035.6439307480301700542.wav",
        "startTime": 1685000000,
        "endTime": 1685000010
      }
    ]
  },
  "5ca1bd6b3872ecc9afb99132": {
    "segments": [
      {
        "content": "今天是二零一零年一月十九号星期二欢迎收看东方新闻我是小蕾我是袁名我们在上海的直播向各位问好",
        "speechUrl": "https://static.tuputech.com/api/image/original/cloud-api/storage-0831/2023-05-31/15-7/ec3249c2c68c475da82acfa0e01da544/1685518035.6439307480301700542.wav",
        "startTime": 1685000000,
        "endTime": 1685000010
      }
    ],
    "text": "今天是二零一零年一月十九号星期二欢迎收看东方新闻我是小蕾我是袁名我们在上海的直播向各位问好"
  },
  "5caee6b2a76925c55a09a6d2": {
    "segments": [
      {
        "label": "Politics",
        "rate": 0.9607035630154159,
        "review": false,
        "action": "block",
        "content": "昨天下午举行传达学习，贯彻胡锦涛总书记，在上海考察时的重要讲话精神，中共中央政治局委员上海市委书记俞正声强调",
        "hasVoice": true,
        "speechUrl": "https://static.tuputech.com/api/image/original/cloud-api/storage-0831/2023-05-31/15-7/ec3249c2c68c475da82acfa0e01da544/1685518035.7890524239124616494.wav",
        "startTime": 1685000000,
        "endTime": 1685000010,
        "details": [
          {
            "keyword": "胡锦涛",
            "hint": "胡锦涛",
            "mainLabel": "Politics",
            "subLabel": "Political_Negative_events"
          }
        ]
      }
    ],
    "label": "Politics",
    "review": false,
    "rate": 0.9608212453978402,
    "action": "block",
    "text": "今天是二零一零年一月十九号星期二欢迎收看东方新闻我是小蕾我是袁名我们在上海的直播向各位问好。昨天下午举行传达学习，贯彻胡锦涛总书记，在上海考察时的重要讲话精神，中共中央政治局委员上海市委书记俞正声强调"
  },
  "5f59e4b71b29fa890e5472fb": {
    "segments": [
      {
        "label": 1,
        "review": false,
        "speechUrl": "https://static.tuputech.com/api/image/original/cloud-api/storage-0831/2023-05-31/15-7/ec3249c2c68c475da82acfa0e01da544/1685518035.6439307480301700542.wav",
        "startTime": 1685000000,
        "endTime": 1685000010,
        "details": [
          {
            "label": 1,
            "rate": 0.9999990463256836,
            "startTime": 2.8,
            "endTime": 10
          }
        ]
      }
    ]
  },
  "customInfo": {
    "roomId": "<roomId>"
  },
  "nonce": 1685000000,
  "timestamp": 1685000000
}

{
  "code": 0,
  "message": "success",
  "requestId": "<requestId>",
  "roomId": "<roomId>",
  "userId": "<userId>",
  "forumId": "<forumId>",
  "5caee6b2a76925c55a09a6d2": {
    "violations": [
      {
        "content": "昨天下午举行传达学习，贯彻胡锦涛总书记，在上海考察时的重要讲话精神，中共中央政治局委员上海市委书记俞正声强调",
        "action": "pass",
        "label": "Normal",
        "review": false,
        "rate": 1,
        "hasVoice": true,
        "details": []
      }
    ],
    "text": "昨天下午举行传达学习，贯彻胡锦涛总书记，在上海考察时的重要讲话精神，中共中央政治局委员上海市委书记俞正声强调",
    "label": "Politics",
    "action": "block",
    "review": false,
    "rate": 1
  },
  "nonce": 1685000000,
  "timestamp": 1685000000
}

5. 语音流结束回调

当客户关闭任务、流结束或异常时，图普会向客户发送语音流结束回调，可以通过标志 status=end 判断该回调是否表示语音流结束。若业务状态码 code 不为 0，说明视频流异常结束，可以根据业务状态码判断异常类型。可能的异常包括：

流结束：推流端停止推流，或一段时间内无法获取新的流数据
流状态异常：流地址错误、协议错误、流数据异常或流服务器错误；流中无视频或语音数据流；拉流过程中，流提前结束
拉流异常：连接超时，或拉流超时；无法拉流，流服务器拒绝连接

说明

v3.1 接口始终在语音流结束时回调；v3 接口仅在 callbackRules 设置了状态结束回调时才会回调。

5.1 请求参数说明🔥🔥🔥

参数名称类型是否必有说明

参数名称	类型	是否必有	说明
`signature`	String	是	同步响应或回调请求签名，由图普使用私钥签名，在需要时，您可以通过图普公钥进行验签以确保此响应内容来自图普（与您调用接口时使用的公私钥不同）。验签步骤：取 `json` 字段内容为 `SignString`；将 `signature` 字段内容进行 `Base64` 解码，得到 `RawSignature`；使用图普公钥以 `SHA256` 算法验证 `RawSignature` 及 `SignString`
`json`	String	是	同步响应或回调请求经过 JSON 转义后的字符串，需进一步解析得到业务数据。字段内容示例：`{\"code\":0, \"message\":\"success\"}`；字段详见下述 JSON 参数说明；为方便展示，同步响应及回调请求的示例中，均为解析后的 JSON

signature

String

是

取 json 字段内容为 SignString；
将 signature 字段内容进行 Base64 解码，得到 RawSignature；
使用图普公钥以 SHA256 算法验证 RawSignature 及 SignString

json

String

是

同步响应或回调请求经过 JSON 转义后的字符串，需进一步解析得到业务数据。

字段内容示例：{\"code\":0, \"message\":\"success\"}；
字段详见下述 JSON 参数说明；
为方便展示，同步响应及回调请求的示例中，均为解析后的 JSON

JSON 参数说明

v3.1（推荐）
v3

参数名称	类型	是否必有	说明
`code`	Int	是	状态码，详见业务状态码。可能的返回值包括： `0`：任务正常处理完成 `51000`：流结束 `51001~51003`：流状态异常 `51004~51006`：拉流异常
`requestId`	String	是	任务 ID
`status`	String	是	流结束标志，目前始终取 `end`
`nonce`	Number	是	随机数
`timestamp`	Number	是	当前服务器的 Unix 时间戳

参数名称	类型	是否必有	说明
`code`	Int	是	状态码，详见业务状态码。可能的返回值包括： `0`：任务正常处理完成 `51000`：流结束 `51001~51003`：流状态异常 `51004~51006`：拉流异常
`requestId`	String	是	任务 ID
`status`	String	是	流结束标志，目前始终取 `end`
`nonce`	Number	是	随机数
`timestamp`	Number	是	当前服务器的 Unix 时间戳

5.2 语音流结束状态回调示例

v3.1（推荐）
v3

{
  "code": 0,
  "requestId": "<requestId>",
  "status": "end",
  "nonce": 1685000000,
  "timestamp": 1685000000
}

{
  "code": 0,
  "requestId": "<requestId>",
  "status": "end",
  "nonce": 1685000000,
  "timestamp": 1685000000
}

6. 更新日志

日期	说明
2024-08-09	调整并优化流结束回调说明

语音流异步接口

1. 接口介绍​

2. 请求​

2.1 请求地址​

2.2 请求方法​

2.3 请求头​

2.4 超时时间及异常处理​

2.5 请求参数说明 🔥​

SpeechStream 参数说明​

SpeechStream 参数说明​

2.6 请求示例​

3. 同步响应​

3.1 响应参数说明 🔥🔥​

JSON 参数说明​

Result 参数说明​

Result 参数说明​

3.2 响应示例​

4. 回调请求​

4.1 请求地址​

4.2 请求方法​

4.3 请求头​

4.4 超时时间及异常处理​

4.5 请求参数说明 🔥🔥🔥​

JSON 参数说明​

4.6 请求示例​

5. 语音流结束回调​

5.1 请求参数说明🔥🔥🔥​

JSON 参数说明​

5.2 语音流结束状态回调示例​

6. 更新日志​

1. 接口介绍

2. 请求

2.1 请求地址

2.2 请求方法

2.3 请求头

2.4 超时时间及异常处理

2.5 请求参数说明 🔥

SpeechStream 参数说明

SpeechStream 参数说明

2.6 请求示例

3. 同步响应

3.1 响应参数说明 🔥🔥

JSON 参数说明

Result 参数说明

Result 参数说明

3.2 响应示例

4. 回调请求

4.1 请求地址

4.2 请求方法

4.3 请求头

4.4 超时时间及异常处理

4.5 请求参数说明 🔥🔥🔥

JSON 参数说明

4.6 请求示例

5. 语音流结束回调

5.1 请求参数说明🔥🔥🔥

JSON 参数说明

5.2 语音流结束状态回调示例

6. 更新日志