tencent cloud

Cloud Infinite

DokumentasiCloud InfiniteAPI DocumentationIntelligent Search MetaInsightFace SearchFace comparison

Face comparison

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

Feature Description

You can use a face image to be detected to search a dataset for the top N most similar face images.

Authorization Description

When using a sub-account, add the ci:DatasetFaceSearch permission to the action of the authorization policy. For all 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.

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 face comparison, see Intelligent Search Fees.

Request

Request sample

POST /datasetquery/facesearch 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

{
    "DatasetName": "test",
    "URI": "cos://examplebucket-1250000000/test.jpg",
    "MaxFaceNum": 1,
    "Limit": 10,
    "MatchThreshold": 10
}

Request Parameters

Parameter Name
Description
Type
Required
DatasetName
Dataset name, unique within the same account. In this scenario, you can only select datasets bound to face search templates. You can query the name through the console or API
String
Yes
URI
Resource identifier field, indicating the file address for which an index needs to be created
String
Yes
MaxFaceNum
Number of faces to search for in the input image. Default value: 1 (if 0 is passed or no value is passed, the default value is used). Maximum value: 10
Integer
No
Limit
Number of related faces returned for each face in the search. Default value: 10. Maximum value: 100
Integer
No
MatchThreshold
Limits the minimum relevance score for returned faces. Only faces with a relevance score exceeding the MatchThreshold value are returned. Default value: 0. Recommended value: 80.
For example, if MatchThreshold is set to 80, only faces with a relevance score greater than or equal to 80 are returned in the search results
Integer
No

Response

Response Headers

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

Response Body

{
    "FaceResult": [{
        "FaceInfos": [{
            "PersonId": "xxxxx",
            "FaceBoundary": {
                "Height": 264,
                "Width": 203,
                "Left": 353,
                "Top": 90
            },
            "FaceId": "80c10056-1d40-418b-9f4f-dabf8e8cc349",
            "Score": 76,
            "URI": "cos://facesearch-1258726280/huge_hezao.webp"
        }],
        "InputFaceBoundary": {
            "Height": 545,
            "Width": 401,
            "Left": 737,
            "Top": 191
        }
    }],
    "RequestId": "NjYxNTMyY2JfNGQ2ODk0MGJfNzAzZl81"
}
The specific data content of the response body is as follows:
Parameter Name
Type
Description
FaceResult
Container Array
List of face search and recognition result information
RequestId
String
Request ID
FaceResult node content:
Parameter Name
Type
Description
FaceInfos
Container Array
List of related face information
InputFaceBoundary
Container
Position of the face bounding box in the input image
FaceInfos node content:
Parameter Name
Type
Description
PersonId
String
Custom character ID
FaceBoundary
Container
Position of the associated face bounding box
FaceId
String
Face ID
Score
Integer
Related face match score
URI
String
Resource identifier field, indicating the file address for which an index needs to be created
FaceBoundary node content:
Parameter Name
Type
Description
Height
Integer
Face height
Width
Integer
Face width
Left
Integer
Horizontal coordinate of the upper-left corner of the face bounding box
Top
Integer
Vertical coordinate of the upper-left corner of the face bounding box
InputFaceBoundary node content:
Parameter Name
Type
Description
Height
Integer
Face height
Width
Integer
Face width
Left
Integer
Horizontal coordinate of the upper-left corner of the face bounding box
Top
Integer
Vertical coordinate of the upper-left corner of the face bounding box

Use Cases

Request: Performing Face Search with Scalar Filtering

POST /datasetquery/facesearch 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": "test",
    "URI": "cos://examplebucket-1250000000/test.jpg",
    "MaxFaceNum": 1,
    "Limit": 10,
    "MatchThreshold": 10
}

Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 230
Connection: keep-alive
Date: Mon, 28 Jun 2022 15:23:12 GMT
Server: tencent-ci
x-ci-request-id: NjMxMDJhYTNfMThhYTk0MGFfYmU1OV8zZjc=

{
    "FaceResult": [{
        "FaceInfos": [{
            "PersonId": "xxxxx",
            "FaceBoundary": {
                "Height": 264,
                "Width": 203,
                "Left": 353,
                "Top": 90
            },
            "FaceId": "80c10056-1d40-418b-9f4f-dabf8e8cc349",
            "Score": 76,
            "URI": "cos://facesearch-1258726280/huge_hezao.webp"
        }],
        "InputFaceBoundary": {
            "Height": 545,
            "Width": 401,
            "Left": 737,
            "Top": 191
        }
    }],
    "RequestId": "NjYxNTMyY2JfNGQ2ODk0MGJfNzAzZl81"
}


Error Codes

This request operation has no special error messages. For common error messages, see Error Codes.
Topik sebelumnya: Supported Scalar Filter Fields and OperatorsTopik selanjutnya: Create a workflow

Bantuan dan Dukungan

Apakah halaman ini membantu?

masukan

Search
    Enter keywords to search documentation