视频文件异步接口

1. 接口介绍

视频识别主要是截图识别，当待审核视频较大或时长较长时，截图及识别耗时较长，客户可以通过该接口进行异步识别，识别结果将以回调的方式通知客户。除去回调外，客户也可以主动查询识别结果。调用该接口时会返回 videoId 作为本次审核任务的任务 ID，并在回调请求中携带 videoId。业务流程如下：

提示

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

截图分辨率

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

2. 请求

2.1 请求地址

区域	请求地址
国内	`http://api.video.tuputech.com/v3/recognition/video/asyncscan/<secretId>`
国外	`http://api-us.open.tuputech.com/v3/recognition/video/asyncscan/<secretId>`

提示

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

2.2 请求方法

POST

2.3 请求头

Content-Type: application/json

2.3 请求参数

参数名称	类型	是否必填	说明
`video`	String	是	视频文件链接。 1. 出于安全考虑，视频链接端口除 `80`, `443` 端口外，应在 `1025-65535` 范围内
`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, 60]`，默认 1 秒
`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.4 请求示例

{
  "video": "<url>",
  "interval": 1,
  "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 数据结构
`<任务 ID>`	Object	是	识别任务的结果，每个识别任务会有全局固定不变的 `taskId` 和对应数据结构，详见具体任务识别结果回调
`suggestion`	Number	否	汇总结果，整体的通过/拒绝情况，参考审核场景汇总结果说明
`riskType`	Number	否	汇总结果，整体的风险类型，参考审核场景汇总结果说明
`customInfo`	Object	否	提交的自定义信息，请求参数中的 `customInfo`

VideoInfo 数据结构

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

4.6 请求示例

{
  "code": 0,
  "message": "success",
  "nonce": 1685000000,
  "timestamp": 1685000000,
  "videoInfo": {
    "id": "<videoId>",
    "captureStart": "2023-01-01T00:00:00Z",
    "capturedImages": 9,
    "duration": 8.5
  },
  "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（语音转译审核）>": {
    "text": "毛泽东你好",
    "violations": [
      {
        "startTime": 12,
        "endTime": 15,
        "content": "毛泽东",
        "action": "block",
        "label": "Politics",
        "review": false,
        "rate": 0.896484,
        "details": [
          {
            "keyword": "毛泽东",
            "hint": "毛泽东",
            "mainLabel": "Politics",
            "subLabel": "National_Leader"
          }
        ]
      }
    ]
  },
  "<任务 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
      }
    ]
  }
}

4.7 具体任务识别结果回调

图片类任务：

语音类任务：

视频文件异步接口

1. 接口介绍​

截图分辨率​

2. 请求​

2.1 请求地址​

2.2 请求方法​

2.3 请求头​

2.3 请求参数​

CallbackRules 数据结构​

CallbackRule 数据结构​

2.4 请求示例​

3. 同步响应​

3.1 响应参数说明​

json 参数说明​

3.2 响应示例​

4. 回调请求​

4.1 请求地址​

4.2 请求方法​

4.3 请求头​

4.4 超时时间及异常处理​

4.5 请求参数说明​

json 参数说明​

VideoInfo 数据结构​

4.6 请求示例​

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

1. 接口介绍

截图分辨率

2. 请求

2.1 请求地址

2.2 请求方法

2.3 请求头

2.3 请求参数

CallbackRules 数据结构

CallbackRule 数据结构

2.4 请求示例

3. 同步响应

3.1 响应参数说明

json 参数说明

3.2 响应示例

4. 回调请求

4.1 请求地址

4.2 请求方法

4.3 请求头

4.4 超时时间及异常处理

4.5 请求参数说明

json 参数说明

VideoInfo 数据结构

4.6 请求示例

4.7 具体任务识别结果回调