图片异步识别接口

1. 接口介绍

该接口支持批量提交图片任务进行识别，通过查询和回调的方式异步获取结果，适用于需要异步处理数据的场景。识别结果缓存 2 小时，在此期间您可以通过图片请求的 requestId 查询结果。

动态图片支持 gif 及 webp 格式，目前仅截取首帧进行识别。从 2023 年 12 月开始，变更为满足下述条件时，转换为最多 10 张静态图片进行识别：

请求中的图片数量为 1，并且是 gif 或 webp 动态图片

动态图片转换、计费和结果响应规则：

当动图帧数 <= 10 时，取全部帧；按照实际帧数计费；按照实际帧数返回每张图片的结果；
当动图帧数 >= 10 时，间隔取 10 帧；按照 10 帧计费；按照 10 帧返回每张图片的结果。

提示

接口并发限制：默认每秒请求数不超过 50 次；
图片文件大小限制：base64 编码后默认不超过 1M，请联系我们调整并发及文件限制；
请求大小限制：每次请求中最多包含 10 张图片，单次请求体不超过 30M；
支持的图片格式：png、jpg、jpeg、tif、webp、bmp、gif、heic

2. 请求

2.1 请求地址

图片链接
图片 base64

区域	请求地址
国内	`https://api.open.tuputech.com/v3/recognition/image/async/<secretId>`
国外	`https://api-oversea.open.tuputech.com/v3/recognition/image/async/<secretId>`

区域	请求地址
国内	`https://api.open.tuputech.com/v3/recognition/image/async/base64/<secretId>`
国外	`https://api-oversea.open.tuputech.com/v3/recognition/image/async/base64/<secretId>`

提示

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

2.2 请求方法

POST

2.3 请求头

Content-Type: application/json

2.4 超时时间及异常处理

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

危险

由于模型基于请求流量动态伸缩，在空闲一定时间后会关闭（部分专用模型空闲一定时间后会关闭全部实例）。由于模型冷启动耗时较长，部分请求可能无法处理，最终返回非 200 HTTP 状态码或业务状态码 101。该现象可能在以下情况下出现：

初次请求
长时间未调用后再次请求
请求流量突增
请求存在规律性的流量波动（例如每隔超过 5 分钟请求一批数据，或仅在工作日期间有大量请求）

针对以上情况，我们分别建议您：

间隔 2~3 分钟后重试
间隔 2~3 分钟后重试，并且后续保持至少每分钟 1 次调用
提前进行预热，或及时联系我们扩容
调整业务请求时间间隔到 5 分钟内，或联系我们调整实例保持策略。若您的业务仅在工作日期间有大量请求，节假日期间较少，请务必联系我们

2.5 请求参数说明

