文档

FindImages - 搜索媒体集中图片

更新时间:

调用FindImages接口根据指定条件,例如时间、地点、标签、人物特征等,搜索媒体集中图片。并可以按照给定要求进行排序。

接口说明

  • 此接口已不再维护,建议使用新版(2020-09-30 版本)查询与统计相关接口。关于新版与旧版 API 的对比,请参见新旧版本使用指引中的新版与旧版 API 对应关系说明章节。
  • 搜索结果依赖索引的建立,返回结果与实际值可能有数秒的数据延迟。

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

授权信息

当前API暂无授权信息透出。

请求参数

名称类型必填描述示例值
Projectstring

项目名称。

immimagetest
SetIdstring

媒体集的唯一标识。

set001
ImageSizeRangestring

图片大小范围,使用 JSON 格式表示,格式为{"MinWidth":100,"MaxWidth":3000,"MinHeight":50,"MaxHeight":5000}

{"MinWidth":100,"MaxWidth":3000,"MinHeight":50,"MaxHeight":5000}
ImageTimeRangestring

图片的时间范围,该时间从 EXIF 信息获取,使用 JSON 格式表示,格式为 {"Start":"1970-01-01T00:00:01.544Z","End":"2199-01-01T00:00:01.544Z"}

{"Start":"2020-11-10T00:00:01.544Z","End":"2020-11-25T00:00:01.544Z"}
CreateTimeRangestring

图片加入媒体集的时间范围,使用 JSON 格式表示,格式为{"Start":"1970-01-01T00:00:01.544Z","End":"2199-01-01T00:00:01.544Z"}

{"Start":"2020-11-10T00:00:01.544Z","End":"2020-11-25T00:00:01.544Z"}
ModifyTimeRangestring

图片更新的时间范围,使用 JSON 格式表示,格式为 {"Start":"1970-01-01T00:00:01.544Z","End":"2199-01-01T00:00:01.544Z"}

{"Start":"2020-11-10T00:00:01.544Z","End":"2020-11-25T00:00:01.544Z"}
SourceTypestring

源数据的类型,包括如下选项:

  • image:图片
  • video:视频
image
SourceUriPrefixstring

图片的 OSS URI 的前缀。

oss://imm-test/
RemarksAPrefixstring

标记信息的前缀,用于前缀匹配。

remark
RemarksBPrefixstring

标记信息的前缀,用于前缀匹配。

remark
TagNamesstring

标签列表,设置多个标签时,请使用 JSON 格式表示,此时只有同时包含所有标签的图片才会返回,格式为["脸","人物"]。

["脸","人物"]
OCRContentsMatchstring

OCR 识别的内容搜索。

myh
AgeRangestring

年龄范围,使用 JSON 格式表示,格式为{"Start":0,"End":99}

{"Start":0,"End":99}
Genderstring

性别,可选值为 MALE 和 FEMALE。

MALE
Emotionstring

表情,可选值为 HAPPY、SAD、ANGRY、SURPRISED、SCARED、DISGUSTED 和 CALM。

HAPPY
OrderBystring

排序字段,可选值为 CreateTime、ModifyTime、ImageTime、FacesModifyTime、TagsModifyTime、RemarksA、RemarksB、RemarksC 和 RemarksD。

CreateTime
Orderstring

排序方式,可选值为 ASC 和 DESC。

  • ASC:升序
  • DESC:降序
ASC
Markerstring

从 Marker 开始按字典序返回图片信息列表。如果不设置此参数,则从头开始返回图片。

imm
LocationBoundarystring

地理位置范围,使用 JSON 格式表示,格式为{"TopLeft":"50.2,100.1","BottomRight":"30.5,120.1"}

其中 TopLeft(左上)和 BottomRight(右下)两个顶点的格式为lat,long,是以英文逗号(,)分隔的浮点数。

说明 Top 的值必须大于 Bottom 的值,Left 的值必须小于 Right 的值。
{"TopLeft":"50.2,100.1","BottomRight":"30.5,120.1"}
RemarksCPrefixstring

