api reference · 2020. 12. 14. · apis provided by frs comply with restful api design...

Face Recognition Service

API Reference

Issue 01

Date 2021-04-26

HUAWEI TECHNOLOGIES CO., LTD.

Copyright © Huawei Technologies Co., Ltd. 2021. All rights reserved.

No part of this document may be reproduced or transmitted in any form or by any means without priorwritten consent of Huawei Technologies Co., Ltd. Trademarks and Permissions

and other Huawei trademarks are trademarks of Huawei Technologies Co., Ltd.All other trademarks and trade names mentioned in this document are the property of their respectiveholders. NoticeThe purchased products, services and features are stipulated by the contract made between Huawei andthe customer. All or part of the products, services and features described in this document may not bewithin the purchase scope or the usage scope. Unless otherwise specified in the contract, all statements,information, and recommendations in this document are provided "AS IS" without warranties, guaranteesor representations of any kind, either express or implied.

The information in this document is subject to change without notice. Every effort has been made in thepreparation of this document to ensure accuracy of the contents, but all statements, information, andrecommendations in this document do not constitute a warranty of any kind, express or implied.

Issue 01 (2021-04-26) Copyright © Huawei Technologies Co., Ltd. i

Contents

1 Before You Start....................................................................................................................... 11.1 Overview.................................................................................................................................................................................... 11.2 API Calling..................................................................................................................................................................................11.3 Endpoints....................................................................................................................................................................................11.4 Restrictions and Limitations................................................................................................................................................ 21.5 Concepts..................................................................................................................................................................................... 3

2 API Overview............................................................................................................................ 5

3 Calling APIs............................................................................................................................... 73.1 Applying for FRS...................................................................................................................................................................... 73.2 Making an API Request......................................................................................................................................................... 83.3 Authentication....................................................................................................................................................................... 123.4 Response.................................................................................................................................................................................. 14

4 APIs........................................................................................................................................... 174.1 Service Status Query............................................................................................................................................................ 174.2 Face Detection....................................................................................................................................................................... 204.3 Face Verification.................................................................................................................................................................... 244.4 Face LiveDetect...................................................................................................................................................................... 294.5 Face Retrieval......................................................................................................................................................................... 364.6 Facial Image Library Management................................................................................................................................. 414.6.1 Facial Image Library Create........................................................................................................................................... 414.6.2 Query of All Facial Image Libraries............................................................................................................................. 454.6.3 Facial Image Library Query............................................................................................................................................ 474.6.4 Facial Image Library Delete........................................................................................................................................... 504.7 Facial Resource Management...........................................................................................................................................524.7.1 Face Add............................................................................................................................................................................... 524.7.2 Face Query........................................................................................................................................................................... 574.7.3 Face Update.........................................................................................................................................................................614.7.4 Face Delete.......................................................................................................................................................................... 644.7.5 Batch Face Delete..............................................................................................................................................................67

5 Public Data Structures......................................................................................................... 705.1 Common Message Headers ............................................................................................................................................. 705.2 Message Object Structures................................................................................................................................................ 72

Face Recognition ServiceAPI Reference Contents

Issue 01 (2021-04-26) Copyright © Huawei Technologies Co., Ltd. ii

5.2.1 AllParam............................................................................................................................................................................... 725.2.2 DetectFace........................................................................................................................................................................... 765.2.3 Landmark............................................................................................................................................................................. 775.2.4 FaceSetFace......................................................................................................................................................................... 775.2.5 SearchFace........................................................................................................................................................................... 785.2.6 FaceSetInfo.......................................................................................................................................................................... 795.2.7 BoundingBox....................................................................................................................................................................... 795.2.8 VideoDetectResult............................................................................................................................................................. 805.2.9 ServiceInfo............................................................................................................................................................................805.2.10 WarningList....................................................................................................................................................................... 815.3 Customized Fields................................................................................................................................................................. 825.4 Sort Syntax.............................................................................................................................................................................. 835.5 Filter Syntax............................................................................................................................................................................ 83

6 Appendix..................................................................................................................................856.1 Status Codes........................................................................................................................................................................... 856.2 Error Codes.............................................................................................................................................................................. 886.3 Obtaining the Project ID, Account Name, and AK/SK.............................................................................................. 966.3.1 Obtaining the Project ID and Account Name..........................................................................................................966.3.2 Obtaining an Account ID................................................................................................................................................ 976.3.3 Obtaining an Access Key ID/Secret Access Key (AK/SK)......................................................................................98

Face Recognition ServiceAPI Reference Contents

Issue 01 (2021-04-26) Copyright © Huawei Technologies Co., Ltd. iii

1 Before You Start1.1 Overview

Face Recognition Service (FRS) quickly detects faces in images, analyzes key facialpoints, obtains face attributes, and implements face comparison and search.

FRS provides open Application Programming Interfaces (APIs) for users. You canuse these APIs as instructed by this document.

If you plan to access FRS through an API, ensure that you are familiar with FRSconcepts. For details, see the Service Overview.

1.2 API CallingFRS supports Representational State Transfer (REST) APIs, allowing you to callAPIs using HTTPS. For details about API calling, see Calling APIs.

1.3 EndpointsAn endpoint is the request address for calling an API. Endpoints vary dependingon services and regions. For the endpoints of all services, see Regions andEndpoints.

Table 1-1 lists Face Recognition endpoints. Select a desired one based on servicerequirements.

Table 1-1 FRS endpoints

Region EndpointRegion

Endpoint Protocol

DeployedService

AP-HongKong

ap-southeast-1

face.ap-southeast-1.myhuaweicloud.com

HTTPS FRS APIs

Face Recognition ServiceAPI Reference 1 Before You Start

Issue 01 (2021-04-26) Copyright © Huawei Technologies Co., Ltd. 1

https://developer.huaweicloud.com/intl/en-us/endpoint?FRShttps://developer.huaweicloud.com/intl/en-us/endpoint?FRS

Region EndpointRegion

Endpoint Protocol

DeployedService

AP-Bangkok

ap-southeast-2

face.ap-southeast-2.myhuaweicloud.com

HTTPS FRS APIs

1.4 Restrictions and LimitationsDue to various factors such as technology and cost, FRS has some restrictions. Thesystem-wide restrictions affect all sub-services. In addition to system-widerestrictions, sub-services have their independent restrictions.

System-Wide Restrictions● Only images in JPG, PNG, JPEG, or BMP format can be recognized.● Each user can use 10 facial image libraries free of charge. Each library

