视频流异步接口

1. 接口介绍

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

提示

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

截图分辨率

如果视频的短边分辨率超过 1024 像素，则截取的图片以 1024/短边 等比例截取。例如：视频分辨率为 1920x1080，截图的分辨率为 1820x1024。

2. 请求

2.1 请求地址

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

提示

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

2.2 请求方法

POST

2.3 请求头

Content-Type: application/json

2.4 超时时间及异常处理

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

2.5 请求参数

参数名称	类型	是否必填	说明
`video`	String	是	视频流地址。 1. 支持的协议：`RTMP`、`HLS`、`HTTP-FLV`、`RTSP`； 2. 支持的编码格式：`H.264/AVC`、`H.263`、`H.263+`、`MPEG-1`、`MPEG-2`、`MPEG-4`、`MJPEG`、`VP8`、`VP9`；3. 支持的容器格式：`flv`, `mkv`, `mp4`, `rmvb`, `avi`, `wmv`, `3gp`, `ts`, `mov`
`timestamp`	Int	是	当前服务器的 Unix 时间戳
`nonce`	Int	是	随机数
`signature`	String	是	`RSA-SHA256` 算法签名。签名步骤：将参与签名的参数（`secretId`，`timestamp`，`nonce`）用英文半角逗号 `,` 拼接，得到 `SignString`；使用您的私钥以 `RSA-SHA256` 算法对 `SignString` 签名，然后进行 `Base64` 编码，得到 `signature` 字符串。点击数字证书下载私钥。私钥有 rsa 和 pkcs8 两种格式，通常 Golang，Python 使用 rsa 格式私钥，Java 使用 pkcs8 格式私钥点击签名及验证示例查看签名示例
`callbackUrl`	String	是	识别结果回调接口地址，用于接收 POST 回调
`interval`	Number	否	视频截图间隔，单位秒。取值范围 `[0.5, 10]`，默认 1 秒
`fragmentTime`	Number	否	视频语音切片时长及回调间隔，范围 `[10, 60]` 秒，默认 60 秒
`audio`	Boolean	否	是否开启语音识别，默认 `false`
`callbackRules`	CallbackRules	否	回调规则，默认回调违规标签的数据。详见 CallbackRules 数据结构
`customInfo`	Object<String, String/Int>	否	自定义信息，为识别任务添加业务信息（如房间 ID、文件 ID 等）或其他扩展参数
`task`	Array<String>	否	指定的任务 ID。通常单个应用（接口）下会配置多个识别任务，可根据业务需要指定其中的部分任务进行识别

CallbackRules 数据结构

参数名称	类型	是否必填	说明
`<任务 ID>`	Array<CallbackRule>	否	识别任务的回调规则，详见 CallbackRule 数据结构

备注

CallbackRules 是一个键值对/Object，key 为 taskId, value 为 CallbackRule 数组。

CallbackRule 数据结构

参数名称	类型	是否必填	说明
`label`	Int	是	仅回调指定标签的结果
`review`	Boolean	否	不为空时，仅回调指定标签的复审类型的结果

2.6 请求示例