标记信息的前缀,用于前缀匹配。

remark
RemarksDPrefixstring

标记信息的前缀,用于前缀匹配。

remark
ExternalIdstring

外部 ID,用于和您的应用层的 ID(如果有)进行绑定。

externalId001
GroupIdstring

人脸分组 ID。如果人脸未分组,则此参数返回值为 group-not-grouped。

group-not-grouped
Limitinteger

返回图片的最大个数,默认值为 20,取值范围为 1~100。

20
FacesModifyTimeRangestring

人脸信息更新的时间范围,使用 JSON 格式表示,格式为{"Start":"1970-01-01T00:00:01.544Z","End":"2199-01-01T00:00:01.544Z"}

{"Start":"2020-11-10T00:00:01.544Z","End":"2020-11-25T00:00:01.544Z"}
TagsModifyTimeRangestring

标签信息更新的时间范围,使用 JSON 格式表示,格式为{"Start":"1970-01-01T00:00:01.544Z","End":"2199-01-01T00:00:01.544Z"}

{"Start":"2020-11-10T00:00:01.544Z","End":"2020-11-25T00:00:01.544Z"}
AddressLineContentsMatchstring

只有当 Location 有值,即带有地理信息标记的文件时,此参数才有效。

地址搜索。

zhejiang
RemarksArrayAInstring

只有图片的标签列表中存在至少一个标签匹配查询条件,则图片就会返回。

["remarka1","remarka2"]
RemarksArrayBInstring

只有图片的标签列表中存在至少一个标签匹配查询条件,则图片就会返回。

["remarkb1","remarkb2"]

返回参数

名称类型描述示例值
object
RequestIdstring

当次请求的 Request ID。

810FE908-522F-4951-8AF8-7211890D4B2A
Imagesobject []

图片信息列表。

CroppingSuggestionStatusstring

提供裁剪建议的状态,包括如下选项:

  • NotProcessed:未处理
  • Processing:处理中
  • Success:成功
  • Failed:失败

您可以根据该状态决定读取结果、等待或重试。

NotProcessed
ImageQualityModifyTimestring

图片质量打分的更新时间。

2020-11-25T10:12:59.57Z
TagsFailReasonstring

标签识别的失败原因。格式为[HTTPStatusCode ErrorCode] ErrorMessage,例如[400 InvalidResource] Specified resource is too large. Please check.

只有当标签识别失败时,此参数才有值。

Timeout
RemarksCstring

标记信息。

remarkc
CreateTimestring

图片加入媒体集的时间。

2020-11-25T10:12:59.57Z
SourceTypestring

源数据的类型。

image
FacesFailReasonstring

人脸识别的失败原因。

只有当人脸识别失败时,此参数才有值。

Timeout
Tagsobject []

标签识别结果。

TagConfidencefloat

标签置信度。

0.9812195897102356
CentricScorefloat

标签主体分数。用于提示该标签内容在图片中的主要程度,越高则说明该标签越可能为图片主体。取值范围为 0~1。

0
TagNamestring

标签名称。

TagLevelinteger

标签级别,取值范围为 1~4。

2
ParentTagNamestring

父级标签名称。

人物
FacesModifyTimestring

人脸识别的更新时间。

2020-11-25T10:12:59.57Z
ImageTimestring

图片的拍摄日期,该日期从 EXIF 信息中获取。

如果图片 EXIF 信息无此信息,则返回结果中无此参数。

2020-11-25T10:12:59.57Z
OCRModifyTimestring

OCR 识别的更新时间。

2020-11-25T10:12:59.57Z
AddressModifyTimestring

图片地理位置检测的更新时间。

2020-11-25T10:12:59.57Z
OCRobject []

OCR 识别结果。

OCRConfidencefloat

文字置信度。

0.8254936695098877
OCRContentsstring

文字内容。

欢迎使用智能媒体管理
OCRBoundaryobject

文字位置框信息。

Topinteger

顶点 Y 坐标,距离顶端距离。

12
Widthinteger

文字位置框宽度。单位为 px。