contains a maximum of 100,000 facial features. To expand the capacity of asingle facial image library, contact HUAWEI CLOUD customer service toconfirm the expansion scale and price.

● Use standard JSON format in the body of the application/json request.● Do not use carriage return characters in Base64 code.● The system does not save images or videos of users.

Face Detection/Verification/Retrieval● The total size of the two images input for face verification is less than 8 MB.● The image size must be less than 8 MB. If the image size is too large, the

image transmission will take a long time. It is recommended that the imagesize be less than 1 MB.

● The image resolution must be less than 4,096 x 2,160. The face resolution inan image must be greater than 80 x 80. It is recommended that the faceresolution be greater than 120 x 120.

● To ensure the recognition effect, facial images need to meet the followingrequirements:

a. The illumination should be greater than 200 lux and there is no lightreflection or shadow caused by strong light.

b. The overall image is clear without obvious motion blur and the face in itis not blocked.

c. The side face angle does not exceed 30°, and the tilt angle and horizontalangle do not exceed 15°. The face in an image must be a vertically placedfront face.

Face LiveDetect● Currently, only video files and Base64-encoded videos can be detected. User

clients need to obtain the video streams, save them as files, and then call theLiveDetect API.



● The size of a video file cannot exceed 8 MB. It is recommended that the videofile be compressed to 200 KB to 2 MB on the client.

● The video duration must be 1 to 15 seconds.● The recommended frame rate is 10 fps to 30 fps.● The encapsulation format can be MP4, AVI, FLV, WEBM, ASF, or MOV.● The video encoding format can be H.261, H.263, H.264, HEVC, VC-1, VP8, VP9,

or WMV3.

1.5 Concepts● Account

An account is created upon successful registration with HUAWEI CLOUD. Theaccount has full access permissions for all of its cloud services and resources.It can be used to reset user passwords and grant user permissions. Theaccount is a payment entity. For security purposes, do not directly use theaccount to perform routine management but create IAM users and grantthem permissions for routine management.

● UserA user is created in IAM using an account to use cloud services. Each user hasits own identity credentials (password and access keys).An IAM user can view the account ID and user ID on the My Credentialspage of the console. The account name, username, and password will berequired for API authentication.

● RegionRegions are divided based on geographical location and network latency.Public services, such as Elastic Cloud Server (ECS), Elastic Volume Service(EVS), Object Storage Service (OBS), Virtual Private Cloud (VPC), Elastic IP(EIP), and Image Management Service (IMS), are shared within the sameregion. Regions are classified into universal regions and dedicated regions. Auniversal region provides universal cloud services for common tenants. Adedicated region provides specific services for specific tenants.

● Availability Zone (AZ)An AZ contains one or more physical data centers. Each AZ has independentcooling, fire extinguishing, moisture-proof, and electricity facilities. Within anAZ, computing, network, storage, and other resources are logically dividedinto multiple clusters. AZs within a region are interconnected using high-speed optical fibers to support cross-AZ high-availability systems.

● ProjectProjects group and isolate resources (including compute, storage, and networkresources) across physical regions. A default project is provided for eachHUAWEI CLOUD region, and subprojects can be created under each defaultproject. Users can be granted permissions to access all resources in a specificproject. For more refined access control, create subprojects under a projectand purchase resources in the subprojects. Users can then be assignedpermissions to access only specific resources in the subprojects.



https://console-intl.huaweicloud.com/iam/?locale=en-us#/myCredential

Figure 1-1 Project isolating model



2 API OverviewAPIs provided by FRS comply with RESTful API design specifications. Table 2-1 liststhe APIs.

Table 2-1 FRS APIs

Type API Description

Face Detection Face Detection This API is used to detect, locate, andanalyze the face in an input image,and output the key facial points andattributes.

Face Verification Face Verification This API is used to compare two facesto verify whether they belong to thesame person and return theconfidence level. If each input imagecontains multiple faces, the API selectsthe largest face for comparison.

Face LiveDetect Face LiveDetect This API is used to determine whethera person in a video is alive by checkingwhether the person's actions in thevideo are consistent with those in theinput action list. If multiple facesappear, the largest face is selected.

Face Retrieval Face Retrieval This API is used to search an existingfacial image library for one or morefaces similar to the input face, andreturn corresponding confidence levels.

Face Recognition ServiceAPI Reference 2 API Overview


Type API Description

Facial ImageLibraryManagement

Facial ImageLibrary Create

This API is used to create a facialimage library for storing facialfeatures. You can create a maximum of10 facial image libraries. Each librarycan contain a maximum of 100,000facial features. If you need higherspecifications, contact customerservice.

Query of AllFacial ImageLibraries

This API is used to query the statusesof all facial image libraries of thecurrent user.

Facial ImageLibrary Query

This API is used to query the status ofa facial image library.

Facial ImageLibrary Delete

This API is used to delete a facialimage library and all faces in thelibrary.

Facial ResourceManagement

Face Add This API is used to add faces to a facialimage library. All detected faces in theinput facial image will be added to thelibrary.

Face Query This API is used to query the faceinformation in a specified facial imagelibrary.

Face Update This API is used to update a single facebased on its face ID (face_id).

Face Delete This API is used to delete a face from afacial image library based on aspecified field.

Batch FaceDelete

This API is used to batch deletemultiple faces that meet specifiedcriteria you customize.

Face Recognition ServiceAPI Reference 2 API Overview


3 Calling APIs3.1 Applying for FRS

Before using the APIs, you must apply for FRS as follows:

NO TE

Before applying for FRS, register with HUAWEI CLOUD and complete real-nameauthentication.

Procedure1. Log in to the FRS management console on HUAWEI CLOUD.2. Select the sub-service to be enabled based on service requirements, for

example, Face Detection, and click Enable Service on the right.3. In the left navigation pane, choose Authorization, and click Agree. Figure

3-1 shows the page. When authorization is complete, the Agree buttonchanges to Authorized.

NO TE

● You also need to authorize FRS to access data stored on the Object Storage Service(OBS) to ensure highest performance.

● During OBS authorization, if the system shows that the number of agenciesreaches the upper limit, log in to the Identity and Access Management serviceconsole to delete or create agencies.

● When the service status is Enabled, you can call the APIs.

Figure 3-1 Service authorization

Face Recognition ServiceAPI Reference 3 Calling APIs


https://console-intl.huaweicloud.com/frs/?locale=en-ushttps://console-intl.huaweicloud.com/iam/?locale=en-us