参数名称	类型	是否必需	说明
`images`	Array<Image>	是	图片数组，详见 Image 参数说明
`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>	否	TaskId 数组。通过此参数指定应用（SID）下需要调用的识别任务，如：`["54bcfc6c329af61034f7c2fc"]`；不传该参数时，调用该应用（SID）下的全部识别任务

Image 参数说明

图片链接
图片 base64

参数名称	类型	是否必需	说明
`url`	String	是	图片链接。 1. 支持的图片格式：`png`、`jpg`、`jpeg`、`tif`、`webp`、`bmp`、`gif`、`heic`； 2. 图片 base64 编码后默认限制在 1M 以内； 3. 出于安全考虑，图片链接端口除 `80`, `443` 端口外，应在 `1025-65535` 范围内
`callbackUrl`	String	否	回调地址，若为空则跳过结果回调
`tag`	String	否	图片业务信息，后续可根据 `tag` 搜索对应调用记录。例如：直播场景可传房间号或主播 ID 信息
`sequenceId`	String	否	连续帧图的组别 ID，例如直播间 ID 等，基于此 ID 进行该 ID 组别下的连续帧相似度识别（启用连续帧相似度识别服务必传）。 1. 需要保证同一 `sequenceId` 下的图片帧，在同一请求中唯一，并且在不同请求间按照时间顺序有一定的间隔（防止乱序）； 2. 建议按照图片帧的出现顺序依次调用接口，而非在一次请求中传入多张图片帧

参数名称	类型	是否必需	说明
`content`	String	是	图片 base64 字符串。 1. 支持的图片格式：`png`、`jpg`、`jpeg`、`tif`、`webp`、`bmp`、`gif`、`heic`； 2. 图片 base64 编码后默认限制在 1M 以内（一般经过 base64 编码后的字符串比原始数据大 33%）； 3. 请注意区分 Data URL 及 base64 字符串，base64 字符串不包含 `data:image/xxx;base64,` 前缀
`callbackUrl`	String	否	回调地址，若为空则跳过结果回调
`tag`	String	否	图片业务信息，后续可根据 `tag` 搜索对应调用记录。例如：直播场景可传房间号或主播 ID 信息
`sequenceId`	String	否	连续帧图的组别 ID，例如直播间 ID 等，基于此 ID 进行该 ID 组别下的连续帧相似度识别（启用连续帧相似度识别服务必传）。 1. 需要保证同一 `sequenceId` 下的图片帧，在同一请求中唯一，并且在不同请求间按照时间顺序有一定的间隔（防止乱序）； 2. 建议按照图片帧的出现顺序依次调用接口，而非在一次请求中传入多张图片帧

2.6 请求示例

图片链接
图片 base64

{
  "images": [
    {
      "url": "<url>",
      "callbackUrl": "<callback>",
      "tag": "<tag>",
      "sequenceId": "<sequenceId>"
    }
  ],
  "tasks": [
    "54bcfc6c329af61034f7c2fc"
  ],
  "nonce": 1685000000,
  "timestamp": 1685000000,
  "signature": "<signature>"
}

{
  "images": [
    {
      "content": "<base64>",
      "callbackUrl": "<callback>",
      "tag": "<tag>",
      "sequenceId": "<sequenceId>"
    }
  ],
  "tasks": [
    "54bcfc6c329af61034f7c2fc"
  ],
  "nonce": 1685000000,
  "timestamp": 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 参数说明

参数名称	类型	是否必有	说明
`images`	Array<Image>	是	图片提交结果，与请求参数 `images` 一一对应，详见 Image 参数说明

Image 参数说明

参数名称	类型	是否必有	说明
`code`	Number	是	状态码，标识该图片是否提交成功，详见业务状态码
`message`	String	是	状态信息
`requestId`	String	是	图片请求 ID，唯一标识该图片。字符串长度 24 ~ 255
`tag`	String	否	图片业务信息
`sequenceId`	String	否	连续帧图的组别 ID

3.2 响应示例

{
  "code": 0,
  "message": "success",
  "images": [
    {
      "code": 0,
      "message": "success",
      "requestId": "<requestId>",
      "tag": "<tag>"
    }
  ],
  "nonce": 1685000000,
  "timestamp": 1685000000
}

4. 回调请求

4.1 请求地址

参数 images 中每一张图片所对应的 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`	Number	是	状态码，标识该图片是否识别成功，参考业务状态码
`message`	String	是	业务信息
`requestId`	String	是	图片请求 ID，唯一标识该图片。字符串长度 24 ~ 255
`summary`	Summary	是	图片所有识别任务的汇总结果，数组长度与入参图片数量对应，详见 Summary 参数说明
`tag`	String	否	图片业务信息
`sequenceId`	String	否	连续帧图的组别 ID
`<任务 ID>`	Object	否	图片识别任务的结果，每个识别任务会有全局固定不变的 TaskId 和对应数据结构。具体各识别任务的结果回调数据结构，请参考具体任务识别结果页面，例如色情识别

Summary 参数说明

参数名称	类型	是否必有	说明
`code`	Number	是	图片识别状态码，参考业务状态码
`name`	String	否	图片链接或文件名
`suggestion`	Number	否	建议的操作，参考汇总结果解析
`riskType`	Number	否	风险类型，参考汇总结果解析
`riskTask`	String	否	风险任务 ID
`tag`	String	否	图片额外的业务信息

4.6 请求示例

{
  "code": 0,
  "message": "success",
  "requestId": "<requestId>",
  "riskType": 0,
  "suggestion": 0,
  "summary": [
    {
      "code": 0,
      "name": "<name>",
      "riskType": 0,
      "suggestion": 0
    }
  ],
  "54bcfc6c329af61034f7c2fc": {
    "fileList": [
      {
        "label": 2,
        "name": "<name>",
        "rate": 0.9511421918869019,
        "review": true,
        "subLabels": []
      }
    ]
  },
  "nonce": 1685000000,
  "timestamp": 1685000000
}

图片异步识别接口

1. 接口介绍​

2. 请求​

2.1 请求地址​

2.2 请求方法​

2.3 请求头​

2.4 超时时间及异常处理​

2.5 请求参数说明​

Image 参数说明​

2.6 请求示例​

3. 同步响应​

3.1 响应参数说明​

json 参数说明​

Image 参数说明​

3.2 响应示例​

4. 回调请求​

4.1 请求地址​

4.2 请求方法​

4.3 请求头​

4.4 超时时间及异常处理​

4.5 请求参数说明​

json 参数说明​

Summary 参数说明​

4.6 请求示例​

1. 接口介绍

2. 请求

2.1 请求地址

2.2 请求方法

2.3 请求头

2.4 超时时间及异常处理

2.5 请求参数说明

Image 参数说明

2.6 请求示例

3. 同步响应

3.1 响应参数说明

json 参数说明

Image 参数说明

3.2 响应示例

4. 回调请求

4.1 请求地址

4.2 请求方法

4.3 请求头

4.4 超时时间及异常处理

4.5 请求参数说明

json 参数说明

Summary 参数说明

4.6 请求示例