12
Heightinteger

文字位置框高度。单位为 px。

12
Leftinteger

顶点 X 坐标,距离左端距离。单位为 px。

12
ImageQualityFailReasonstring

图片质量打分的失败原因。

Timeout
FacesStatusstring

人脸识别的状态,包括如下选项:

  • NotProcessed:未处理
  • Processing:处理中
  • Success:成功
  • Failed:失败

您可以根据该状态决定读取结果、等待或重试。

Success
ImageHeightinteger

图片高度。

861
RemarksArrayAstring

标记信息列表。

["remarka1","remarka2"]
Addressobject

图片地理位置检测结果。

只有图片带有地理位置信息时,检测结果才有值。

Townshipstring

图片地理位置所在街道(或同级)。

转塘街道
Districtstring

图片地理位置所在区(或同级)。

西湖区
AddressLinestring

图片地理位置的完整地址。

浙江省杭州市西湖区转塘街道石龙山西路
Countrystring

图片地理位置所在国家或地区。

中国
Citystring

图片地理位置所在城市(或同级)。

杭州市
Provincestring

图片地理位置所在省(或同级)。

浙江省
ExternalIdstring

外部 ID,用于和您的应用层的 ID(如果有)进行绑定。

externalId001
SourceUristring

图片 OSS URI。

oss://imm-test/testcases/face1.jpg
ModifyTimestring

图片的修改时间。

添加图片后,如果未修改过图片,则图片的修改时间和图片的创建时间相同。

2020-11-25T10:12:59.57Z
FileSizeinteger

文件大小,单位为字节。

69732
SourcePositionstring

只有当 SourceType 为 video 时,此参数才生效。

视频中该图片帧处于源视频的时间轴位置。格式为00000000.010,即%8.3f。

00000000.010
Facesobject []

人脸识别结果。

Genderstring

性别,可选项包括 MALE 和 FEMALE。

FEMALE
FaceIdstring

人脸 ID。

59edc040d0a8f4952b183d1b5044913a0ccd8739500ee2705ffe4965a0406a51
GenderConfidencefloat

性别置信度。

1
FaceAttributesobject

人脸其他属性。

GlassesConfidencefloat

是否戴眼镜置信度。

1
Glassesstring

是否带眼镜。

NONE
Maskstring

是否带口罩。

NONE
BeardConfidencefloat

是否有胡子置信度。

1
MaskConfidencefloat

是否带口罩置信度。

1
FaceBoundaryobject

人脸位置框信息。

Topinteger

顶点 Y 坐标,距离顶端距离。单位为 px。

152
Widthinteger

人脸位置框宽度。单位为 px。

139
Heightinteger

人脸位置框高度。单位为 px。

141
Leftinteger

顶点 X 坐标,距离左端距离。单位为 px。

267
HeadPoseobject

头部朝向。

Pitchfloat

人脸的俯仰角,取值范围为-180~+180度,可信的范围建议为-30~+30度。

18.385589599609375
Rollfloat

面内偏转角,取值范围为-180~+180度,可信的建议范围为-45~+45度。

4.204030513763428
Yawfloat

人脸的左右偏转角,取值范围为-180~+180度,可信的范围建议为-80~+80度。

2.4945924282073975
Beardstring

是否有胡子。

NONE
FaceQualityfloat

人脸质量。

0.9321779608726501
Emotionstring

心情。

HAPPY
Ageinteger

年龄。

29
FaceConfidencefloat

人脸置信度。

0.9608758687973022
EmotionConfidencefloat

心情置信度。

0.7079545259475708
Attractivefloat

人脸吸引力,分数越高吸引力越强,取值范围为 0~1。

0.96
GroupIdstring

人脸分组 ID。如果人脸未分组,则此参数返回值为 group-not-grouped。

group-not-grouped
EmotionDetailsobject

七种心情对应的置信度。

HAPPYfloat

HAPPY 心情置信度。

0.7079545259475708
SURPRISEDfloat

SURPRISED 心情置信度。

0.00006676767952740192
CALMfloat