3.2 Making an API RequestThis section describes the structure of a REST API request, and uses the IAM APIfor obtaining a user token as an example to demonstrate how to call an API. Theobtained token can then be used to authenticate the calling of other APIs.

Request URIA request URI is in the following format:

{URI-scheme} :// {Endpoint} / {resource-path} ? {query-string}

Table 3-1 Request URI

Parameter Description

URI-scheme Protocol used to transmit requests. All APIs use HTTPS.

Endpoint Domain name or IP address of the server bearing the RESTservice. The endpoint varies between services in differentregions. It can be obtained from Endpoints.For example, the endpoint of IAM in the AP-Hong Kong regionis iam.ap-southeast-1.myhuaweicloud.com.

resource-path

Access path of an API for performing a specified operation. Youcan obtain the value of this parameter from the URI of thespecific API.For example, the resource-path of the API used to obtain a usertoken is /v3/auth/tokens.

query-string Query parameter, which is optional. Ensure that a question mark(?) is included before each query parameter that is in the formatof "Parameter name=Parameter value". For example, ? limit=10indicates that a maximum of 10 data records will be displayed.

For example, to obtain an IAM token in the AP-Hong Kong region, obtain theendpoint of IAM (iam.ap-southeast-1.myhuaweicloud.com) for this region andthe resource-path (/v3/auth/tokens) in the URI of the API used to obtain a usertoken. Then, construct the URI as follows:

https://iam.ap-southeast-1.myhuaweicloud.com/v3/auth/tokens

Figure 3-2 Example URI



https://support.huaweicloud.com/intl/en-us/api-iam/iam_30_0001.htmlhttps://support.huaweicloud.com/intl/en-us/api-iam/iam_30_0001.htmlhttps://support.huaweicloud.com/intl/en-us/api-iam/iam_30_0001.html

NO TE

To simplify the URI display in this document, each API is provided only with a resource-path and a request method. The URI-scheme of all APIs is HTTPS, and the endpoints of allAPIs in the same region are identical.

Request Method

The HTTP protocol defines the following request methods that can be used tosend a request to the server:

Table 3-2 HTTP methods

Method Description

GET Requests the server to return specified resources.

PUT Requests the server to update specified resources.

POST Requests the server to add resources or perform specialoperations.

DELETE Requests the server to delete specified resources, forexample, an object.

HEAD Same as GET except that the server must return onlythe response header.

PATCH Requests the server to update partial content of aspecified resource.If the resource does not exist, a new resource will becreated.

For example, in the case of the API used to obtain a user token, the requestmethod is POST. The request is as follows:POST https://iam.ap-southeast-1.myhuaweicloud.com/v3/auth/tokens

Request Header

You can also add additional header fields to a request, such as the fields requiredby a specified URI or HTTP method. For example, to request for the authenticationinformation, add Content-Type, which specifies the request body type.

Table 3-3 describes common request header fields.

Table 3-3 Common request header fields

Parameter Description Mandatory Example Value

Content-type

Request body type orformat. Its default valueis application/json.

Yes application/json



https://support.huaweicloud.com/intl/en-us/api-iam/iam_30_0001.html


X-Project-Id Project ID, which is usedto obtain the token of aproject. For details abouthow to obtain theproject ID, tenant ID, AK,and SK, see Obtainingthe Project ID, AccountName, and AK/SK.

No e9993fc787d94b6c886cbaa340f9c0f4

X-Auth-Token

User token, a responseto the API used toobtain a user token.This API is the only onethat does not requireauthentication.

Thisparameter ismandatoryfor tokenauthentication.

-

X-Sdk-Date Time when the requestis sent. The time is inYYYYMMDD'T'HHMMSS'Z' format.The value is the currentGreenwich Mean Time(GMT) of the system.

Thisparameter ismandatoryfor AK/SK-basedauthentication, but notrequired forPKI token-basedauthentication

20190307T101459Z

Authorization

Signature authenticationinformation.The value is obtainedfrom the requestsignature result and isrequired when the AKand SK are used toencrypt the signature.Type: stringDefault value: none

Thisparameter ismandatoryfor AK/SK-basedauthentication.

SDK-HMAC-SHA256Credential=ZIRRKMTWPTQFQI1WKNKB/20150907//ec2/sdk_request,SignedHeaders=content-type;host;x-sdk-date,Signature=55741b610f3c9fa3ae40b5a8021ebf7ebc2a28a603fc62d25cb3bfe6608e1994



https://support.huaweicloud.com/intl/en-us/api-iam/iam_30_0001.html


Host Information about therequested server. Thevalue can be obtainedfrom the URL of theservice API.The value ishostname[:port].If the port number is notspecified, the defaultport is used. The defaultport number for https is443.

Thisparameter ismandatoryfor AK/SK-basedauthentication.

code.test.comorcode.test.com:443

NO TE

In addition to supporting token-based authentication, public cloud APIs also supportauthentication using access key ID/secret access key (AK/SK). During AK/SK-basedauthentication, an SDK is used to sign the request, and the Authorization (signatureinformation) and X-Sdk-Date (time when the request is sent) header fields areautomatically added to the request. For more details, see API Request Signing Guide.

For example, the API used to obtain a user token does not require authentication.Therefore, only the Content-Type field needs to be added to requests for callingthe API. An example of such requests is as follows:

POST https://iam.ap-southeast-1.myhuaweicloud.com/v3/auth/tokensContent-Type: application/json

Request BodyThe body of a request is often sent in a structured format as specified in theContent-Type header field. The request body transfers content except the requestheader. If the request body contains Chinese characters, these characters must becoded in UTF-8.

The request body varies between APIs. Some APIs do not require the request body,such as the APIs requested using the GET and DELETE methods.

In the case of the API used to obtain a user token, the request parameters andparameter description can be obtained from the API request. The followingprovides an example request with a body included. Replace username,domainname, ******** (login password), and xxxxxxxx (project name) with theactual values and obtain the token specified for the project. For example, if theproject name is set to ap-southeast-1, the obtained token applies to the services inap-southeast-1. For details about how to obtain a username, domainname, andproject name, see Obtaining Account, IAM User, Group, Project, Region, andAgency Information.



https://support.huaweicloud.com/intl/en-us/devg-apisign/api-sign-provide.htmlhttps://support.huaweicloud.com/intl/en-us/api-iam/iam_30_0001.htmlhttps://support.huaweicloud.com/intl/en-us/api-iam/iam_30_0001.htmlhttps://support.huaweicloud.com/intl/en-us/api-iam/iam_17_0002.htmlhttps://support.huaweicloud.com/intl/en-us/api-iam/iam_17_0002.html

