tencent cloud

Cloud Infinite

DokumentasiCloud InfiniteAPI DocumentationIntelligent Search MetaInsightMultimodal SearchHybrid Search - Image Search

Hybrid Search - Image Search

Unduh
Mode fokus
Ukuran font
Terakhir diperbarui: 2026-09-08 16:24:29
Diterjemahkan oleh AI

API Description

This API searches for images within a dataset. Based on the DatasetHybridSearch API, it supports two search methods: search by image and search by text.
Search by image: Enter an image, and the system retrieves images with similar content to the input image.
Search by text: Enter natural language text, and the system retrieves images that match the semantics of the input text. For example, if you enter a search query containing a person's name, the system retrieves images related to that person from the dataset.
Hybrid search - image search supports scalar filtering. For supported fields and operators, see Scalar Filtering Field and Operator Support List.

Authorization Description

When using a sub-account, add the ci:DatasetHybridSearch permission to the action of the authorization policy. For all operation APIs supported by Cloud Infinite, see CI action.

Service Activation

When you use this feature for the first time, Cloud Infinite is activated for you by default, and the bucket is automatically bound to Cloud Infinite. You can use it directly without role authorization.
Note:
After Cloud Infinite is bound, if you manually unbind Cloud Infinite from the bucket, you will no longer be able to use this feature.
To use name information for image search, you need to enable the allowlist. Please contact us.

Use Limits

Before using search, complete creating a dataset first.
Only the Jakarta region is supported. In the request Host, Region can only be set to ap-jakarta.
For more usage limitations, see Usage Limits.

Fee Instructions

For fees related to hybrid search - image search, see Intelligent Search Fees.

Request

Request sample

POST /datasetquery/hybridsearch HTTP/1.1
Host: <AppId>.ci.ap-jakarta.myqcloud.com
Authorization: Auth String
Content-Length: xxx
Content-Type: application/json
Accept: application/json
Note:
Authorization: Auth String. For details, see Request Signature.

Request header

This API only uses common request headers. For details, see Common Request Headers.

Request body

Request body example 1: Search by image with scalar filtering
{
	"DatasetName": "imagesearch",
	"Mode": "pic",
	"Templates": "ImageSearch",
	"SearchURIs": ["cos://examplebucket-1250000000/test.jpg"],
	"Limit": 10,
	"MatchThreshold": 1,
	"Filter": {
		"$and": [{
				"MediaType": {
					"$in": ["image"]
				}
			},
			{
				"Size": {
					"$gt": 123
				}
			}
		]
	}
}
Request body example 2: Search by text with scalar filtering
{
	"DatasetName": "imagesearch",
	"Mode": "text",
	"Templates" : "ImageSearch",
	"SearchText": "an image containing a large tree",
	"Limit": 10,
	"MatchThreshold": 1,
	"Filter": {
		"$and": [{
				"MediaType": {
					"$in": ["image"]
				}
			},
			{
				"Size": {
					"$gt": 123
				}
			}
		]
	}
}

Request Parameters

Parameter Name
Description
Type
Required
DatasetName
Dataset name, unique within the same account
String
Yes
Mode
Specifies the input type for search. Default value: pic. Valid values:
pic: Indicates an image search by inputting an image
text: Indicates a text-based image search. It supports natural language input, such as "an image containing a large tree", and also supports entering a celebrity's name to search for related images
String
No
Templates
Specifies the data type of the output. Valid values:
ImageSearch: Performs image search and returns image results. It supports two modes: pic and text
FullImageSearch: Performs a full image search and returns image results. Mode must be set to text
String
Yes
SearchURIs
Resource identifier field. Currently, only COS Buckets are supported. Field rule: cos://<BucketName>/<Path>, where BucketName indicates the COS Bucket name and Path indicates the resource path. Example: cos://examplebucket-1250000000/test.jpg
String Array
No. Required when Mode is pic.
SearchText
Search statement. Supports up to 60 UTF-8 encoded characters. For example, "an image containing a large tree" or the name of a celebrity
String
No. Required when Mode is text.
Limit
Number of related images to return. Default value: 10. Value range: (0, 100]
Integer
No
MatchThreshold
Limits the minimum relevance score for returned images. Only images with a relevance score greater than or equal to the MatchThreshold value are returned. Default value: 0. Value range: (0, 100]
For example, if MatchThreshold is set to 80, only images with a relevance score greater than or equal to 80 are returned in the search results
Integer
No
Filter
Simple query parameter conditions. This optional parameter can contain three conditions. For the data format, see Scalar Filtering Fields and Operator Support List
Container
No

Response

Response Headers

This API only returns common response headers. For details, see Common Response Headers.

Response Body