CALM 心情置信度。

0.2918718755245209
DISGUSTEDfloat

DISGUSTED 心情置信度。

0.000033771051676012576
ANGRYfloat

ANGRY 心情置信度。

0.00001282201901631197
SADfloat

SAD 心情置信度。

0.00001527295717096422
SCAREDfloat

SCARED 心情置信度。

0.0000014976058082538657
ImageQualityStatusstring

图片质量打分状态,包括如下选项:

  • NotProcessed:未处理
  • Processing:处理中
  • Success:成功
  • Failed:失败

您可以根据该状态决定读取结果、等待或重试。

Success
OCRFailReasonstring

OCR 识别的失败原因。

Timeout
AddressFailReasonstring

图片地理位置检测的失败原因。

只有当图片地理位置检测失败时,此参数才有值。

Timeout
ImageQualityobject

图片质量分数。

OverallScorefloat

综合质量分数。

0.7759467363357544
Colorfloat

当前版本不支持此参数。

图片色度。

0.6101377010345459
ColorScorefloat

当前版本不支持此参数。

图片色度的分数。

0.6101377010345459
ContrastScorefloat

当前版本不支持此参数。

图片对比度的分数。

0.6101377010345459
Contrastfloat

当前版本不支持此参数。

图片对比度。

0.6101377010345459
ExposureScorefloat

当前版本不支持此参数。

图片曝光程度的分数。

0.6101377010345459
ClarityScorefloat

当前版本不支持此参数。

图片清晰度的分数。

0.6101377010345459
Clarityfloat

当前版本不支持此参数。

图片清晰度。

0.6101377010345459
Exposurefloat

当前版本不支持此参数。

图片曝光程度。

0.6101377010345459
CompositionScorefloat

当前版本不支持此参数。

图片构成的分数。

0.6101377010345459
CroppingSuggestionModifyTimestring

提供最新裁剪建议的时间。

2020-11-25T10:12:59.57Z
ImageFormatstring

图片格式。

jpg
ImageWidthinteger

图片宽度。

500
RemarksArrayBstring

标记信息列表。

["remarkb1","remarkb2"]
CroppingSuggestionobject []

图片的裁减建议。

Scorefloat

该裁剪方案的美学分数,分数越高表示该方案效果越好,取值范围为 0~1。

0.8979608535766602
CroppingBoundaryobject

裁剪框。

Topinteger

顶点 Y 坐标,距离顶端距离。单位为 px。

77
Widthinteger

裁剪框宽度。单位为 px。

500
Heightinteger

裁剪框高度。单位为 px。

499
Leftinteger

顶点 X 坐标,距离左端距离。单位为 px。

0
AspectRatiostring

图片裁剪比例列表。

1:1
Orientationstring

图片旋转值,从 EXIF 信息中获取。

如果图片 EXIF 信息无此信息,则返回结果中无此参数。

{"val":"Right-top","type":3}
RemarksDstring

标记信息。

remarkd
TagsStatusstring

标签识别的状态,包括如下选项:

  • NotProcessed:未处理
  • Processing:处理中
  • Success:成功
  • Failed:失败

您可以根据该状态决定读取结果、等待或重试。

Success
CroppingSuggestionFailReasonstring

裁剪建议提供失败的原因。

只有当图片裁剪建议提供失败时,此参数才有值。

Timeout
RemarksAstring

标记信息。

remarka
ImageUristring

图片的 OSS URI。

oss://imm-test/testcases/face1.jpg
TagsModifyTimestring

标签识别的更新时间。当 TagsStatus 更改时更新。

2020-11-25T10:12:59.57Z
OCRStatusstring

OCR 识别的状态,包括如下选项:

  • NotProcessed:未处理
  • Processing:处理中
  • Success:成功
  • Failed:失败

您可以根据该状态决定读取结果、等待或重试。

NotProcessed
AddressStatusstring

图片地理位置检测的状态,包括如下选项:

  • NotProcessed:未处理
  • Processing:处理中
  • Success:成功
  • Failed:失败

