1. 接口描述
接口请求域名: ims.tencentcloudapi.com 。
本接口(Image Moderation, IM)用于提交图片文件进行同步智能审核任务。使用前请您使用腾讯云主账号登录控制台 开通图片内容安全服务 并调整好对应的业务配置。
接口使用说明:
- 前往“内容安全控制台-图片内容安全”开启使用图片内容安全服务,首次开通服务的用户可免费领用试用套餐包,包含3000张图片识别额度,有效期为15天。
- 该接口为收费接口,计费方式敬请参见 腾讯云图片内容安全定价。
接口功能说明:
- 支持对图片文件或链接进行检测,通过深度学习技术,识别可能令人反感、不安全或不适宜的违规图片内容;
- 支持对GIF图/长图进行截帧或拆分检测;
- 支持识别多种违规场景,包括:低俗、违法违规、色情、广告等场景;
- 支持多种物体检测(实体、广告台标、二维码等)及图片中文本的OCR文本识别;
- 支持根据不同的业务场景配置自定义的审核策略;
- 支持用户自定义选择图片风险库,打击自定义识别类型的违规图片(目前仅支持黑名单配置);
- 支持在审核图片内容时同时关联账号或设备信息,可识别违规风险账号或设备。
接口调用说明:
- 图片文件大小限制:图片文件须大于256字节,Base64编码后的FileContent内容应小于10MB,FileURL的源图应小于30MB;
- 图片默认尺寸支持:长和宽 需>50分辨率且<10000分辨率,并且图片长宽比<90:1;
- 图片文件分辨率支持:建议分辨率大于256x256,否则可能会影响识别效果;
- 图片文件支持格式(无备注默认只支持静态图):BMP、ICO、JPEG、JNG、PNG、TIFF、RAW、SVG、GIF(静、动)、WEBP(静、动)、HEIC(静、动),动图在处理时,默认最多抽取5帧图像,并且每隔5帧进行一次采样;
- 图片文件链接支持的传输协议:HTTP、HTTPS;
- 图片审核仅支持单次传输一条URL进行审核,支持多并发请求。默认并发为100 QPS,超过此限制将返回
RequestLimitExceeded
错误; - 若传入图片文件的访问链接时,为保障被检测图片的稳定性和可靠性,建议您使用腾讯云COS存储或者CDN缓存等。
图片下载说明:
- 下载时间限制:图片首次下载限制为3秒。如超过此时间,将重试一次,重试时间为3秒。如果重试仍超时,将返回
ImageDownloadError
(下载超时); - 网络安全策略:由于网络安全策略,带有重定向的链接(如HTTP返回302状态码)可能导致下载失败。请尽量避免使用此类链接,以确保下载顺利进行,可能返回
ResourceUnavailable.ImageDownloadError
; - 异步回源支持:目前不支持通过异步回源方式获取图片源。请确保使用直接链接,以避免下载失败。
关于版本迭代的描述
当前页面版本为图片内容安全2020版本,2020.11.3日前接入的图片内容安全接口为2019版本,在此时间前接入的用户可直接访问以下链接进行维护操作:图片内容安全-2019版本
2020版本相对2019版本进行了升级,支持更灵活的多场景业务策略配置以及更丰富的识别回调信息,满足不同业务的识别需求,建议按照2020版本接入指引进行接口升级;同时,2019版本也会持续维护直至用户不再使用为止。
默认接口请求频率限制:100次/秒。
推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。
2. 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见 公共请求参数。
参数名称 | 必选 | 类型 | 描述 |
---|---|---|---|
Action | 是 | String | 公共参数,本接口取值:ImageModeration。 |
Version | 是 | String | 公共参数,本接口取值:2020-12-29。 |
Region | 是 | String | 公共参数,详见产品支持的 地域列表。 |
BizType | 否 | String | 该字段表示策略的具体编号,用于接口调度,在内容安全控制台中可配置。若不传入Biztype参数(留空),则代表采用默认的识别策略;传入则会在审核时根据业务场景采取不同的审核策略。 备注:Biztype仅为数字、字母与下划线的组合,长度为3-32个字符;不同Biztype关联不同的业务场景与识别能力策略,调用前请确认正确的Biztype。 示例值:182600012300002017 |
DataId | 否 | String | 该字段表示您为待检测对象分配的数据ID,传入后可方便您对文件进行标识和管理。 取值:由英文字母(大小写均可)、数字及四个特殊符号(_,-,@,#)组成,长度不超过64个字符。 示例值:a61237dd-c2a0-43e7-a3da-d27022d39ba7 |
FileContent | 否 | String | 该字段表示待检测图片文件内容的Base64编码,由于云API对请求包体有大小限制,图片的Base64编码内容大小不得超过10MB。 备注:该字段与FileUrl必须选择输入其中一个。 示例值:aHR0cDovL2lubmVycG9ybnNjcmVlbnNob3QtMTI1MjgxMzg1MC5jb3MuYXAtZ3Vh |
FileUrl | 否 | String | 该字段表示待检测图片文件的访问链接,URL源图大小不超过30MB。 备注:该字段与FileContent必须选择输入其中一个。 示例值:https://cmstest-123.cos.ap-guangzhou.myqcloud.com/image.jpg |
Interval | 否 | Integer | GIF检测专用,用于表示GIF截帧频率(每隔多少张图片抽取一帧进行检测);默认值为0,此时只会检测GIF的第一帧或不进行切分处理。 备注:Interval与MaxFrames参数需要组合使用。例如,Interval=3, MaxFrames=400,则代表在检测GIF时,将每间隔2帧检测一次且最多检测400帧。 示例值:0 |
MaxFrames | 否 | Integer | GIF检测专用,用于标识最大截帧数量;默认值为1,此时只会检测输入GIF的第一帧不进行切分处理(可能会造成处理超时)。 备注:Interval与MaxFrames参数需要组合使用。例如,Interval=3, MaxFrames=400,则代表在检测GIF时,将每间隔2帧检测一次且最多检测400帧。 示例值:5 |
User | 否 | User | 该字段表示待检测对象对应的用户相关信息,若填入则可甄别相应违规风险用户。 |
Device | 否 | Device | 该字段表示待检测对象对应的设备相关信息,若填入则可甄别相应违规风险设备。 |
3. 输出参数
参数名称 | 类型 | 描述 |
---|---|---|
Suggestion | String | 该字段用于返回Label标签下的后续操作建议。当您获取到判定结果后,返回值表示系统推荐的后续操作;建议您按照业务所需,对不同违规类型与建议值进行处理。 返回值:Block:建议屏蔽,Review :建议人工复审,Pass:建议通过 示例值:Block |
Label | String | 该字段用于返回检测结果(LabelResults)中所对应的优先级最高的恶意标签,表示模型推荐的审核结果,建议您按照业务所需,对不同违规类型与建议值进行处理。 返回值:Normal:正常,Porn:色情,Abuse:谩骂,Ad:广告;以及其他令人反感、不安全或不适宜的内容类型。 示例值:Porn |
SubLabel | String | 该字段用于返回检测结果所命中优先级最高的恶意标签下的子标签名称,如:色情--性行为;若未命中任何子标签则返回空字符串。 示例值:SexyBehavior |
Score | Integer | 该字段用于返回当前标签(Label)下的置信度,取值范围:0(置信度最低)-100(置信度最高 ),越高代表图片越有可能属于当前返回的标签;如:色情 99,则表明该图片非常有可能属于色情内容;色情 0,则表明该图片不属于色情内容。 示例值:90 |
LabelResults | Array of LabelResult | 该字段用于返回分类模型命中的恶意标签的详细识别结果,包括涉黄、广告等令人反感、不安全或不适宜的内容类型识别结果。 注意:此字段可能返回 null,表示取不到有效值。 |
ObjectResults | Array of ObjectResult | 该字段用于返回物体检测模型的详细检测结果;包括:实体、广告台标、二维码等内容命中的标签名称、标签分数、坐标信息、场景识别结果、建议操作等内容审核信息;详细返回值信息可参阅对应的数据结构(ObjectResults)描述。 注意:此字段可能返回 null,表示取不到有效值。 |
OcrResults | Array of OcrResult | 该字段用于返回OCR文本识别的详细检测结果;包括:文本坐标信息、文本识别结果、建议操作等内容审核信息;详细返回值信息可参阅对应的数据结构(OcrResults)描述。 注意:此字段可能返回 null,表示取不到有效值。 |
LibResults | Array of LibResult | 该字段用于返回基于图片风险库(风险黑库与正常白库)识别的结果,详细返回值信息可参阅对应的数据结构(LibResults)描述。 备注:图片风险库目前暂不支持自定义库。 注意:此字段可能返回 null,表示取不到有效值。 |
DataId | String | 该字段用于返回检测对象对应请求参数中的DataId。 示例值:a61237dd-c2a0-43e7-a3da-d27022d39ba7 |
BizType | String | 该字段用于返回检测对象对应请求参数中的BizType。 示例值:182600012300002017 |
Extra | String | 该字段用于返回根据您的需求配置的额外附加信息(Extra),如未配置则默认返回值为空。 备注:不同客户或Biztype下返回信息不同,如需配置该字段请提交工单咨询或联系售后专员处理。 注意:此字段可能返回 null,表示取不到有效值。 |
FileMD5 | String | 该字段用于返回检测对象对应的MD5校验值,以方便校验文件完整性。 |
RecognitionResults | Array of RecognitionResult | 该字段用于返回仅识别图片元素的模型结果;包括:场景模型命中的标签、置信度和位置信息 注意:此字段可能返回 null,表示取不到有效值。 |
RequestId | String | 唯一请求 ID,由服务端生成,每次请求都会返回(若请求因其他原因未能抵达服务端,则该次请求不会获得 RequestId)。定位问题时需要提供该次请求的 RequestId。 |
4. 示例
示例1 图片同步检测
图片同步检测
输入示例
POST / HTTP/1.1
Host: ims.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: ImageModeration
<公共请求参数>
{
"BizType": "182600012300002017",
"DataId": "a61237dd-c2a0-43e7-a3da-d27022d39ba7",
"FileUrl": "https://cmstest-123.cos.ap-guangzhou.myqcloud.com/image.jpg"
}
输出示例
{
"Response": {
"RequestId": "a61237dd-c2a0-43e7-a3da-d27022d39ba7",
"DataId": "a61237dd-c2a0-43e7-a3da-d27022d39ba7",
"BizType": "182600012300002017",
"Suggestion": "Block",
"FileMD5": "",
"Label": "Porn",
"SubLabel": "SexyBehavior",
"Score": 90,
"LabelResults": [
{
"Scene": "Porn",
"Suggestion": "Block",
"Label": "Porn",
"SubLabel": "SexyBehavior",
"Score": 90,
"Details": []
}
],
"ObjectResults": [
{
"Scene": "QrCode",
"Suggestion": "Block",
"Label": "Ad",
"SubLabel": "",
"Score": 100,
"Names": [
"QRCODE"
],
"Details": [
{
"Id": 0,
"Name": "QRCODE",
"Value": "https://test.com/test",
"ObjectId": "",
"SubLabel": "QRCODE",
"Score": 100,
"Location": {
"X": 155.01746,
"Y": 396.01746,
"Width": 769.9824,
"Height": 769.98254,
"Rotate": 0
}
}
]
}
],
"OcrResults": [],
"LibResults": [],
"RecognitionResults": [],
"Extra": ""
}
}
5. 开发者资源
腾讯云 API 平台
腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台,方便您从同一入口查询及使用腾讯云提供的所有 API 服务。
API Inspector
用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况,并自动生成各语言版本的 API 代码,也可前往 API Explorer 进行在线调试。
SDK
云 API 3.0 提供了配套的开发工具集(SDK),支持多种编程语言,能更方便的调用 API。
- Tencent Cloud SDK 3.0 for Python: GitHub Gitee
- Tencent Cloud SDK 3.0 for Java: GitHub Gitee
- Tencent Cloud SDK 3.0 for PHP: GitHub Gitee
- Tencent Cloud SDK 3.0 for Go: GitHub Gitee
- Tencent Cloud SDK 3.0 for Node.js: GitHub Gitee
- Tencent Cloud SDK 3.0 for .NET: GitHub Gitee
- Tencent Cloud SDK 3.0 for C++: GitHub Gitee
- Tencent Cloud SDK 3.0 for Ruby: GitHub Gitee
命令行工具
6. 错误码
以下仅列出了接口业务逻辑相关的错误码,其他错误码详见 公共错误码。
错误码 | 描述 |
---|---|
DryRunOperation | DryRun 操作,代表请求将会是成功的,只是多传了 DryRun 参数。 |
FailedOperation | 操作失败。 |
InternalError | 内部错误。 |
InternalError.InternalError | 内部错误。 |
InvalidParameter | 参数错误。 |
InvalidParameter.ImageAspectRatioTooLarge | 图片长宽比太大 |
InvalidParameter.ImageDataTooSmall | 图片体积太小 |
InvalidParameter.ImageSizeTooSmall | 图片分辨率过低。 |
InvalidParameter.InvalidImageContent | 图片内容错误。 |
InvalidParameter.InvalidParameter | 参数不合法。 |
InvalidParameterValue | 参数取值错误。 |
InvalidParameterValue.EmptyImageContent | 图片内容参数为空。 |
InvalidParameterValue.ImageSizeTooSmall | 图片分辨率太低。 |
InvalidParameterValue.InvalidContent | FileContent和FileUrl为空或base64编码错误。 |
InvalidParameterValue.InvalidDataId | DataId格式错误。 |
InvalidParameterValue.InvalidFileContentSize | 图片文件内容大小异常。 |
InvalidParameterValue.InvalidImageContent | 图片内容错误。 |
InvalidParameterValue.InvalidParameter | 参数值错误。 |
LimitExceeded | 超过配额限制。 |
MissingParameter | 缺少参数错误。 |
OperationDenied | 操作被拒绝。 |
RequestLimitExceeded | 请求的次数超过了频率限制。 |
ResourceInUse | 资源被占用。 |
ResourceInsufficient | 资源不足。 |
ResourceNotFound | 资源不存在。 |
ResourceUnavailable | 资源不可用。 |
ResourceUnavailable.ImageDownloadError | 图片文件下载失败。 |
ResourceUnavailable.InvalidImageContent | 图片资源错误。 |
ResourceUnavailable.ModelCallFailed | 模型调用失败,请重试。 |
ResourcesSoldOut | 资源售罄。 |
UnauthorizedOperation | 未授权操作。 |
UnauthorizedOperation.Unauthorized | 未开通权限/无有效套餐包/账号已欠费。 |
UnknownParameter | 未知参数错误。 |
UnsupportedOperation | 操作不支持。 |