通過輸入自然語言，對數據集內的元數據進行基于語義的查詢搜索。
接口說明
注意事項
-
請確保在使用該接口前，已充分了解智能媒體管理產品的收費方式和價格。該接口每次請求，會產生語義理解費用和查詢費用兩種計費項各一次。
-
調用該接口前，請確保您已通過綁定方式（ CreateBinding ）或者主動索引（ IndexFileMeta 或者 BatchIndexFileMeta ）方式將文件索引到數據集（Dataset）中。
-
返回結果僅為示例，根據工作流模板配置不同，獲取到的文件元數據信息的類別和包含的內容均有可能與示例不同。如果有疑問，請使用釘釘搜索釘釘群號 21714099 加入釘釘群進行反饋。
使用限制
-
每次查詢最多返回 1000 個文件信息。
-
不支持翻頁查詢。
-
自然語言理解不保證完全準確。
使用方式
使用自然語言關鍵詞對數據集內的文件進行搜索查詢。目前支持理解的關鍵信息包括標簽（Labels.LabelName）、時間（ProduceTime）和地點（Address.AddressLine）等。例如，以2023 年杭州的風景為條件進行查詢，會被智能拆分為如下三個條件，并查找出同時滿足這些條件的文件：
-
ProduceTime：2023 年 1 月 1 日零點起到 2023 年 12 月 31 日結束止
-
Address.AddressLine：包含
杭州關鍵詞 -
Labels.LabelName：包含
風景標簽
配合工作流模板配置，當模板中包含ImageEmbeddingExtraction算子時，該搜索請求會提供基于圖片內容的搜索，即您輸入的Query內容會同時被理解為圖片內包含的內容，從而實現對圖片的智能檢索。
調試
您可以在OpenAPI Explorer中直接運行該接口，免去您計算簽名的困擾。運行成功后，OpenAPI Explorer可以自動生成SDK代碼示例。
授權信息
下表是API對應的授權信息，可以在RAM權限策略語句的Action元素中使用，用來給RAM用戶或RAM角色授予調用此API的權限。具體說明如下：
- 操作：是指具體的權限點。
- 訪問級別：是指每個操作的訪問級別，取值為寫入（Write）、讀取（Read）或列出（List）。
- 資源類型：是指操作中支持授權的資源類型。具體說明如下：
- 對于必選的資源類型，用背景高亮的方式表示。
- 對于不支持資源級授權的操作，用
全部資源表示。
- 條件關鍵字：是指云產品自身定義的條件關鍵字。
- 關聯操作：是指成功執行操作所需要的其他權限。操作者必須同時具備關聯操作的權限，操作才能成功。
| 操作 | 訪問級別 | 資源類型 | 條件關鍵字 | 關聯操作 |
|---|---|---|---|---|
| imm:SemanticQuery | list |
|
| 無 |
請求參數
| 名稱 | 類型 | 必填 | 描述 | 示例值 |
|---|---|---|---|---|
| NextToken | string | 否 | 目前不再提供該參數。 | |
| MaxResults | integer | 否 | 本次讀取的最大數據記錄數量。范圍(0,1000]。 | 20 |
| ProjectName | string | 是 | 項目名稱。 | test-project |
| DatasetName | string | 是 | 數據集名稱。 | test-dataset |
| Query | string | 是 | 需要進行語義搜索的內容。 | 2021年4月杭州的風景 |
| WithFields | array | 否 | 僅返回特定字段的值，而不是全部已有的元信息字段。可用于降低返回的結構體大小。 不填或留空則返回所有字段。 | |
| string | 否 | 僅返回特定字段的值，而不是全部已有的元信息字段。可用于降低返回的結構體大小。 不填或留空則返回所有字段。 | ["URI", "Filename"] | |
| MediaTypes | array | 否 | 搜索的媒體類型。如留空則默認值為： ["image"] | |
| string | 否 | 枚舉值，當前僅支持： image | ["image"] |
返回參數
示例
正常返回示例
JSON格式
{
"RequestId": "2C5C1E0F-D8B8-4DA0-8127-EC32C771****",
"Files": [
{
"OwnerId": "102321002467****",
"ProjectName": "test-project",
"DatasetName": "test-dataset",
"ObjectType": "file",
"ObjectId": "75d5de2c50754e3dadd5c35dbca5f9949369e37eb342a73821f690c94c36c7f7",
"UpdateTime": "2021-06-29T14:50:13.011643661+08:00",
"CreateTime": "2021-06-29T14:50:13.011643661+08:00",
"URI": "oss://test-bucket/test-object.jpg",
"OSSURI": "oss://examplebucket/sampleobject.jpg",
"Filename": "sampleobject.jpg",
"MediaType": "image",
"ContentType": "image/jpeg",
"Size": 1000,
"FileHash": "1d9c280a7c4f67f7ef873e28449dbe17",
"FileModifiedTime": "2021-06-29T14:50:13.011643661+08:00",
"FileCreateTime": "2021-06-29T14:50:13.011643661+08:00",
"FileAccessTime": "2021-06-29T14:50:13.011643661+08:00",
"ProduceTime": "2021-06-29T14:50:13.011643661+08:00",
"LatLong": "30.134390,120.074997",
"Timezone": "",
"Addresses": [
{
"Language": "zh-Hans",
"AddressLine": "中國浙江省杭州市余杭區文一西路969號",
"Country": "中國",
"Province": "浙江省",
"City": "杭州市",
"District": "余杭區",
"Township": "文一西路"
}
],
"TravelClusterId": "-",
"Orientation": 0,
"Figures": [
{
"FigureId": "868a9e74-cde5-4c7a-9013-28bb984****",
"FigureConfidence": 1,
"FigureClusterId": "Cluster-dbe72fec-b84c-4ab6-885b-3678e64****",
"FigureClusterConfidence": 1,
"FigureType": "face",
"Age": 29,
"AgeSD": 5,
"Gender": "female",
"GenderConfidence": 1,
"Emotion": "happiness",
"EmotionConfidence": 0.70784568786621,
"FaceQuality": 0.960875928401947,
"Boundary": {
"Width": 200,
"Height": 300,
"Left": 10,
"Top": 30,
"Polygon": [
{
"X": 10,
"Y": 10
}
]
},
"Mouth": "close",
"MouthConfidence": 1,
"Beard": "none",
"BeardConfidence": 1,
"Hat": "none",
"HatConfidence": 1,
"Mask": "none",
"MaskConfidence": 1,
"Glasses": "none",
"GlassesConfidence": 0.8,
"Sharpness": 0.7,
"Attractive": 0.96,
"HeadPose": {
"Pitch": 18.385589599609375,
"Roll": 4.204030513763428,
"Yaw": 2.4945924282073975
}
}
],
"FigureCount": 10,
"Labels": [
{
"Language": "zh-Hans",
"LabelName": "人物特寫",
"LabelLevel": 1,
"LabelConfidence": 1,
"ParentLabelName": "人物",
"CentricScore": 0.877
}
],
"Title": "test",
"ImageWidth": 270,
"ImageHeight": 500,
"EXIF": "{\"Compression\":{\"value\":\"6\"},\"DateTime\":{\"value\":\"2020:08:19 17:11:11\"}}",
"ImageScore": {
"OverallQualityScore": 0.736
},
"CroppingSuggestions": [
{
"AspectRatio": "2:3",
"Confidence": 0.742,
"Boundary": {
"Width": 200,
"Height": 300,
"Left": 10,
"Top": 30,
"Polygon": [
{
"X": 10,
"Y": 10
}
]
}
}
],
"OCRContents": [
{
"Language": "zh-hans",
"Contents": "歡迎使用智能媒體管理",
"Confidence": 0.8254936695098877,
"Boundary": {
"Width": 200,
"Height": 300,
"Left": 10,
"Top": 30,
"Polygon": [
{
"X": 10,
"Y": 10
}
]
}
}
],
"VideoWidth": 1080,
"VideoHeight": 1920,
"VideoStreams": [
{
"Index": 0,
"Language": "en",
"CodecName": "h264",
"CodecLongName": "H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10",
"Profile": "High",
"CodecTimeBase": "1373627/83160000",
"CodecTagString": "avc1",
"CodecTag": "0x31637661",
"Width": 1280,
"Height": 720,
"HasBFrames": 2,
"SampleAspectRatio": "1:1",
"DisplayAspectRatio": "16:9",
"PixelFormat": "yuv420p",
"Level": 40,
"FrameRate": "25/1",
"AverageFrameRate": "25/1",
"TimeBase": "1/12800",
"StartTime": 0,
"Duration": 22.88,
"Bitrate": 5407765,
"FrameCount": 572,
"Rotate": "90",
"BitDepth": 8,
"ColorSpace": "bt709",
"ColorRange": "tv",
"ColorTransfer": "bt709",
"ColorPrimaries": "bt709"
}
],
"Subtitles": [
{
"Index": 2,
"Language": "en",
"CodecName": "mov_text",
"CodecLongName": "MOV text",
"CodecTagString": "tx3g",
"CodecTag": "0x67337874",
"StartTime": 0,
"Duration": 71.378,
"Bitrate": 74,
"Content": "歡迎",
"Width": 600,
"Height": 30
}
],
"AudioStreams": [
{
"Index": 1,
"Language": "en",
"CodecName": "aac",
"CodecLongName": "AAC (Advanced Audio Coding)",
"CodecTimeBase": "1/44100",
"CodecTagString": "mp4a",
"CodecTag": "0x6134706d",
"TimeBase": "1/48000",
"StartTime": 0.0235,
"Duration": 3.690667,
"Bitrate": 320087,
"FrameCount": 173,
"Lyric": "test",
"SampleFormat": "fltp",
"SampleRate": 48000,
"Channels": 2,
"ChannelLayout": "stereo"
}
],
"Artist": "Jane",
"AlbumArtist": "Jane",
"AudioCovers": [
{
"ImageWidth": 500,
"ImageHeight": 820,
"EXIF": "{\"FileSize\":{\"value\":\"29304\"},\"Format\":{\"value\":\"jpg\"}}",
"ImageScore": {
"OverallQualityScore": 0.736
},
"CroppingSuggestions": [
{
"AspectRatio": "2:3",
"Confidence": 0.742
}
],
"OCRContents": [
{
"Language": "zh-hans",
"Contents": "歡迎使用智能媒體管理",
"Confidence": 0.8254936695098877
}
]
}
],
"Composer": "Jane",
"Performer": "Jane",
"Language": "eng",
"Album": "FirstAlbum",
"PageCount": 5,
"ETag": "\"1D9C280A7C4F67F7EF873E28449****\"",
"CacheControl": "no-cache",
"ContentDisposition": "attachment; filename =test.jpg",
"ContentEncoding": "UTF-8",
"ContentLanguage": "zh-CN",
"AccessControlAllowOrigin": "https://aliyundoc.com",
"AccessControlRequestMethod": "PUT",
"ServerSideEncryptionCustomerAlgorithm": "SM4",
"ServerSideEncryption": "AES256",
"ServerSideDataEncryption": "SM4",
"ServerSideEncryptionKeyId": "9468da86-3509-4f8d-a61e-6eab1eac****",
"OSSStorageClass": "Standard",
"OSSCRC64": "559890638950338001",
"ObjectACL": "default",
"ContentMd5": "HZwoCnxPZ/fvhz4oRJ2+Fw==",
"OSSUserMeta": {
"key": "val"
},
"OSSTaggingCount": 2,
"OSSTagging": {
"key": "val"
},
"OSSExpiration": "2120-01-01T12:00:00.000Z",
"OSSVersionId": "CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****",
"OSSDeleteMarker": "CAEQMhiBgIDXiaaB0BYiIGQzYmRkZGUxMTM1ZDRjOTZhNjk4YjRjMTAyZjhl****",
"OSSObjectType": "Normal",
"CustomId": "\t\nmember-image-id-0001",
"CustomLabels": {
"MemberName": "Tim",
"Enabled": "True",
"ItemCount": "10"
},
"StreamCount": 1,
"ProgramCount": 1,
"FormatName": "mov",
"FormatLongName": "QuickTime / MOV",
"StartTime": 0,
"Bitrate": 13091201,
"Duration": 15.263,
"SemanticSimilarity": 0.855123,
"SemanticTypes": [
"content"
],
"Elements": [
{
"ElementContents": [
{
"Type": "text",
"Content": "文本片段",
"URL": "http://aliyun.com",
"TimeRange": [
0
]
}
],
"ObjectId": "",
"ElementType": "",
"SemanticSimilarity": 0,
"ElementRelations": [
{
"Type": "",
"ObjectId": ""
}
]
}
],
"SceneElements": [
{
"TimeRange": [
0
],
"FrameTimes": [
0
]
}
],
"OCRTexts": "阿里云IMM",
"FileStatus": "",
"Reason": "[InternalError] The request has been failed due to some unknown error. status: 500, requestId: CC5ACFBD-BB7A-496D-A9D6-****",
"SmartClusters": [
{
"SmartClusterId": "",
"Similarity": 0
}
],
"ObjectStatus": "Indexed",
"SequenceNumber": 3,
"ClusterStatus": {
"key": {
"key": [
""
]
}
},
"ClusterModifications": {
"key": {
"key": [
""
]
}
}
}
]
}錯誤碼
訪問錯誤中心查看更多錯誤碼。
變更歷史
| 變更時間 | 變更內容概要 | 操作 |
|---|---|---|
| 2024-09-05 | OpenAPI 入參發生變更 | 查看變更詳情 |
| 2024-09-04 | OpenAPI 入參發生變更 | 查看變更詳情 |
| 2023-11-20 | OpenAPI 入參發生變更、OpenAPI 返回結構發生變更 | 查看變更詳情 |
| 2023-09-04 | OpenAPI 返回結構發生變更 | 查看變更詳情 |