视频文件任务结果查询接口

1. 接口介绍

查询 7 天内的视频文件任务状态及结果，可用于轮询任务结果。通常任务有如下几种状态：

• 正在排队等待处理：待处理任务数量超出上限，排队等待处理
• 正在处理：任务正在被处理
• 处理成功：任务处理成功，已有识别结果
• 处理失败：任务处理失败，可能由于文件链接无法访问等原因导致任务处理失败
• 已取消：任务被客户取消
• 已过期：任务结果已过期

2. 请求

2.1 请求地址

v3.1（推荐）

区域	请求地址
国内	https://api.video.tuputech.com/v3.1/recognition/video/result/<secretId>
国外	https://api-oversea.video.tuputech.com/v3.1/recognition/video/result/<secretId>

v3

区域	请求地址
国内	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（推荐）

参数名称	类型	是否必填	说明
requestId	String	是	任务 ID
timestamp	Int	否	当前服务器的 Unix 时间戳。 当前已废弃，仅保持兼容（采用该鉴权方式的调用不受影响）。新接入请使用 API Key 接口鉴权
nonce	Float	否	随机数（建议使用 Unix 时间戳或若干位随机整数）。 当前已废弃，仅保持兼容（采用该鉴权方式的调用不受影响）。新接入请使用 API Key 接口鉴权
signature	String	否	RSA-SHA256 算法签名。 当前已废弃，仅保持兼容（采用该鉴权方式的调用不受影响）。新接入请使用 API Key 接口鉴权。 签名步骤： 将参与签名的参数（secretId，timestamp，nonce）用英文半角逗号 , 拼接，得到 SignString； 使用您的私钥以 RSA-SHA256 算法对 SignString 签名，然后进行 Base64 编码，得到 signature 字符串。 点击 数字证书 下载私钥。私钥有 rsa 和 pkcs8 两种格式，通常 Golang，Python 使用 rsa 格式私钥，Java 使用 pkcs8 格式私钥 点击 签名及验证示例 查看签名示例

v3

参数名称	类型	是否必填	说明
videoId	String	是	任务 ID
timestamp	Int	否	当前服务器的 Unix 时间戳。 当前已废弃，仅保持兼容（采用该鉴权方式的调用不受影响）。新接入请使用 API Key 接口鉴权
nonce	Float	否	随机数（建议使用 Unix 时间戳或若干位随机整数）。 当前已废弃，仅保持兼容（采用该鉴权方式的调用不受影响）。新接入请使用 API Key 接口鉴权
signature	String	否	RSA-SHA256 算法签名。 当前已废弃，仅保持兼容（采用该鉴权方式的调用不受影响）。新接入请使用 API Key 接口鉴权。 签名步骤： 将参与签名的参数（secretId，timestamp，nonce）用英文半角逗号 , 拼接，得到 SignString； 使用您的私钥以 RSA-SHA256 算法对 SignString 签名，然后进行 Base64 编码，得到 signature 字符串。 点击 数字证书 下载私钥。私钥有 rsa 和 pkcs8 两种格式，通常 Golang，Python 使用 rsa 格式私钥，Java 使用 pkcs8 格式私钥 点击 签名及验证示例 查看签名示例

2.6 请求示例

v3.1（推荐）

{
  "requestId": "<requestId>",
  "timestamp": 1685000000,
  "nonce": 1685000000,
  "signature": "<signature>"
}

v3

{
  "videoId": "<videoId>",
  "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

JSON 参数说明

v3.1（推荐）

参数名称	类型	是否必有	说明
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 时间戳

v3

参数名称	类型	是否必有	说明
code	Int	是	状态码，详见 业务状态码
message	String	是	返回信息
nonce	Float	是	随机数（建议使用 Unix 时间戳或若干位随机整数）
timestamp	Int	是	当前服务器的 Unix 时间戳
status	String	是	视频任务当前状态。 cancelled：已取消； failed：任务失败； pending：正在排队； processing：正在处理； success: 处理完成
result	Object	否	识别结果, 结构参考视频异步识别接口回调结果

3.2 响应示例

v3.1（推荐）

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
}

v3

{
  "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 字段，简化解析逻辑；其他字段标记为待废弃