您可以根据该状态决定读取结果、等待或重试。

Success
Exifstring

图片原始 EXIF 信息,以 JSON Object 序列化后的格式存储。

{"FileSize":{"value":"29304"},"Format":{"value":"jpg"},"ImageHeight":{"value":"417"},"ImageWidth":{"value":"500"},"ResolutionUnit":{"value":"2"},"XResolution":{"value":"96/1"},"YResolution":{"value":"96/1"}}
Locationstring

图片地理位置,从 EXIF 信息中获取,格式为lat,long,以英文逗号(,)分隔的浮点数。

如果图片 EXIF 信息无此信息,则返回结果中无此参数。

30.134390,120.074997
RemarksBstring

标记信息。

remarkb
NextMarkerstring

下一次列出图片信息时以此值为 Marker,将未返回的结果返回。

当图片未全部返回时,此参数才有值。

CAESBgoEIgIIABgAIswBCskBA8QAAAAxUzMxMzczNDM2MzQzOTM1MzgzNTM3MzYzMDMyMzczNDM1M2E2OTZkNmQ2OTZkNjE2NzY1M2E3MzY1NzQzMDMwMzEzYTMxMzYzMzM1NjIzOTMzMzI2MTYyMzQzNzY2NjMzNjY2NjI2MTYxMzMzMjM1MzQzOTMzMzQzNzMwMzI2NTMxNjE2MjM3MzczMTY0NjM2NDM2MzgzNjM4NjQzMjM2MzEzNzM2MzYzNjM4NjUzNTYyMzc2NjM0MzU2MjYxNjE2NTMx
SetIdstring

媒体集的唯一标识。

set001

示例

正常返回示例

JSON格式

