视频文件任务结果查询接口
1. 接口介绍
查询 7 天内的视频文件任务状态及结果,可用于轮询任务结果。通常任务有如下几种状态:
- 正在排队等待处理:待处理任务数量超出上限,排队等待处理
- 正在处理:任务正在被处理
- 处理成功:任务处理成功,已有识别结果
- 处理失败:任务处理失败,可能由于文件链接无法访问等原因导致任务处理失败
- 已取消:任务被客户取消
- 已过期:任务结果已过期
2. 请求
2.1 请求地址
- v3.1(推荐)
- v3
区域 | 请求地址 |
---|---|
国内 | https://api.video.tuputech.com/v3.1/recognition/video/result/<secretId> |
国外 | https://api-oversea.video.tuputech.com/v3.1/recognition/video/result/<secretId> |
区域 | 请求地址 |
---|---|
国内 | https://api.video.tuputech.com/v3/recognition/video/result/<secretId> |
国外 | https://api-oversea.video.tuputech.com/v3/recognition/video/result/<secretId> |
提示
<secretId>
需替换为您的应用 SID
,请联系客户经理为您开通及配置。关于 SID
详见 常见问题(FAQ)。
2.2 请求方法
POST
2.3 请求头
请求头名称 | 取值 | 是否必需 | 示例 | 说明 |
---|---|---|---|---|
Content-Type | application/json | 是 | Content-Type: application/json | 请求数据类型为 JSON |
X-API-Key | <API Key> | 是 | X-API-Key: <API Key> | API Key 用于接口鉴权。请访问控制台 - 数字证书 获取 API Key |
2.4 超时时间及异常处理
- 建议配置超时时间
1
秒,在 HTTP 响应状态码非200
或业务状态码为100/101
(服务错误)时立即进行重试; - 在业务状态码为
30/31
(正在排队或正在处理)时,间隔若干时间(取决于应用 QPS 及文件时长)进行重试; - 在业务状态码为
29/32/33
(任务已过期、取消或失败)时立即返回
2.5 请求参数说明 🔥
- v3.1(推荐)
- v3
参数名称 | 类型 | 是否必填 | 说明 |
---|---|---|---|
requestId | String | 是 | 任务 ID |
timestamp | Int | 否 | 当前服务器的 Unix 时间戳。 当前已废弃,仅保持兼容(采用该鉴权方式的调用不受影响)。新接入请使用 API Key 接口鉴权 |
nonce | Float | 否 | 随机数(建议使用 Unix 时间戳或若干位随机整数)。 当前已废弃,仅保持兼容(采用该鉴权方式的调用不受影响)。新接入请使用 API Key 接口鉴权 |
signature | String | 否 |
|
参数名称 | 类型 | 是否必填 | 说明 |
---|---|---|---|
videoId | String | 是 | 任务 ID |
timestamp | Int | 否 | 当前服务器的 Unix 时间戳。 当前已废弃,仅保持兼容(采用该鉴权方式的调用不受影响)。新接入请使用 API Key 接口鉴权 |
nonce | Float | 否 | 随机数(建议使用 Unix 时间戳或若干位随机整数)。 当前已废弃,仅保持兼容(采用该鉴权方式的调用不受影响)。新接入请使用 API Key 接口鉴权 |
signature | String | 否 |
|
2.6 请求示例
- v3.1(推荐)
- v3
{
"requestId": "<requestId>",
"timestamp": 1685000000,
"nonce": 1685000000,
"signature": "<signature>"
}
{
"videoId": "<videoId>",
"timestamp": 1685000000,
"nonce": 1685000000,
"signature": "<signature>"
}
3. 同步响应
3.1 响应参数说明 🔥🔥
参数名称 | 类型 | 说明 |
---|---|---|
signature | String | 同步响应或回调请求签名,由图普使用私钥签名,在需要时,您可以通过 图普公钥
进行验签以确保此响应内容来自图普(与您调用接口时使用的公私钥不同)。验签步骤:
|
json | String | 同步响应或回调请求经过 JSON 转义后的字符串,需进一步解析得到业务数据。
|
JSON 参数说明
- v3.1(推荐)
- v3
参数名称 | 类型 | 是否必有 | 说明 |
---|---|---|---|
code | Int | 是 | 状态码,详见 业务状态码 。可能的返回值包括:0 :任务处理完成 29 :任务不存在,或已过期失效 30 :任务正在排队等待处理 31 :任务正在处理 32 :任务已被取消 33 :任务处理失败 100/101 :服务错误 |
message | String | 是 | 状态信息 |
requestId | String | 是 | 任务 ID |
suggestion | Int | 否 | 汇总结果,整体的通过/拒绝情况,当业务状态码为 0 时存在,参考 审核场景汇总结果说明 |
riskType | Int | 否 | 汇总结果,整体的风险类型,当业务状态码为 0 时存在,参考 审核场景汇总结果说明 |
<任务 ID> | Object<String, Any> | 否 | 识别任务的结果,每个识别任务会有 全局固定不变 的 taskId 和对应数据结构,当业务状态码为 0 时存在,详见下述链接:1. 图片类任务结果 2. 文本类任务结果 3. 语音类任务结果 |
videoInfo | VideoInfo | 否 | 视频信息,当业务状态码为 0 时存在,详见 VideoInfo 数据结构 |
customInfo | Object<String, Any> | 否 | 透传的自定义信息,请求参数中的 customInfo |
nonce | Float | 是 | 随机数(建议使用 Unix 时间戳或若干位随机整数) |
timestamp | Int | 是 | 当前服务器的 Unix 时间戳 |
参数名称 | 类型 | 是否必有 | 说明 |
---|---|---|---|
code | Int | 是 | 状态码,详见 业务状态码 |
message | String | 是 | 返回信息 |
nonce | Float | 是 | 随机数(建议使用 Unix 时间戳或若干位随机整数) |
timestamp | Int | 是 | 当前服务器的 Unix 时间戳 |
status | String | 是 | 视频任务当前状态。cancelled :已取消;failed :任务失败;pending :正在排队;processing :正在处理;success : 处理完成 |
result | Object | 否 | 识别结果, 结构参考视频异步识别接口回调结果 |
3.2 响应示例
- v3.1(推荐)
- v3
3.2.1 任务处理成功
{
"code": 0,
"message": "success",
"requestId": "<requestId>",
"riskType": 1,
"suggestion": 1,
"videoInfo": {
"captureStart": "2023-01-01T00:00:00Z",
"capturedImages": 9,
"duration": 8.5
},
"customInfo": {
"roomId": "<roomId>"
},
"<任务 ID>": {},
"nonce": 1685000000,
"timestamp": 1685000000
}
3.2.2 任务正在处理
{
"code": 31,
"message": "异步任务:任务正在处理",
"requestId": "<requestId>",
"customInfo": {
"roomId": "<roomId>"
},
"nonce": 1685000000,
"timestamp": 1685000000
}
3.2.3 任务处理失败
{
"code": 33,
"message": "异步任务:任务处理失败 (文件错误:文件无效或下载错误)",
"requestId": "<requestId>",
"customInfo": {
"roomId": "<roomId>"
},
"nonce": 1685000000,
"timestamp": 1685000000
}
{
"code": 0,
"message": "success",
"status": "success",
"result": {
"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
}
]
}
},
"nonce": 1685000000,
"timestamp": 1685000000
}
4. 更新日志
日期 | 说明 |
---|---|
2025-06-17 | 新增 API Key 接口鉴权方式,简化接口鉴权。废弃签名鉴权方式,仅保持兼容(采用签名鉴权方式的调用不受影响) |
2024-08-09 | 调整并优化任务结果查询接口,将任务状态码收敛到 code 字段,简化解析逻辑;其他字段标记为待废弃 |