接口說明

基于科大訊飛自研的人臉算法，可實(shí)現(xiàn)對(duì)比兩張照片中的人臉信息，判斷是否是同一個(gè)人并返回相似度得分。

集成人臉比對(duì)API時(shí)，需按照以下要求：

#鑒權(quán)說明

在調(diào)用業(yè)務(wù)接口時(shí)，請(qǐng)求方需要對(duì)請(qǐng)求進(jìn)行簽名，服務(wù)端通過簽名來校驗(yàn)請(qǐng)求的合法性。 通過在請(qǐng)求地址后面加上鑒權(quán)相關(guān)參數(shù)的方式，參數(shù)具體如下： http示例url：

https://api.xf-yun.com/v1/private/s67c9c78c?authorization=YXBpX2tleT0iYXBpa2V5WFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFgiLCBhbGdvcml0aG09ImhtYWMtc2hhMjU2IiwgaGVhZGVycz0iaG9zdCBkYXRlIHJlcXVlc3QtbGluZSIsIHNpZ25hdHVyZT0iSk5od3prMWtLYjUwdUVGbEUxS2xCbk83K09NTjNZUk5LZVFsYzVMYVltTT0i&host=api.xf-yun.com&date=Fri%2C+17+Jul+2020+06%3A26%3A58+GMT

鑒權(quán)參數(shù)：

? date參數(shù)生成規(guī)則：

date必須是UTC+0或GMT時(shí)區(qū)，RFC1123格式(Fri, 17 Jul 2020 06:26:58 GMT)。
服務(wù)端會(huì)對(duì)date進(jìn)行時(shí)鐘偏移檢查，最大允許300秒的偏差，超出偏差的請(qǐng)求都將被拒絕。

? authorization參數(shù)生成格式：

1）獲取接口密鑰APIKey 和 APISecret。
在訊飛開放平臺(tái)控制臺(tái)，創(chuàng)建一個(gè)應(yīng)用后打開人臉比對(duì)頁面可以獲取，均為32位字符串。

2）參數(shù)authorization base64編碼前（authorization_origin）的格式如下。

api_key="$api_key",algorithm="hmac-sha256",headers="host date request-line",signature="$signature"

其中 api_key 是在控制臺(tái)獲取的APIKey，algorithm 是加密算法（僅支持hmac-sha256），headers 是參與簽名的參數(shù)（見下方注釋）。
signature 是使用加密算法對(duì)參與簽名的參數(shù)簽名后并使用base64編碼的字符串，詳見下方。

注： headers是參與簽名的參數(shù)，請(qǐng)注意是固定的參數(shù)名（"host date request-line"），而非這些參數(shù)的值。

3）signature的原始字段(signature_origin)規(guī)則如下。

signature原始字段由 host，date，request-line三個(gè)參數(shù)按照格式拼接成，
拼接的格式為(\n為換行符,’:’后面有一個(gè)空格)：

host: $host\ndate: $date\n$request-line

假設(shè)

請(qǐng)求url = api.xf-yun.com
date = Fri, 17 Jul 2020 06:26:58 GMT

那么 signature原始字段(signature_origin)則為：

host: api.xf-yun.com
date: Fri, 17 Jul 2020 06:26:58 GMT
POST /v1/private/s67c9c78c HTTP/1.1

4）使用hmac-sha256算法結(jié)合apiSecret對(duì)signature_origin簽名，獲得簽名后的摘要signature_sha。

signature_sha=hmac-sha256(signature_origin,$apiSecret)

其中 apiSecret 是在控制臺(tái)獲取的APISecret

5）使用base64編碼對(duì)signature_sha進(jìn)行編碼獲得最終的signature。

signature=base64(signature_sha)

假設(shè)

APISecret = apisecretXXXXXXXXXXXXXXXXXXXXXXX	
date = Fri, 17 Jul 2020 06:26:58 GMT

則signature為

signature=JNhwzk1kKb50uEFlE1KlBnO7+OMN3YRNKeQlc5LaYmM=