{
  "RequestId": "810FE908-522F-4951-8AF8-7211890D4B2A",
  "Images": [
    {
      "CroppingSuggestionStatus": "NotProcessed",
      "ImageQualityModifyTime": "2020-11-25T10:12:59.57Z",
      "TagsFailReason": "Timeout",
      "RemarksC": "remarkc",
      "CreateTime": "2020-11-25T10:12:59.57Z",
      "SourceType": "image",
      "FacesFailReason": "Timeout",
      "Tags": [
        {
          "TagConfidence": 0.9812195897102356,
          "CentricScore": 0,
          "TagName": "脸",
          "TagLevel": 2,
          "ParentTagName": "人物"
        }
      ],
      "FacesModifyTime": "2020-11-25T10:12:59.57Z",
      "ImageTime": "2020-11-25T10:12:59.57Z",
      "OCRModifyTime": "2020-11-25T10:12:59.57Z",
      "AddressModifyTime": "2020-11-25T10:12:59.57Z",
      "OCR": [
        {
          "OCRConfidence": 0.8254936695098877,
          "OCRContents": "欢迎使用智能媒体管理",
          "OCRBoundary": {
            "Top": 12,
            "Width": 12,
            "Height": 12,
            "Left": 12
          }
        }
      ],
      "ImageQualityFailReason": "Timeout",
      "FacesStatus": "Success",
      "ImageHeight": 861,
      "RemarksArrayA": "[\"remarka1\",\"remarka2\"]",
      "Address": {
        "Township": "转塘街道",
        "District": "西湖区",
        "AddressLine": "浙江省杭州市西湖区转塘街道石龙山西路",
        "Country": "中国",
        "City": "杭州市",
        "Province": "浙江省"
      },
      "ExternalId": "externalId001",
      "SourceUri": "oss://imm-test/testcases/face1.jpg",
      "ModifyTime": "2020-11-25T10:12:59.57Z",
      "FileSize": 69732,
      "SourcePosition": "00000000.010",
      "Faces": [
        {
          "Gender": "FEMALE",
          "FaceId": "59edc040d0a8f4952b183d1b5044913a0ccd8739500ee2705ffe4965a0406a51",
          "GenderConfidence": 1,
          "FaceAttributes": {
            "GlassesConfidence": 1,
            "Glasses": "NONE",
            "Mask": "NONE",
            "BeardConfidence": 1,
            "MaskConfidence": 1,
            "FaceBoundary": {
              "Top": 152,
              "Width": 139,
              "Height": 141,
              "Left": 267
            },
            "HeadPose": {
              "Pitch": 18.385589599609375,
              "Roll": 4.204030513763428,
              "Yaw": 2.4945924282073975
            },
            "Beard": "NONE"
          },
          "FaceQuality": 0.9321779608726501,
          "Emotion": "HAPPY",
          "Age": 29,
          "FaceConfidence": 0.9608758687973022,
          "EmotionConfidence": 0.7079545259475708,
          "Attractive": 0.96,
          "GroupId": "group-not-grouped",
          "EmotionDetails": {
            "HAPPY": 0.7079545259475708,
            "SURPRISED": 0.00006676767952740192,
            "CALM": 0.2918718755245209,
            "DISGUSTED": 0.000033771051676012576,
            "ANGRY": 0.00001282201901631197,
            "SAD": 0.00001527295717096422,
            "SCARED": 0.0000014976058082538657
          }
        }
      ],
      "ImageQualityStatus": "Success",
      "OCRFailReason": "Timeout",
      "AddressFailReason": "Timeout",
      "ImageQuality": {
        "OverallScore": 0.7759467363357544,
        "Color": 0.6101377010345459,
        "ColorScore": 0.6101377010345459,
        "ContrastScore": 0.6101377010345459,
        "Contrast": 0.6101377010345459,
        "ExposureScore": 0.6101377010345459,
        "ClarityScore": 0.6101377010345459,
        "Clarity": 0.6101377010345459,
        "Exposure": 0.6101377010345459,
        "CompositionScore": 0.6101377010345459
      },
      "CroppingSuggestionModifyTime": "2020-11-25T10:12:59.57Z",
      "ImageFormat": "jpg",
      "ImageWidth": 500,
      "RemarksArrayB": "[\"remarkb1\",\"remarkb2\"]",
      "CroppingSuggestion": [
        {
          "Score": 0.8979608535766602,
          "CroppingBoundary": {
            "Top": 77,
            "Width": 500,
            "Height": 499,
            "Left": 0
          },
          "AspectRatio": "1:1"
        }
      ],
      "Orientation": "{\"val\":\"Right-top\",\"type\":3}",
      "RemarksD": "remarkd",
      "TagsStatus": "Success",
      "CroppingSuggestionFailReason": "Timeout",
      "RemarksA": "remarka",
      "ImageUri": "oss://imm-test/testcases/face1.jpg",
      "TagsModifyTime": "2020-11-25T10:12:59.57Z",
      "OCRStatus": "NotProcessed",
      "AddressStatus": "Success",
      "Exif": "{\"FileSize\":{\"value\":\"29304\"},\"Format\":{\"value\":\"jpg\"},\"ImageHeight\":{\"value\":\"417\"},\"ImageWidth\":{\"value\":\"500\"},\"ResolutionUnit\":{\"value\":\"2\"},\"XResolution\":{\"value\":\"96/1\"},\"YResolution\":{\"value\":\"96/1\"}}",
      "Location": "30.134390,120.074997",
      "RemarksB": "remarkb"
    }
  ],
  "NextMarker": "CAESBgoEIgIIABgAIswBCskBA8QAAAAxUzMxMzczNDM2MzQzOTM1MzgzNTM3MzYzMDMyMzczNDM1M2E2OTZkNmQ2OTZkNjE2NzY1M2E3MzY1NzQzMDMwMzEzYTMxMzYzMzM1NjIzOTMzMzI2MTYyMzQzNzY2NjMzNjY2NjI2MTYxMzMzMjM1MzQzOTMzMzQzNzMwMzI2NTMxNjE2MjM3MzczMTY0NjM2NDM2MzgzNjM4NjQzMjM2MzEzNzM2MzYzNjM4NjUzNTYyMzc2NjM0MzU2MjYxNjE2NTMx",
  "SetId": "set001"
}

错误码

访问错误中心查看更多错误码。