Response body example: Results returned by image search and text search.
{
	"ImageResult": [{
		"URI": "cos://examplebucket-1250000000/test.jpg",
		"Score": 99
	}],
	"RequestId": "NjYwYzEwYjhfNGQ2ODk0MGJfMjcxxxx"
}
The specific data content of the response body is as follows:
Parameter Name
Type
Description
RequestId
String
Request ID
ImageResult
Container Array
List of image search and recognition result information
ImageResult node content:
Parameter Name
Type
Description
URI
String
Resource identifier field, indicating the COS address of the matched image
Score
Integer
Match score of the related image

Practical Case

Case 1: Search by Image

Use an image as input to search for images with similar content in the dataset. During an image search, if the dataset contains an image that is exactly the same as the input image, its match score can reach 100.
Request:
POST /datasetquery/hybridsearch HTTP/1.1
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1497530202;1497610202&q-key-time=1497530202;1497610202&q-header-list=&q-url-param-list=&q-signature=****************************************
Host: 1234567890.ci.ap-jakarta.myqcloud.com
Content-Length: 166
Content-Type: application/json
Accept: application/json

{
	"DatasetName": "imagesearch",
	"Mode": "pic",
	"Templates": "ImageSearch",
	"SearchURIs": ["cos://examplebucket-1250000000/query.jpg"],
	"Limit": 10,
	"MatchThreshold": 80
}
Response:
HTTP/1.1 200 OK
Content-Type: application/json
Server: tencent-ci
x-ci-request-id: NjMxMDJhYTNfMThhYTk0MGFfYmU1OV8zZjc=

{
	"ImageResult": [{
		"URI": "cos://examplebucket-1250000000/query.jpg",
		"Score": 100
	}],
	"RequestId": "NjYwYzEwYjhfNGQ2ODk0MGJfMjcxxxx"
}

Case 2: Search by Text (Natural Language Input)

Use natural language text as input to search for images in the dataset that match the semantics of the text. For example, if you enter "a front-facing photo of a man in a suit", multiple images with corresponding semantic features are returned and sorted in descending order by relevance score.
Request:
POST /datasetquery/hybridsearch HTTP/1.1
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1497530202;1497610202&q-key-time=1497530202;1497610202&q-header-list=&q-url-param-list=&q-signature=****************************************
Host: 1234567890.ci.ap-jakarta.myqcloud.com
Content-Type: application/json
Accept: application/json

{
	"DatasetName": "imagesearch",
	"Mode": "text",
	"Templates": "ImageSearch",
	"SearchText": "A front-facing photo of a man in a suit",
	"Limit": 10,
	"MatchThreshold": 50
}
Response:
HTTP/1.1 200 OK
Content-Type: application/json
Server: tencent-ci

{
	"ImageResult": [
		{ "URI": "cos://examplebucket-1250000000/image_01.webp", "Score": 59 },
		{ "URI": "cos://examplebucket-1250000000/image_02.webp", "Score": 58 },
		{ "URI": "cos://examplebucket-1250000000/image_03.webp", "Score": 58 },
		{ "URI": "cos://examplebucket-1250000000/image_04.webp", "Score": 57 },
		{ "URI": "cos://examplebucket-1250000000/image_05.webp", "Score": 56 }
	],
	"RequestId": "NmExZDJiMTBfMjYyOTVhMTVfMTYyYzk1XzIxN2E="
}

Case 3: Search by Text (Person Name Input)

Text-based image search supports directly entering a search query containing a person's name to retrieve images related to that person from the dataset.
Request:
{
	"DatasetName": "imagesearch",
	"Mode": "text",
	"Templates": "ImageSearch",
	"SearchText": "Zhang San",
	"Limit": 10,
	"MatchThreshold": 50
}
Response:
{
	"ImageResult": [
		{ "URI": "cos://examplebucket-1250000000/person_01.webp", "Score": 88 },
		{ "URI": "cos://examplebucket-1250000000/person_02.webp", "Score": 85 }
	],
	"RequestId": "NmExZDJiMGVfMjYyOTVhMTVfMTYyYzk1XzIxNzk="
}
Note:
The match score for image-to-image search (when an image matches itself) can reach 100, while the semantic match score for text-to-image search is usually lower. During initial debugging, you are advised to gradually adjust MatchThreshold from 30 to 40 to avoid a high default threshold filtering out all results.

Error Codes

This request operation has no special error messages. For common error messages, see Error Codes.

Topik sebelumnya: Scalar Search Expression SyntaxTopik selanjutnya: Supported Scalar Filter Fields and Operators

Bantuan dan Dukungan

Apakah halaman ini membantu?

masukan

Search
    Enter keywords to search documentation