接口說明

基于科大訊飛自研的人臉算法，可實現對比兩張照片中的人臉信息，判斷是否是同一個人并返回相似度得分。

集成人臉比對API時，需按照以下要求：

#鑒權說明

在調用業務接口時，請求方需要對請求進行簽名，服務端通過簽名來校驗請求的合法性。 通過在請求地址后面加上鑒權相關參數的方式，參數具體如下： 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

鑒權參數：

? date參數生成規則：

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

? authorization參數生成格式：

1）獲取接口密鑰APIKey 和 APISecret。
在訊飛開放平臺控制臺，創建一個應用后打開人臉比對頁面可以獲取，均為32位字符串。

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

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

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

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

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

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

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

假設

請求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算法結合apiSecret對signature_origin簽名，獲得簽名后的摘要signature_sha。

signature_sha=hmac-sha256(signature_origin,$apiSecret)

其中 apiSecret 是在控制臺獲取的APISecret

5）使用base64編碼對signature_sha進行編碼獲得最終的signature。

signature=base64(signature_sha)

假設

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

則signature為

signature=JNhwzk1kKb50uEFlE1KlBnO7+OMN3YRNKeQlc5LaYmM=

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

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

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

7）最后再對authorization_origin進行base64編碼獲得最終的authorization參數。

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

#鑒權結果

如果鑒權失敗，則根據不同錯誤類型返回不同HTTP Code狀態碼，同時攜帶錯誤描述信息，詳細錯誤說明如下：

認證失敗返回示例：

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"
}

#請求參數

在調用業務接口時，都需要在 Http Request Body 中配置以下參數，請求數據均為json字符串。
請求參數示例：

{
  "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..."
    }
  }
}

請求參數說明：

#返回結果

如出現錯誤碼，可到 這里 查詢。
返回參數示例：

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

返回參數說明：

text字段base64解碼示例

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

text字段參數說明：

#常見問題

#人臉比對的主要功能是什么？

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

#人臉比對支持什么應用平臺？

答：目前支持Web API應用平臺。

#人臉比對對人臉有什么要求嗎？

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