图片同步识别接口
1. 接口介绍
该接口对图片内容进行检测识别,并同步返回识别结果。
2. 请求
2.1 通过图片链接调用
QPS 限制
- 1 秒最多允许请求 50 次;
- 1 个请求最多携带 10 张图片;
如有特殊并发需求,请联系我们。
2.1.1 请求地址
区域 | 请求地址 |
---|---|
国内 | http://api.open.tuputech.com/v3/recognition/<secretId> |
国外 | http://api-us.open.tuputech.com/v3/recognition/<secretId> |
国外 | http://api-oversea.open.tuputech.com/v3/recognition/<secretId> |
提示
- <secretId> 需替换为您的
secretId
,请联系我们为您开通secretId
。 - 如果您的图片服务器在国外,请通过国外域名调用,避免图片下载失败或超时。
2.1.2 请求方法
POST
2.1.3 请求头
Content-Type: application/json
2.1.4 请求参数说明
参数名称 | 类型 | 是否必需 | 说明 |
---|---|---|---|
image | String/Array<String> | 是 | 1. 支持传入多个图片链接; 2. 支持的图片格式:png、jpg、jpeg、tif、webp、bmp、gif、heif; 3. 为了加快网络传输速度,图片大小默认限制在 1M 以内,且建议对图片进行压缩处理,等比压缩到 [256, 512] 之间。 |
tag | String/Array<String> | 否 | 用于给图片或文本附加额外信息(比如:直播客户可能传房间号,或者主播 ID 信息)。方便后续根据 tag 搜索到相关的图片或文本;1. 支持多个 tag 参数,和 image 或 text 参数一一对应;2. 如果 tag 只有一个,或者 tag 数量少于 image 或 text ,缺省用最后一个 tag 补全(尾补全)。 |
task | String/Array<String> | 否 | 如果需要只执行接口下的某些审核的任务,可通过此参数指定,任务 ID 的形式,如:54bcfc6c329af61034f7c2fc 。不传该参数的话,执行该接口下的全部审核任务。 |
sequenceId | String/Array<String> | 否 | 连续帧图的组别 ID,例如直播间 ID 等,基于此 ID 进行该 ID 组别下的连续帧相似度识别(启用连续帧相似度识别服务必传)。 1. 支持多个 sequenceId 参数,和 image 参数按照顺序一一对应;2. 需要保证同一 sequenceId 下的图片帧,在同一请求中唯一,并且在不同请求间按照时间顺序有一定的间隔(防止乱序) |
referer | String | 否 | 图普根据图片 url 下载图片时,将其赋值给 HTTP Header 的 Referer,用于图片防盗链。 |
timestamp | Number | 是 | 当前的服务器的 Unix 时间戳,可以是毫秒或秒级。 |
nonce | Number | 是 | 随机数,建议是 [0-1] 之间的小数,如:0.1527317095951506 。 |
signature | String | 是 |
|
2.2 通过图片 base64 调用
QPS 限制
- 1 秒最多允许请求 50 次;
- 1 个请求最多携带 10 张图片;
- 每个请求总大小必须小于等于 30MB(json body 总大小)
如有特殊并发需求,请联系我们。
2.2.1 请求地址
区域 | 请求地址 |
---|---|
国内 | http://api.open.tuputech.com/v3/recognition/image/sync/base64/<secretId> |
国外 | http://api-us.open.tuputech.com/v3/recognition/image/sync/base64/<secretId> |
国外 | http://api-oversea.open.tuputech.com/v3/recognition/image/sync/base64/<secretId> |
提示
- <secretId> 需替换为您的
secretId
,请联系我们为您开通secretId
。 - 如果您的图片服务器在国外,请通过国外域名调用,避免图片下载失败或超时。
2.2.2 请求方法
POST
2.2.3 请求头
Content-Type: application/json
2.2.4 请求参数说明
参数名称 | 类型 | 是否必需 | 说明 |
---|---|---|---|
images | Array<String> | 是 | 1. 图片列表,列表元素内容为图片 base64 内容; 2. 支持的图片格式:png、jpg、jpeg、tif、webp、bmp、gif; 3. 为了加快网络传输速度,图片大小必须在 1M 以内,且建议对图片进行压缩处理,等比压缩到 [256, 512] 之间,再进行 base64 编码 |
tags | Array<String> | 否 | 用于给图片或文本附加额外信息(比如:直播客户可能传房间号,或者主播 ID 信息)。方便后续根据 tag 搜索到相关的图片或文本。2. tags 数目和 images 参数一一对应;3. 如果 tags 只有一个,或者 tags 数量少于 image 或 text ,缺省用最后一个 tag 补全(尾补全)。 |
tasks | Array<String> | 否 | 如果需要只执行接口下的某些审核的任务,可通过此参数指定,任务 ID 的形式,如:["54bcfc6c329af61034f7c2fc"] 。不传该参数的话,执行该接口下的全部审核任务。 |
timestamp | Number | 是 | 当前的服务器的 Unix 时间戳,可以是毫秒或秒级。 |
nonce | Number | 是 | 随机数,建议是 [0-1] 之间的小数,如:0.1527317095951506 。 |
signature | String | 是 |
|
2.3 通过上传图片文件调用
QPS 限制
- 1 秒最多允许请求 50 次;
- 1 个请求最多携带 10 张图片;
如有特殊并发需求,请联系我们。
2.3.1 请求地址
区域 | 请求地址 |
---|---|
国内 | http://api.open.tuputech.com/v3/recognition/<secretId> |
国外 | http://api-us.open.tuputech.com/v3/recognition/<secretId> |
国外 | http://api-oversea.open.tuputech.com/v3/recognition/<secretId> |
提示
- <secretId> 需替换为您的
secretId
,请联系我们为您开通secretId
。 - 如果您的图片服务器在国外,请通过国外域名调用,避免图片下载失败或超时。
2.3.2 请求方法
POST
2.3.3 请求头
Content-Type: multipart/form-data
2.3.4 请求参数说明
参数名称 | 类型 | 是否必需 | 说明 |
---|---|---|---|
image | File/String | 是 | 1. 支持多个 image 参数,也就是上传多个图片文件;2. 本接口也支持传入图片链接,但建议通过 JSON 调用; 3. 支持的图片格式:png、jpg、jpeg、tif、webp、bmp、gif、heif; 4. 为了加快网络传输速度,图片大小必须在 1M 以内,且建议对图片进行压缩处理,等比压缩到 [256, 512] 之间。 |
tag | String | 否 | 用于给图片或文本附加额外信息(比如:直播客户可能传房间号,或者主播 ID 信息)。方便后续根据 tag 搜索到相关的图片或文本。1. 支持多个 tag 参数,和 image 或 text 参数一一对应;2. 如果 tag 只有一个,或者 tag 数量少于 image 或 text ,缺省用最后一个 tag 补全(尾补全)。 |
task | String | 否 | 如果需要只执行接口下的某些审核的任务,可通过此参数指定,任务 ID 的形式,如:54bcfc6c329af61034f7c2fc 。不传该参数的话,执行该接口下的全部审核任务。 |
sequenceId | String | 否 | 连续帧 id,用于连续帧相似度识别模型。 1. 支持多个 sequenceId 参数,和 image 参数一一对应;2. 如果 sequenceId 只有一个,或者 sequenceId 数量少于 image ,缺省用最后一个 sequenceId 补全(尾补全);3. 建议按照图片帧的出现顺序分别调用接口,而非在一次请求中传入多张图片帧。 |
referer | String | 否 | 图普根据图片 url 下载图片时,将其赋值给 HTTP Header 的 Referer,用于图片防盗链。 |
timestamp | Number | 是 | 当前的服务器的 Unix 时间戳,可以是毫秒或秒级。 |
nonce | Number | 是 | 随机数,建议是 [0-1] 之间的小数,如:0.1527317095951506 。 |
signature | String | 是 |
|
2.4 curl 请求示例
- 单图
curl -X POST --header 'Content-Type: multipart/form-data' \
-F 'image=@your_image_file_path_or_url' \
-F 'timestamp=1553249299' \
-F 'nonce=0.04708760756305974' \
-F 'signature=your_signature' \
'http://api.open.tuputech.com/v3/recognition/your_secret_id'
- 多图
curl -X POST --header 'Content-Type: multipart/form-data' \
-F 'image=@your_image_file_path_or_url_0' \
-F 'image=@your_image_file_path_or_url_1' \
-F 'timestamp=1553249299' \
-F 'nonce=0.04708760756305974' \
-F 'signature=your_signature' \
'http://api.open.tuputech.com/v3/recognition/your_secret_id'
指定任务的 curl 请求示例
- task 指定只跑色情任务
curl -X POST --header 'Content-Type: multipart/form-data' \
-F 'image=@your_image_file_path_or_url' \
-F 'timestamp=1553249299' \
-F 'task=54bcfc6c329af61034f7c2fc' \
-F 'nonce=0.04708760756305974' \
-F 'signature=your_signature' \
'http://api.open.tuputech.com/v3/recognition/your_secret_id'
- task 指定跑色情、暴恐任务
curl -X POST --header 'Content-Type: multipart/form-data' \
-F 'image=@your_image_file_path_or_url' \
-F 'timestamp=1553249299' \
-F 'task=54bcfc6c329af61034f7c2fc' \
-F 'task=5e1d70adeec2874f7318dc52' \
-F 'nonce=0.04708760756305974' \
-F 'signature=your_signature' \
'http://api.open.tuputech.com/v3/recognition/your_secret_id'
3. 返回
3.1 公共返回参数
参数名 | 类型 | 是否必有 | 说明 |
---|---|---|---|
signature | String | 是 | 响应经过 JSON 字符串转义后的签名。我们采用的数字证书签名算法是:RSA-SHA256 ,签名输出类型是:base64 ,首先下载图普科技的公钥证书,然后按如下步骤认证:1. 接口返回的响应含两个字段:signature 和 json,signature 是数字签名,json 是真正的有效数据的字符串格式; 2. 用 signature 对 json 进行签名认证,算法: RSA-SHA256 ,输出类型:base64 ,得到认证结果;3. 认证通过后,对 json 字符串解析,得到实际审核结果数据,详见 json 字段说明。 |
json | String | 是 | JSON 字符串,是实际审核结果数据。含: message:与 code 相关的文本信息 timestamp:当前的服务器的 Unix 时间戳。 nonce:随机数。 |
3.2 公共返回示例
{
"signature": "signature_from_tupu_service",
"json": "{\"code\":0,\"message\":\"success\",\"nonce\":\"0.5442530125172196\",\"timestamp\":1595318082309}"
}
3.3 业务返回参数
参数名 | 类型 | 是否必有 | 说明 |
---|---|---|---|
code | Number | 是 | 请求的状态码,参考 服务公共状态码解析 |
message | String | 是 | 请求的状态信息 |
timestamp | Number | 是 | 当前的服务器的 Unix 时间戳 |
nonce | Number | 是 | 随机数 |
summary | Array<Object> | 是 | 应用下所有任务的汇总结果,数组长度与入参图片数量对应,针对汇总结果的说明可以参考 汇总结果解析。summary 参数详见 Summary 参数说明 |
taskId | Object | 是 | 识别任务的结果,每个识别任务会有 全局固定不变 的 taskId 和对应数据结构,请参考审核结果示例中的 54bcfc6c329af61034f7c2fc 。具体各识别任务的返回结果数据结构,请参考 具体任务识别结果 页面,例如 色情识别 |
... | ... | 否 | 其它识别及请求响应结果信息 |
Summary 参数说明
参数名 | 类型 | 是否必有 | 说明 |
---|---|---|---|
code | Number | 是 | 请求的状态码,参考 服务公共状态码解析 |
name | String | 是 | 图片 url 或文件名 |
suggestion | Number | 否 | 建议的操作,请参看 汇总结果解析中的 Suggestion 处理建议说明 |
riskType | Number | 否 | 风险类型,请参看 汇总结果解析中的 RiskType 风险类型说明 |
riskTask | String | 否 | 风险任务 ID |
tag | String | 否 | 图片自定义描述 |
注意:针对识别结果一般结果返回会解析 label
+ review
。label
对应该各的识别结果,review
对应是否复审。识别分数高于阈值的即返回 review=false
,即机器确定自己的判断结果;识别分数低于阈值的即返回 review=true
,即机器对自己的判断结果保留,建议人工复审。
3.4 业务返回示例
接口响应 json
字段经过解析后得到如下数据结构。
{
"code": 0,
"message": "success",
"timestamp": 1435385737,
"nonce": 0.010413094889372587,
"summary": [{
"code": 0,
"message": "success",
"name": "http://test.com/test1.jpg",
"suggestion": 0,
"riskType": 1,
"riskTask": "<风险任务 id>",
"tag": "t1"
},
{
"code": 14,
"message": "download fail",
"name": "http://test.com/test2.jpg",
"tag": "t2"
}
],
"54bcfc6c329af61034f7c2fc": {
"statistic": [
0,
0,
1
],
"reviewCount": 0,
"fileList": [{
"rate": 0.9927366971969604,
"label": 2,
"name": "http://tuputech.com/test.jpg",
"tag": "some_tag",
"zip": "zip_file_name",
"review": false,
"subLabel": {
"label": 30,
"rate": 0.99,
"review": false
},
"subLabels": [{
"label": "隐晦性行为",
"rate": 0.989293
}, {
"label": "女性只露肩膀",
"rate": 0.774093
}]
}]
}
}