{
  "video": "<url>",
  "interval": 1,
  "fragmentTime": 10,
  "callbackUrl": "<callback>",
  "audio": false,
  "customInfo": {
    "roomId": "<roomId>"
  },
  "callbackRules": {
    "54bcfc6c329af61034f7c2fc": [
      {
        "label": 0,
        "review": false
      },
      {
        "label": 1,
        "review": false
      }
    ]
  },
  "task": [
    "<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 参数说明

参数名称	类型	说明
`code`	Int	状态码，详见业务状态码
`message`	String	状态信息
`nonce`	Number	随机数
`timestamp`	Number	当前服务器的 Unix 时间戳
`videoId`	String	任务 ID，长度为 20~64 的字符串（可能随着服务迭代发生变化）

3.2 响应示例

{
  "code": 0,
  "message": "success",
  "nonce": 1685000000,
  "timestamp": 1685000000,
  "videoId": "<videoId>"
}

4. 回调请求

4.1 请求地址

callbackUrl 参数指定的地址。

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 参数说明

参数名称	类型	是否必有	说明
`code`	Int	是	状态码，详见业务状态码
`message`	String	是	状态信息
`nonce`	Number	是	随机数
`timestamp`	Number	是	当前服务器的 Unix 时间戳
`videoInfo`	VideoInfo	是	视频信息，详见 VideoInfo 数据结构
`fragmentInfo`	Object	是	视频片段信息。详见 FragmentInfo 数据结构
`<任务 ID>`	Object	是	识别任务的结果，每个识别任务会有全局固定不变的 `taskId` 和对应数据结构，详见具体任务识别结果回调
`isAudio`	Boolean	否	该回调是否语音片段识别结果，视频截图识别结果该字段可能省略。由于视频截图与语音切片的处理时机不同，因此分开回调，客户需通过该字段进行区分
`suggestion`	Number	否	汇总结果，整体的通过/拒绝情况，参考审核场景汇总结果说明
`riskType`	Number	否	汇总结果，整体的风险类型，参考审核场景汇总结果说明
`customInfo`	Object	否	提交的自定义信息，请求参数中的 `customInfo`

VideoInfo 数据结构

参数名称	类型	说明
`id`	String	任务 ID
`captureStart`	String	视频截图开始时间，UTC 时间，格式为 `2023-01-01T00:00:00Z`

FragmentInfo 数据结构

参数名称	类型	说明
`id`	String	视频片段唯一标识
`offsetStart`	Number	视频片段截图开始时间（相对时间），单位秒
`offsetEnd`	Number	视频片段截图结束时间（相对时间），单位秒
`capturedImages`	Number	视频片段截图数量

4.6 请求示例

视频截图回调
语音片段回调

{
  "code": 0,
  "message": "success",
  "nonce": 1685000000,
  "timestamp": 1685000000,
  "videoInfo": {
    "id": "<videoId>",
    "captureStart": "2023-01-01T00:00:00Z"
  },
  "fragmentInfo": {
    "id": "<videoId>-1",
    "offsetStart": 0,
    "offsetEnd": 10,
    "capturedImages": 10
  },
  "customInfo": {
    "roomId": "<roomId>"
  },
  "suggestion": 1,
  "riskType": 1,
  "<任务 ID（图片分类任务）>": {
    "label": 0,
    "review": false,
    "fileList": [
      {
        "url": "<截图链接>",
        "rate": 0.9,
        "label": 0,
        "review": false,
        "second": 0
      }
    ],
    "avgScores": [
      {
        "score": 0.9,
        "label": 0
      }
    ],
    "maximums": [
      {
        "max": 0.9,
        "label": 0
      }
    ],
    "statistics": [
      {
        "count": 0,
        "label": 1
      }
    ]
  },
  "<任务 ID（人物搜索类任务）>": {
    "label": 2,
    "review": false,
    "fileList": [
      {
        "url": "<截图链接>",
        "similarity": 0.9,
        "label": 2,
        "review": false,
        "typeName": "<人物类型>",
        "faceId": "<人物名称>",
        "personId": "<personId>",
        "second": 0,
        "facePosition": [
          [
            0.191406,
            0.25
          ],
          [
            0.3125,
            0.25
          ],
          [
            0.3125,
            0.4652
          ],
          [
            0.191406,
            0.4652
          ]
        ]
      }
    ],
    "statistics": [
      {
        "count": 1,
        "label": 2
      }
    ],
    "matchList": [
      {
        "typeName": "<人物类型>",
        "faceId": "<人物名称>",
        "personId": "<personId>",
        "count": 1
      }
    ]
  },
  "<任务 ID（自定义图库）>": {
    "label": 2,
    "fileList": [
      {
        "url": "<截图链接>",
        "label": 2,
        "similarity": 0.9,
        "relatives": [
          {
            "path": "<自定义图片链接>",
            "score": 0.9
          }
        ],
        "second": 10
      }
    ],
    "maximums": [
      {
        "max": 0.9,
        "label": 2
      }
    ],
    "statistics": [
      {
        "count": 1,
        "label": 2
      }
    ]
  },
  "<任务 ID（OCR 文本审核）>": {
    "label": 3,
    "review": false,
    "fileList": [
      {
        "url": "<截图链接>",
        "text": "毛泽东",
        "scores": 0.9,
        "degree": 0,
        "location": [
          [
            0.4256518406293357,
            0.5753968315895163
          ],
          [
            0.5806905895660593,
            0.5753968315895163
          ],
          [
            0.5806905895660593,
            0.65079364460096
          ],
          [
            0.4256518406293357,
            0.65079364460096
          ]
        ],
        "textAnalysis": {
          "label": 3,
          "review": false,
          "rate": 0.9,
          "details": [
            {
              "keyword": "毛泽东",
              "hint": "毛泽东",
              "mainLabel": 3
            }
          ]
        },
        "second": 10
      }
    ],
    "avgScores": [
      {
        "score": 0.9,
        "label": 3
      }
    ],
    "maximums": [
      {
        "max": 0.9,
        "label": 3
      }
    ],
    "statistics": [
      {
        "count": 1,
        "label": 3
      }
    ]
  },
  "<任务 ID（检测类任务）>": {
    "fileList": [
      {
        "url": "<截图链接>",
        "category": 0,
        "scores": 0.9,
        "second": 1,
        "location": [
          [
            0.03537565228836477,
            0.03303825855255127
          ],
          [
            0.2027942005938315,
            0.03303825855255127
          ],
          [
            0.2027942005938315,
            0.271730899810791
          ],
          [
            0.03537565228836477,
            0.271730899810791
          ]
        ]
      }
    ],
    "avgScores": [
      {
        "score": 0.9,
        "category": 0
      }
    ],
    "maximums": [
      {
        "max": 0.9,
        "category": 0
      }
    ],
    "statistics": [
      {
        "count": 2,
        "category": 0
      }
    ]
  }
}

{
  "code": 0,
  "message": "success",
  "nonce": 1685000000,
  "timestamp": 1685000000,
  "videoInfo": {
    "id": "<videoId>",
    "captureStart": "2023-01-01T00:00:00Z"
  },
  "fragmentInfo": {
    "id": "<videoId>-1",
    "offsetStart": 0,
    "offsetEnd": 10,
    "capturedImages": 10
  },
  "customInfo": {
    "roomId": "<roomId>"
  },
  "isAudio": true,
  "<任务 ID（语音转译审核）>": {
    "text": "毛泽东你好",
    "violations": [
      {
        "startTime": 12,
        "endTime": 15,
        "content": "毛泽东",
        "action": "block",
        "label": "Politics",
        "review": false,
        "rate": 0.896484,
        "details": [
          {
            "keyword": "毛泽东",
            "hint": "毛泽东",
            "mainLabel": "Politics",
            "subLabel": "National_Leader"
          }
        ]
      }
    ]
  }
}

4.7 具体任务识别结果回调

5. 视频流结束状态回调

说明

使用建议：

收到视频流结束状态回调时, 说明任务已结束；
若 code 的值不为 0，说明流异常结束，可根据 code 的值查询对应的异常结束类型。

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 参数说明

参数名称	类型	是否必有	说明
`code`	Number	是	状态码，详见业务状态码
`nonce`	Number	是	随机数
`timestamp`	Number	是	当前服务器的 Unix 时间戳
`videoInfo`	VideoInfo	是	视频信息，详见 VideoInfo 数据结构
`fragmentInfo`	Object	否	视频片段信息。详见 FragmentInfo 数据结构
`customInfo`	Object<String, String/Int>	否	自定义信息，为识别任务添加业务信息（如房间 ID、文件 ID 等）或其他扩展参数

5.2 视频流结束状态回调示例

正常结束
异常结束

{
  "code": 0,
  "message": "success",
  "nonce": 1685000000,
  "timestamp": 1685000000,
  "videoInfo": {
    "id": "<videoId>",
    "captureStart": "2023-01-01T00:00:00Z",
    "status": "end",
    "message": "TaskClosed"
  },
  "fragmentInfo": {
    "id": "<videoId>-1",
    "offsetStart": 0,
    "offsetEnd": 10,
    "capturedImages": 10
  },
  "customInfo": {
    "roomId": "<roomId>"
  }
}

{
  "code": 100,
  "message": "task failed too many times during processing, the last error was: xxxxx",
  "nonce": 1685000000,
  "timestamp": 1685000000,
  "videoInfo": {
    "id": "<videoId>",
    "captureStart": "2023-01-01T00:00:00Z",
    "status": "error",
    "message": "task failed"
  }
}

视频流异步接口

1. 接口介绍​

截图分辨率​

2. 请求​

2.1 请求地址​

2.2 请求方法​

2.3 请求头​

2.4 超时时间及异常处理​

2.5 请求参数​

CallbackRules 数据结构​

CallbackRule 数据结构​

2.6 请求示例​

3. 同步响应​

3.1 响应参数说明​

json 参数说明​

3.2 响应示例​

4. 回调请求​

4.1 请求地址​

4.2 请求方法​

4.3 请求头​

4.4 超时时间及异常处理​

4.5 请求参数说明​

json 参数说明​

VideoInfo 数据结构​

FragmentInfo 数据结构​

4.6 请求示例​

4.7 具体任务识别结果回调​

5. 视频流结束状态回调​

5.1 请求参数说明​

json 参数说明​

5.2 视频流结束状态回调示例​

1. 接口介绍

截图分辨率

2. 请求

2.1 请求地址

2.2 请求方法

2.3 请求头

2.4 超时时间及异常处理

2.5 请求参数

CallbackRules 数据结构

CallbackRule 数据结构

2.6 请求示例

3. 同步响应

3.1 响应参数说明

json 参数说明

3.2 响应示例

4. 回调请求

4.1 请求地址

4.2 请求方法

4.3 请求头

4.4 超时时间及异常处理

4.5 请求参数说明

json 参数说明

VideoInfo 数据结构

FragmentInfo 数据结构

4.6 请求示例

4.7 具体任务识别结果回调

5. 视频流结束状态回调

5.1 请求参数说明

json 参数说明

5.2 视频流结束状态回调示例