NO TE

● The scope parameter specifies where a token takes effect. Its value can be project ordomain. In the preceding example, the value of scope is project, indicating that theobtained token can access only resources of the specified project. If the value of scope isdomainname, the obtained token can access all resources of the specified account. Fordetails, see Obtaining a User Token.

● project name: On the My Credentials page, the value in the Project column is theproject name. For details about how to obtain the project name, see ObtainingAccount, IAM User, Group, Project, Region, and Agency Information.

POST https://iam.ap-southeast-1.myhuaweicloud.com/v3/auth/tokensContent-Type: application/json{ "auth": { "identity": { "methods": ["password"], "password": { "user": { "name": "username", "password": "**********", "domain": { "name": "domainname" } } } }, "scope": { "project": { "name": "ap-southeast-1" } } }}

If all data required for the API request is available, you can send the request to callthe API through curl, Postman, or coding. If you choose to use Postman, version7.24.0 is recommended. In the response to the API used to obtain a user token, x-subject-token is the desired user token. This token can then be used toauthenticate the calling of other APIs.

3.3 AuthenticationRequests for calling an API can be authenticated using either of the followingmethods:

● Token-based authentication: Requests are authenticated using a token.● AK/SK-based authentication: Requests are authenticated by encrypting the

request body using an AK/SK pair.

Token-based AuthenticationNO TE

The validity period of a token is 24 hours. When using a token for authentication, cache itto prevent frequently calling the IAM API used to obtain a user token.

A token specifies temporary permissions in a computer system. During APIauthentication using a token, the token is added to requests to get permissions forcalling the API.



https://support.huaweicloud.com/intl/en-us/api-iam/iam_30_0001.htmlhttps://support.huaweicloud.com/intl/en-us/api-iam/iam_17_0002.htmlhttps://support.huaweicloud.com/intl/en-us/api-iam/iam_17_0002.htmlhttps://support.huaweicloud.com/intl/en-us/api-iam/iam_30_0001.html

When calling the API to obtain a user, you must set auth.scope in the requestbody to project.

{ "auth": { "identity": { "methods": [ "password" ], "password": { "user": { "name": "username", "password": "********", "domain": { "name": "domainname" } } } }, "scope": { "project": { "name": "xxxxxxxx" } } } }

In Making an API Request, the process of calling the API used to obtain a usertoken is described. After a token is obtained, the X-Auth-Token header field mustbe added to requests to specify the token when calling other APIs. For example, ifthe token is ABCDEFJ...., X-Auth-Token: ABCDEFJ.... can be added to a request asfollows:

GET https://iam.ap-southeast-1.myhuaweicloud.com/v3/auth/projectsContent-Type: application/json X-Auth-Token: ABCDEFJ....

AK/SK-based AuthenticationNO TE

AK/SK-based authentication supports API requests with a body not larger than 12 MB. ForAPI requests with a larger body, token-based authentication is recommended.

In AK/SK-based authentication, AK/SK is used to sign requests and the signature isthen added to the requests for authentication.

● AK: access key ID, which is a unique identifier used in conjunction with asecret access key to sign requests cryptographically.

● SK: secret access key used in conjunction with an AK to sign requestscryptographically. It identifies a request sender and prevents the request frombeing modified.

In AK/SK-based authentication, you can use an AK/SK to sign requests based onthe signature algorithm or use the signing SDK to sign requests. For details abouthow to sign requests and use the signing SDK, see API Request Signing Guide.



https://support.huaweicloud.com/intl/en-us/api-iam/iam_30_0001.htmlhttps://support.huaweicloud.com/intl/en-us/api-iam/iam_30_0001.htmlhttps://support.huaweicloud.com/intl/en-us/api-iam/iam_30_0001.htmlhttps://support.huaweicloud.com/intl/en-us/devg-apisign/api-sign-provide.html

NO TICE

The signing SDK is only used for signing requests and is different from the SDKsprovided by services.

For details about how to obtain the AK/SK, see Obtaining an AK/SK.

3.4 ResponseAfter sending a request, you will receive a response, including a status code,response header, and response body.

Status Code

A status code is a group of digits, ranging from 1xx to 5xx. It indicates the statusof a request. For more information, see Status Codes.

For example, if status code 201 is returned for the calling of the API used toobtain a user token, the request is successful.

Response Header

Similar to a request, a response also has a header, for example, Content-Type.

Table 3-4 Common response headers

Parameter Description Mandatory

Content-Type Media type of the message body sent to areceiverType: stringDefault value: application/json;charset=UTF-8

Yes

X-request-id This field carries the request ID for tasktracing.Type: string. request_id-timestamp-hostname (The request_id is the UUIDgenerated on the server. timestamp indicatesthe current timestamp, and hostname is thename of the server that processes the currentAPI.)Default value: none

No

X-ratelimit This field carries the total number of flowcontrol requests.Type: integerDefault value: none

No



https://support.huaweicloud.com/intl/en-us/devg-apisign/api-sign-provide.html#api-sign-provide__section5742192219435https://support.huaweicloud.com/intl/en-us/api-iam/iam_30_0001.html

Parameter Description Mandatory

X-ratelimit-used

This field carries the number of remainingrequests.Type: integerDefault value: none

No

X-ratelimit-window

This field carries the flow control unit.Type: string. The unit is minute, hour, or day.Default value: hour

No

Figure Header fields of the response to the request for obtaining a user tokenshows the response header fields for the API used to obtain a user token.

The x-subject-token header field is the desired user token. This token can then beused to authenticate the calling of other APIs.

Figure 3-3 Header fields of the response to the request for obtaining a user token

Response BodyThe body of a response is often returned in structured format as specified in theContent-Type header field. The response body transfers content except theresponse header.

The following is part of the response body for the API used to obtain a usertoken.