6）根據(jù)以上信息拼接authorization base64編碼前（authorization_origin）的字符串，示例如下。

api_key="apikeyXXXXXXXXXXXXXXXXXXXXXXXXXX", algorithm="hmac-sha256", headers="host date request-line", signature="JNhwzk1kKb50uEFlE1KlBnO7+OMN3YRNKeQlc5LaYmM="

注： headers是參與簽名的參數(shù)，請(qǐng)注意是固定的參數(shù)名（"host date request-line"），而非這些參數(shù)的值。

7）最后再對(duì)authorization_origin進(jìn)行base64編碼獲得最終的authorization參數(shù)。

authorization = base64(authorization_origin)
示例：
authorization=YXBpX2tleT0iYXBpa2V5WFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFgiLCBhbGdvcml0aG09ImhtYWMtc2hhMjU2IiwgaGVhZGVycz0iaG9zdCBkYXRlIHJlcXVlc3QtbGluZSIsIHNpZ25hdHVyZT0iSk5od3prMWtLYjUwdUVGbEUxS2xCbk83K09NTjNZUk5LZVFsYzVMYVltTT0i

#鑒權(quán)結(jié)果

如果鑒權(quán)失敗，則根據(jù)不同錯(cuò)誤類型返回不同HTTP Code狀態(tài)碼，同時(shí)攜帶錯(cuò)誤描述信息，詳細(xì)錯(cuò)誤說明如下：

認(rèn)證失敗返回示例：

HTTP/1.1 403 Forbidden
Date: Thu, 06 Dec 2018 07:55:16 GMT
Content-Length: 116
Content-Type: text/plain; charset=utf-8
{
    "message": "HMAC signature does not match"
}

#請(qǐng)求參數(shù)

在調(diào)用業(yè)務(wù)接口時(shí)，都需要在 Http Request Body 中配置以下參數(shù)，請(qǐng)求數(shù)據(jù)均為json字符串。
請(qǐng)求參數(shù)示例：

{
  "header": {
    "app_id": "XXXXXXXX",
    "status": 3
  },
  "parameter": {
    "s67c9c78c": {
      "service_kind": "face_compare",
      "face_compare_result": {
        "encoding": "utf8",
        "compress": "raw",
        "format": "json"
      }
    }
  },
  "payload": {
    "input1": {
      "encoding": "jpg",
      "status": 3,
      "image": "/4AAQSkZJRgA..."
    },
    "input2": {
      "encoding": "jpg",
      "status": 3,
      "image": "/9j/4AAQSkZJ..."
    }
  }
}

請(qǐng)求參數(shù)說明：

#返回結(jié)果

如出現(xiàn)錯(cuò)誤碼，可到 這里 查詢。
返回參數(shù)示例：

{
  "header": {
    "code": 0,
    "message": "success",
    "sid": "asexxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "payload": {
    "face_compare_result": {
      "compress": "raw",
      "encoding": "utf8",
      "format": "json",
      "text": "ewoJInJldCIgOiAwLAoJInNjb3JlIiA6IDAuOTk2MTg2MDc3NTk0NzU3MDgKfQo="
    }
  }
}

返回參數(shù)說明：

text字段base64解碼示例

{
	"ret" : 0,
	"score" : 0.99618607759475708
}

text字段參數(shù)說明：

#常見問題

#人臉比對(duì)的主要功能是什么？

答：人臉比對(duì)可以對(duì)比兩張照片中的人臉信息，判斷是否是同一個(gè)人。

#人臉比對(duì)支持什么應(yīng)用平臺(tái)？

答：目前支持Web API應(yīng)用平臺(tái)。

#人臉比對(duì)對(duì)人臉有什么要求嗎？

答：需要清晰的人臉照片，人臉大小不小于30*30像素，其中人臉俯仰角、左右偏航角、人臉翻轉(zhuǎn)角60°以內(nèi)識(shí)別效果更好。