本文將介紹一種 hCaptcha 影象識別 API 對接說明，它可以透過使用者輸入識別的內容和 hCaptcha驗證碼影象，最後返回需要點選的小影象的座標，完成驗證。
接下來介紹下 hCaptcha 影象識別 API 的對接說明。
申請流程
要使用 API，需要先到 hCaptcha 影象識別 API 對應頁面申請對應的服務，進入頁面之後，點選「Acquire」按鈕，如圖所示：
如果你尚未登入或註冊，會自動跳轉到登入頁面邀請您來註冊和登入，登入註冊之後會自動返回當前頁面。
在首次申請時會有免費額度贈送，可以免費使用該 API。
基本使用
首先先了解下基本的使用方式，就是輸入需要處理 hCaptcha驗證碼影象，便可獲得處理後的結果，首先需要簡單地傳遞一個 queries 欄位，這個就是具體hCaptcha驗證碼影象，我們需要去一個有hCaptcha驗證碼網站中擷取這個驗證碼圖片，示例網站連結為： https://democaptcha.com/demo-form-eng/hcaptcha.html，點選覈取方塊即可顯示具體的完整驗證碼圖片，如下圖所示：
其中queries 欄位是上文中驗證碼影象的截圖，圖片大小建議不要超過100kb，還需要對上面圖片紅色箭頭指向的區域進行截圖，並且還需要你自行壓縮圖片大小，並且還需要將它轉換為Base64編碼，如下圖所示：
同時還需要輸入跟驗證碼影象相關的識別內容引數 question，這個支援中英文翻譯，可以直接傳相關的識別內容，由上文網頁影象中黃色箭頭執行的內容可以看出 question 輸入的應為 Please click on the UNIQUE object among the others.。具體的內容如下：
可以看到這裏我們設定了 Request Headers，包括：
accept：想要接收怎樣格式的響應結果，這裏填寫為application/json，即 JSON 格式。authorization：呼叫 API 的金鑰，申請之後可以直接下拉選擇。
另外設定了 Request Body，包括：
queries：Base64編碼的驗證碼影象列表。question：驗證碼影象相關的識別內容引數，支援直接輸入中英文。
選擇之後，可以發現右側也生成了對應程式碼，如圖所示：
點選「Try」按鈕即可進行測試，如上圖所示，這裏我們就得到了如下結果：
{
"solution": {
"label": "Please click on the UNIQUE object among the others",
"box": [
"360",
"276"
],
"confidences": 0.6354503631591797
}
}
返回結果一共有多個欄位，介紹如下：
solution，此次 hCaptcha驗證碼影象 任務處理後驗證結果。label，hCaptcha驗證碼影象所識別的內容。box，hCaptcha驗證碼影象識別結果的位置資訊，它是由影象的座標資訊構成。confidences，hCaptcha驗證碼影象識別後滿足識別內容的的置信度。
可以看到我們得到了處理 hCaptcha驗證碼影象 的驗證結果，我們只需要根據結果中 box 的位置座標資訊對該驗證碼影象進行模擬點選該區域便可透過驗證。
下面將介紹如何透過結果的 box 的位置資訊如何來點選，首先是針對上傳的驗證碼圖片進行建立直角座標系，其中中心原點在影象的左下角，360是對應的橫座標，276是對應的縱座標，我們只需要透過模擬點選驗證碼對應的座標進行點選即可，具體的影象資訊如下圖所示：
另外如果想生成對應的對接程式碼，可以直接複製生成，例如 CURL 的程式碼如下：
curl -X POST 'https://api.acedata.cloud/captcha/recognition/hcaptcha' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"question": "Please click on the UNIQUE object among the others.",
"queries": ["iVBORw0KGgoAAAANSU.....eY+85KVlzKHav28uq/WLVhL2kHUlFMKUcZbL31S8bpd0pEPKxNllXAE2wgu3uEfj+BfAzOGelsQNFAAAAAElFTkSuQmCC"]
}'
}'
Python 的對接程式碼如下：
import requests
url = "https://api.acedata.cloud/captcha/recognition/hcaptcha"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"question": "Please click on the UNIQUE object among the others.",
"queries": ["iVBORw0KGgoAAAANSU.....eY+85KVlzKHav28uq/WLVhL2kHUlFMKUcZbL31S8bpd0pEPKxNllXAE2wgu3uEfj+BfAzOGelsQNFAAAAAElFTkSuQmCC"]
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
錯誤處理
在呼叫 API 時，如果遇到錯誤，API 會返回相應的錯誤程式碼和資訊。例如：
400 token_mismatched：Bad request, possibly due to missing or invalid parameters.400 api_not_implemented：Bad request, possibly due to missing or invalid parameters.401 invalid_token：Unauthorized, invalid or missing authorization token.429 too_many_requests：Too many requests, you have exceeded the rate limit.500 api_error：Internal server error, something went wrong on the server.
錯誤響應示例
{
"success": false,
"error": {
"code": "api_error",
"message": "fetch failed"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
結論
透過本文件，您已經瞭解瞭如何使用 hCaptcha 影象識別 API 讓使用者輸入識別的內容和 hCaptcha驗證碼影象，最後返回需要點選的小影象的座標，完成驗證。希望本文件能幫助您更好地對接和使用該 API。