{ "token": { "expires_at": "2019-02-13T06:52:13.855000Z", "methods": [ "password" ], "catalog": [



https://support.huaweicloud.com/intl/en-us/api-iam/iam_30_0001.htmlhttps://support.huaweicloud.com/intl/en-us/api-iam/iam_30_0001.htmlhttps://support.huaweicloud.com/intl/en-us/api-iam/iam_30_0001.html

{ "endpoints": [ { "region_id": "ap-southeast-1",......

If an error occurs during API calling, an error code and a message will bedisplayed. The following shows an error response body.

{ "error_msg": "The format of message is error", "error_code": "AS.0001"}

In the response body, error_code is an error code, and error_msg providesinformation about the error. For details, see Error Codes.



4 APIs4.1 Service Status Query

FunctionThis API is used to query the service enabling status.

Prerequisites:

● Ensure that you have enabled FRS. For detailed operations, see Applying forFRS.

URIsubscribe

GET /v2/{project_id}/subscribe

Table 4-1 Path parameters

Parameter Mandatory Type Description

project_id Yes String Project ID. For details abouthow to obtain the ID, seeObtaining the Project ID,Account Name, and AK/SK.

Face Recognition ServiceAPI Reference 4 APIs


https://console-intl.huaweicloud.com/frs/?locale=en-us

Request Message

Table 4-2 Request header parameters


X-Auth-Token Yes String User token.During API authenticationusing a token, the token isadded to requests to obtainpermissions for calling the API.The value of X-Subject-Tokenin the response header is theobtained token.

Response Message

Status code: 200

Table 4-3 Response body parameters

Parameter Type Description

max_face_set_number Integer Maximum number of facialimage libraries.This parameter is not includedwhen the API fails to becalled.

detect_service Object Sub-service information. Fordetails about the ServiceInfostructure, see ServiceInfo.This parameter is not includedwhen the API fails to becalled.

compare_service Object Sub-service information. Fordetails about the ServiceInfostructure, see Table 4-4.This parameter is not includedwhen the API fails to becalled.

live_detect_service Object Sub-service information. Fordetails about the ServiceInfostructure, see Table 4-4.This parameter is not includedwhen the API fails to becalled.




search_service Object Sub-service information. Fordetails about the ServiceInfostructure, see Table 4-4.This parameter is not includedwhen the API fails to becalled.

error_code String Error code returned after theAPI fails to be called. Fordetails, see Error Codes.This parameter is not includedwhen the API is successfullycalled.

error_msg String Error message returned afterthe API fails to be called.This parameter is not includedwhen the API is successfullycalled.

Table 4-4 ServiceInfo


subscribe_status

Boolean Whether a sub-service is enabled

create_time String Time when a sub-service is enabled

Example RequestsFor details about how to obtain the value of X-Auth-Token, see Authentication.

● Sample codeGET https://{endpoint}/v2/{project_id}/subscribeRequest Header:Content-Type: application/jsonX-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...

Example ResponsesStatus code: 200

Example response (successful request){ "max_face_set_number": 10, "detect_service": { "subscribe_status": true, "create_time": "2018-09-03 08:16:48" }, "compare_service": {



"subscribe_status": true, "create_time": "2018-09-03 08:16:48" }, "search_service": { "subscribe_status": true, "create_time": "2018-09-03 08:16:48" }, "live_detect_service": { "subscribe_status": true, "create_time": "2018-09-03 08:16:48" }}

Status code: 400

Example response (failed request){ "error_code": "FRS.0019", "error_msg": "The service has not been subscribed."}

Status Code

For details about the status code, see Status Codes.

Error Code

For details about the error code, see Error Codes.

4.2 Face Detection

Function

This API is used to detect, locate, and analyze the face in an input image, andoutput the key facial points and attributes.

Prerequisites:


Restrictions:● Only images in JPG, PNG, JPEG, or BMP format can be recognized.● Use standard JSON format in the body of the application/json request.● Do not use carriage return characters in Base64 code.● The system does not save images of users.● The image size must be less than 8 MB. If the image is too large, the latency

is long and the image information volume is small. It is recommended thatthe image size be less than 1 MB.









● For details about other restrictions, see Restrictions and Limitations.

Suggestions:

● A larger image does not significantly improve the recognition algorithmprecision but will cause a long latency. Therefore, you are advised to uploadan image smaller than 1 MB. Generally, 500 KB is enough.

● It is recommended that the size of an image stored on OBS be less than 1MB.

● It is recommended that the face resolution in an image be greater than 120 x120.

URI

POST /v2/{project_id}/face-detect




Request Message






Table 4-7 Request body parameters


image_url Either image_url,image_file, orimage_base64 ismandatory.

String Image URL. Currently, onlythe URL of an OBS bucketon HUAWEI CLOUD issupported and FRS musthave the permission toread data in the OBSbucket. For details abouthow to enable the readpermission, see ServiceAuthorization.

image_file Either image_file,image_url, orimage_base64 ismandatory.

File Local image file, whosesize cannot exceed 8 MB.It is recommended thatthe image size be lessthan 1 MB. The requestformat is Multipart.

image_base64 Eitherimage_base64,image_file, orimage_url ismandatory.

String Image data (Base64-encoded). Its requirementsare as follows:● The image size after

Base64 encodingcannot exceed 8 MB. Itis recommended thatthe image size be lessthan 1 MB.

● The image is in JPG,JPEG, BMP, or PNGformat.

Response Message



faces List Detected face. For detailsabout the DetectFacestructure, seeDetectFace.This parameter is notincluded when the APIfails to be called.




error_code String Error code returned afterthe API fails to be called.For details, see ErrorCodes.This parameter is notincluded when the API issuccessfully called.

error_msg String Error message returnedafter the API fails to becalled.This parameter is notincluded when the API issuccessfully called.

Example Requests

For details about how to obtain the value of X-Auth-Token, see Authentication.

● Example request (Method 1: Use a Base64-encoded image.)POST https://{endpoint}/v2/{project_id}/face-detectRequest Header:Content-Type: application/jsonX-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...

Request Body:{ "image_base64": "/9j/4AAQSkZJRgABAgEASABIAAD" }

● Example request (Method 2: Use an image file.)POST https://{endpoint}/v2/{project_id}/face-detectRequest Header:X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...

Request Body: image_file: File (image file)

● Example request (Method 3: Use the image URL.)POST https://{endpoint}/v2/{project_id}/face-detectRequest Header:Content-Type: application/jsonX-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...

Request Body:{ "image_url": "/BucketName/ObjectName" }

Example Responses

Status code: 200

Response example (successful request)



{ "faces": [ { "bounding_box": { "width": 174, "top_left_y": 37, "top_left_x": 22, "height": 174 } } ]}

Status code: 400

Example response (failed request){ "error_code": "FRS.0019", "error_msg": "The service has not been subscribed."}

Status Code


Error Code


4.3 Face Verification

Function

This API is used to compare two faces to verify whether they belong to the sameperson and return the confidence level. If each input image contains multiplefaces, the API selects the largest face for comparison.

Prerequisites:


Restrictions:● The total size of the two images input for face verification is less than 8 MB.● Only images in JPG, PNG, JPEG, or BMP format can be recognized.● Use standard JSON format in the body of the application/json request.● Do not use carriage return characters in Base64 code.● The system does not save images of users.● The image size must be less than 8 MB. If the image is too large, the latency











Suggestions:● A larger image does not significantly improve the recognition algorithm

precision but will cause a long latency. Therefore, you are advised to uploadan image smaller than 1 MB. Generally, 500 KB is enough.



URI

POST /v2/{project_id}/face-compare




Request Message







Parameter Type Mandatory Description

image1_url String Eitherimage1_url,image1_file, orimage1_base64 ismandatory.

Image URL. Currently, onlythe URL of an OBS bucketon HUAWEI CLOUD issupported and FRS musthave the permission to readdata in the OBS bucket. Fordetails about how to enablethe read permission, seeService Authorization.

image1_file File Eitherimage1_file,image1_url, orimage1_base64 ismandatory.

Local image file, whose sizecannot exceed 8 MB. It isrecommended that theimage size be less than 1MB. The request format isMultipart.

image1_base64

String Eitherimage1_base64,image1_url, orimage1_file ismandatory.

Image data (Base64-encoded). Its requirementsare as follows:● The image size after

Base64 encoding cannotexceed 8 MB. It isrecommended that theimage size be less than 1MB.

● The image is in JPG, JPEG,BMP, or PNG format.

image2_url String Eitherimage2_url,image2_file, orimage2_base64 ismandatory.

Image URL. Currently, onlythe URL of an OBS bucketon HUAWEI CLOUD issupported and FRS musthave the permission to readdata in the OBS bucket. Fordetails about how to enablethe read permission, seeService Authorization.

image2_file File Eitherimage2_file,image2_url, orimage2_base64 ismandatory.

Local image file, whose sizecannot exceed 8 MB. It isrecommended that theimage size be less than 1MB. The request format isMultipart.




image2_base64

String Eitherimage2_base64,image2_url, orimage2_file ismandatory.

Image data (Base64-encoded). Its requirementsare as follows:● The image size after

Base64 encoding cannotexceed 8 MB. It isrecommended that theimage size be less than 1MB.


Response Message



image1_face Object Face detected in the first image. Fordetails about the DetectFace structure,see DetectFace.This parameter is not included when theAPI fails to be called.

image2_face Object Face detected in the second image. Fordetails about the DetectFace structure,see DetectFace.This parameter is not included when theAPI fails to be called.

similarity Double Face similarity. The value ranges from 0to 1. A larger value indicates a highersimilarity degree. Generally, if the value isgreater than 0.93, the faces in twoimages belong to one person.This parameter is not included when theAPI fails to be called.

error_code String Error code returned after the API fails tobe called. For details, see Error Codes.This parameter is not included when theAPI is successfully called.

error_msg String Error message returned after the API failsto be called.This parameter is not included when theAPI is successfully called.



Example Requests


● Example request (Method 1: Use a Base64-encoded image.)POST https://{endpoint}/v2/{project_id}/face-compareRequest Header:Content-Type: application/jsonX-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...

Request Body:{ "image1_base64":"/9j/4AAQSkZJRgABAgEASABIAAD...", "image2_base64":"/9j/4AAQSkZJRgABAgEASABIAAD..."}

● Example request (Method 2: Use an image file.)POST https://{endpoint}/v2/{project_id}/face-compareRequest Header:X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...

Request Body:image1_file: File (image file)image2_file: File (image file)

● Example request (Method 3: Use the image URL.)POST https://{endpoint}/v2/{project_id}/face-compareRequest Header:Content-Type: application/jsonX-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...

Request Body:{ "image1_url":"/BucketName/ObjectName", "image2_url":"/BucketName/ObjectName"}

Example Responses

Status code: 200

Response example (successful request){ "image1_face": { "bounding_box": { "width": 174, "top_left_y": 37, "top_left_x": 22, "height": 174 } }, "similarity": 0.4078676104545593, "image2_face": { "bounding_box": { "width": 118, "top_left_y": 28, "top_left_x": 94, "height": 118 } }}

Status code: 400

Example response (failed request){ "error_code": "FRS.0501",



"error_msg": "Detect no face, check out your picture."}

Status CodeFor details about the status code, see Status Codes.

Error CodeFor details about the error code, see Error Codes.

4.4 Face LiveDetect

FunctionThis API is used to determine whether a person in a video is alive by checkingwhether the person's actions in the video are consistent with those in the inputaction list. If multiple faces appear, the largest face is selected.

Prerequisites:


Restrictions:

● Currently, only video files and Base64-encoded videos can be detected. Userclients need to obtain the video streams, save them as files, and then call theLiveDetect API.

● The size of a video file cannot exceed 8 MB. It is recommended that thevideo file be compressed to 200 KB to 2 MB on the client.

● Use standard JSON format in the body of the application/json request.● Do not use carriage return characters in Base64 code.● The system does not save videos of users.● For details about other restrictions, see Restrictions and Limitations.

Suggestions:

● The recommended frame rate is 10 fps to 30 fps.● It is recommended that the video file be compressed to 200 KB to 2 MB on

the client.

URI

POST /v2/{project_id}/live-detec







Request Message








video_url Either video_url,video_file, orvideo_base64 ismandatory.

String Video URL. Currently, onlythe URL of an OBS bucketon HUAWEI CLOUD issupported and FRS musthave the permission toread data in the OBSbucket. For details abouthow to enable the readpermission, see ServiceAuthorization. The videorequirements are asfollows:● The video size after

Base64 encodingcannot exceed 8 MB.

● The video durationmust be 1 to 15seconds.

● The recommendedframe rate is 10 fps to30 fps.

● The encapsulationformat can be MP4,AVI, FLV, WEBM, ASF,or MOV.

● The video encodingformat can be H.261,H.263, H.264, HEVC,VC-1, VP8, VP9, orWMV3.




video_file Either video_file,video_url, orvideo_base64 ismandatory.

File Local video file. Therequest format isMultipart. The videorequirements are asfollows:● The size of a video file

cannot exceed 8 MB. Itis recommended thatthe video file becompressed to 200 KBto 2 MB on the client.








video_base64 Eithervideo_base64,video_url, orvideo_file ismandatory.

String Video data (Base64-encoded). Its requirementsare as follows:● The video size after

Base64 encodingcannot exceed 8 MB. Itis recommended thatthe video file becompressed to 200 KBto 2 MB on the client.





actions Yes String Action code sequence list.Actions are separated bycommas (,). Currently, thefollowing actions aresupported:● 1: Shake the head to

the left.● 2: Shake the head to

the right.● 3: Nod the head.● 4: Mouth movement




action_time No String String of the action timearray. The length of thearray is the same as thenumber of actions. Eachitem contains the starttime and end time of theaction in thecorresponding sequence.The unit is themilliseconds from thevideo start time.

Response Message

Status code: 200



video-result Object LiveDetect result. For detailsabout the VideoDetectResultstructure, seeVideoDetectResult.This parameter is notincluded when the API fails tobe called.

warning-list Object Warning information list. Fordetails about the WarningListstructure, see WarningList.This parameter is notincluded when the API fails tobe called.

error_code String Error code returned after theAPI fails to be called. Fordetails, see Error Codes.This parameter is notincluded when the API issuccessfully called.

error_msg String Error message returned afterthe API fails to be called.This parameter is notincluded when the API issuccessfully called.



Example Requests● Example request (Method 1: Use a Base64-encoded video.)

POST https://{endpoint}/v2/{project_id}/live-detect Request Header: Content-Type: application/json X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT... Request Body: { "video_base64":"/9j/4AAQSkZJRgABAgEASABIAAD", "actions":"1,3,2", "action_time":"1000-3000,4000-7000,9000-12000" }

● Example request (Method 2: Use a video file.)POST https://{endpoint}/v2/{project_id}/live-detect Request Header: X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT... Request Body: video_file: File (Video file) actions: 1,3,2 action_time: 1000-3000,4000-7000,9000-12000

● Example request (Method 3: Use the video URL.)POST https://{endpoint}/v2/{project_id}/live-detect Request Header: Content-Type: application/json X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT... Request Body: { "video_url":"/BucketName/ObjectName", "actions":"1,3,2", "action_time":"1000-3000,4000-7000,9000-12000" }url

Example Responses

Status code: 200

Response example (successful request){ "video-result": { "alive": true, "actions": [{ "action": 1, "confidence": 0.823 },{ "action": 3, "confidence": 0.823 },{ "action": 2, "confidence": 0.823 }], "picture": "/9j/4AAQSkZJRgABAQEAYABgAAD/2w..." }, "warning-list": []}

Status code: 400

Example response (failed request){ "error_code": "FRS.0701", "error_msg": "Parse video data failed." }



Status Code


Error Code


4.5 Face Retrieval

Function

This API is used to search an existing facial image library for one or more facessimilar to the input face, and return corresponding confidence levels.

You can input an image or face ID to retrieve faces. If multiple facial images areinput, the largest face detected in the images is used for retrieval.

Prerequisites:

















URI

POST /v2/{project_id}/face-sets/{face_set_name}/search




face_set_name

String Yes Name of a facial image library.

Request Message








image_url String Eitherimage_url,image_file,image_base64, orface_id ismandatory.

Image URL. Currently, only theURL of an OBS bucket onHUAWEI CLOUD is supportedand FRS must have thepermission to read data in theOBS bucket. For details abouthow to enable the readpermission, see ServiceAuthorization.

image_file File Eitherimage_file,image_url,image_base64, orface_id ismandatory.

Local image file, whose sizecannot exceed 8 MB. It isrecommended that the imagesize be less than 1 MB. Therequest format is Multipart.

image_base64 String Eitherimage_base64,image_url,image_file,or face_id ismandatory.

Image data (Base64-encoded).Its requirements are as follows:● The image size after Base64

encoding cannot exceed 8MB. It is recommended thatthe image size be less than 1MB.


face_id String Eitherface_id,image_url,image_file,orimage_base64 ismandatory.

Face ID returned by the systemafter a face is imported

top_n Integer No N faces returned that are mostsimilar to the input one. Thedefault value of N is 10.

threshold Double No Face similarity threshold. If thesimilarity degree of a face islower than the threshold, theface is not returned. The valueranges from 0 to 1. Therecommended value is 0.93. Thedefault value is 0.




sort JSONArray No Field sorting. For details, seeSort Syntax.

filter String No Filtering criteria. For details, seeFilter Syntax.

return_fields String No Returned customized field.

Response MessageStatus code: 200



faces List Face set to be retrieved.For details, seeSearchFace.This parameter is notincluded when the APIfails to be called.




● Example request (Method 1: Use a Base64-encoded image.)POST https://{endpoint}/v2/{project_id}/face-sets/showFaceSet/searchRequest Header:Content-Type: application/jsonX-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...

Request Body:{



"image_base64": "/9j/4AAQSkZJRgABAgEASABIAAD", "sort" : [ { "timestamp" : "asc" } ], "return_fields" : ["timestamp", "id"], "filter" : "timestamp:12"}

● Example request (Method 2: Use an image file.)POST https://{endpoint}/v2/{project_id}/face-sets/showFaceSet/searchRequest Header:X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...

Request Body:image_file: File (image file)return_fields: ["timestamp","id"]filter: timestamp:12

● Example request (Method 3: Use the image URL.)POST https://{endpoint}/v2/{project_id}/face-sets/showFaceSet/searchRequest Header:Content-Type: application/jsonX-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...

Request Body:{ "image_url":"/BucketName/ObjectName", "sort" : [ { "timestamp" : "asc" } ], "return_fields" : ["timestamp", "id"], "filter" : "timestamp:12"}

● Example request (Method 4: Use the face ID.)POST https://{endpoint}/v2/{project_id}/face-sets/showFaceSet/searchRequest Header: Content-Type: application/json X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...

Request Body: { "face_id":"6KLB1Ktu", "sort" : [ { "timestamp" : "asc" } ], "return_fields" : ["timestamp", "id"], "filter" : "timestamp:12" }

Example Responses

Status code: 200

Response example (successful request){ "faces": [ { "bounding_box": { "width": 170, "top_left_y": 37, "top_left_x": 20, "height": 170



}, "similarity": 0.996146, "external_image_id": "123", "external_fields": { "id": "home", "timestamp": 12 }, "face_id": "6KLB1Ktu" }, { "bounding_box": { "width": 170, "top_left_y": 37, "top_left_x": 20, "height": 170 }, "similarity": 0.996146, "external_image_id": "12", "external_fields": { "id": "home1", "timestamp": 12 }, "face_id": "PexOpqRj" } ]}

Status code: 400

Example response (failed request){ "error_code": "FRS.0018", "error_msg": "The service inner error."}

Status Code


Error Code


4.6 Facial Image Library Management

4.6.1 Facial Image Library Create

Function

This API is used to create a facial image library for storing facial features. You cancreate a maximum of 10 facial image libraries. Each library can contain amaximum of 100,000 facial features. If you need higher specifications, contactcustomer service.

Prerequisites:





NO TE

Use standard JSON format in the body of the application/json request.

URI

POST /v2/{project_id}/face-sets




Request Message






face_set_name String Yes Name of the facial imagelibrary.Do not start the name of afacial image library with anunderscore (_). Otherwise,the Cloud Eye service cannotcollect the number of faces.




face_set_capacity Integer No Maximum capacity of afacial image library. Thevalue is an integer multipleof 10,000, for example,30,000.The default value is 100000and the maximum value isalso 100000. You can createa new facial image library toexpand the capacity. Eachuser can use 10 facial imagelibraries free of charge. Eachlibrary can house amaximum of 100,000 facialfeatures. If you want toexpand the capacity of afacial image library, contactHUAWEI CLOUD customerservice to confirm theexpansion scale and price.

external_fields JSON No Custom data. Custom fieldscannot be named vector,bounding_box,external_image_id, face_id,create_time, _id, _all or_source, which are built-infields.The uniqueness of JSONcharacter strings is notverified. The key value of acustom field contains 1 to 36characters, and the value ofthe string type contains 1 to256 characters. For details,see Customized Fields.If you want to use customfields to add faces to theface library in subsequentoperations, you need todefine this field whencreating the face library.






face_set_info Object Facial image library information. Fordetails, see FaceSetInfo.This parameter is not included whenthe API fails to be called.

error_code String Error code returned after the APIfails to be called. For details, seeError Codes.This parameter is not included whenthe API is successfully called.

error_msg String Error message returned after theAPI fails to be called.This parameter is not included whenthe API is successfully called.


● Example requestPOST https://{endpoint}/v2/{project_id}/face-setsRequest Header:Content-Type: application/jsonX-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...

Request Body:{ "face_set_name": "test", "face_set_capacity": 100000, "external_fields" : { "timestamp" : { "type" : "long" }, "id" : { "type" : "string" }, "number" : { "type" : "integer" } }

}

Example ResponsesStatus code: 200

Response example (successful request){ "face_set_info": { "face_number": 0, "face_set_id": "WYYOFIGb", "face_set_name": "test", "create_date": "2018-05-28 02:19:00",



"face_set_capacity": 10000, "external_fields": { "timestamp" : { "type" : "long" }, "id" : { "type" : "string" }, "number" : { "type" : "integer" } } }

}

Status code: 400

Example response (failed request){ "error_code": "FRS.0002", "error_msg": "The authentication token is abnormal."}

Status Code


Error Code


4.6.2 Query of All Facial Image Libraries

Function

This API is used to query the statuses of all facial image libraries of the currentuser.

Prerequisites:


URI

GET /v2/{project_id}/face-sets







Request Message




Response Message

Status code: 200



face_sets_info List Information about allfacial image libraries. Fordetails, see FaceSetInfo.This parameter is notincluded when the APIfails to be called.



Example Requests




● Example requestGET https://{endpoint}/v2/{project_id}/face-setsRequest Header:Content-Type: application/jsonX-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...

Example Responses

Status code: 200

Response example (successful request){ "face_sets_info": [ { "face_number": 0, "face_set_id": "ylXMMZTO", "face_set_name": "test", "create_date": "2018-05-11 07:49:40", "face_set_capacity": 10000, "external_fields": { "number": { "type": "integer" }, "id": { "type": "string" }, "timestamp": { "type": "long" } } } ]

}

Status code: 400


Status Code


Error Code


4.6.3 Facial Image Library Query

Function

This API is used to query the status of a facial image library.

Prerequisites:





URI

GET /v2/{project_id}/face-sets/{face_set_name}




face_set_name

Yes String Name of a facial image library.

Request Message







face_set_info Object Facial image libraryinformation. For details,see FaceSetInfo.This parameter is notincluded when the APIfails to be called.






Example Requests


● Example requestGET https://{endpoint}/v2/{project_id}/face-sets/showFaceSetRequest Header:Content-Type: application/jsonX-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...

Example Responses

Status code: 200

Response example (successful request){ "face_set_info": { "face_number": 94, "face_set_id": "T785tx1N", "face_set_name": "showFaceSet", "create_date": "2018-05-10 01:44:39", "face_set_capacity": 10000, "external_fields": { "number": { "type": "integer" }, "id": { "type": "string" }, "timestamp": { "type": "long" } } }}

Status code: 400

Example response (failed request){ "error_code": "FRS.0202",



"error_msg": "The service has been freeze."}

Status CodeFor details about the status code, see Status Codes.

Error CodeFor details about the error code, see Error Codes.

4.6.4 Facial Image Library Delete

FunctionThis API is used to delete a facial image library and all faces in the library.

Prerequisites:


URI

DELETE /v2/{project_id}/face-sets/{face_set_name}




face_set_name





Request Message




Response Message

Status code: 200



face_set_name String Name of the facialimage library.This parameter is notincluded when the APIfails to be called.



Example Requests


● Example request



DELETE https://{endpoint}/v2/{project_id}/face-sets/showFaceSetRequest Header:Content-Type: application/jsonX-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...

Example Responses

Status code: 200

Response example (successful request){ "face_set_name": "showFaceSet" }

Status code: 400


Status Code


Error Code


4.7 Facial Resource Management

4.7.1 Face Add

Function

This API is used to add faces to a facial image library. All detected faces in theinput facial image will be added to the library.

Prerequisites:

















URI

POST /v2/{project_id}/face-sets/{face_set_name}/faces




face_set_name




Request Message






image_url String Eitherimage_url,image_file,orimage_base64 ismandatory.

Image URL. Currently, only theURL of an OBS bucket onHUAWEI CLOUD is supportedand FRS must have thepermission to read data in theOBS bucket. For details abouthow to enable the readpermission, see ServiceAuthorization.

image_file File Eitherimage_file,image_url,orimage_base64 ismandatory.

Local image file, whose sizecannot exceed 8 MB. It isrecommended that the imagesize be less than 1 MB. Therequest format is Multipart.

image_base64 String Eitherimage_base64,ima

api reference · 2020. 12. 14. · apis provided by frs comply with restful api design...

Documents