Recaptcha3 协议识别 API 对接说明

本文将介绍一种 Recaptcha3 协议识别 API 对接说明，它可让用户无需识别和点选 Recaptcha3 验证码图片，仅需通过提交 Website Key 即可实现后台自动解码，完成验证。

接下来介绍下 Recaptcha3 协议识别 API 的对接说明。

申请流程

要使用 API，需要先到 Recaptcha3 协议识别 API 对应页面申请对应的服务，进入页面之后，点击「Acquire」按钮，如图所示：

如果你尚未登录或注册，会自动跳转到登录页面邀请您来注册和登录，登录注册之后会自动返回当前页面。

在首次申请时会有免费额度赠送，可以免费使用该 API。

基本使用

首先先了解下基本的使用方式，与Recaptcha2相比，我们需要额外传入一个参数 page_action，这个参数的获取需要去代码中获取，本次展示的网速URL为：https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php，下面展示一种获取的方法：

快捷方法：

打开 f12 ，然后在Element页面中搜索 .execute( ，在红色框框区域我们可以看到有 action 参数，同时execute后面还跟着一串字符串，这也是下文需要的内容，具体的如下图所示，。

​

​

其次还需要输入需要处理验证码的网站URL，便可获得处理后的结果，首先需要简单地传递一个 website_url 字段，最后还需要输入参数 website_key，这个内容在上文可以获取到，也是execute后面的一串字符串。我们接下来就可以在界面上填写对应的内容，如图所示：

​

​

可以看到这里我们设置了 Request Headers，包括：

• accept：想要接收怎样格式的响应结果，这里填写为 application/json，即 JSON 格式。

• authorization：调用 API 的密钥，申请之后可以直接下拉选择。

另外设置了 Request Body，包括：

• page_action：需要在验证码的网站代码获取。

• website_url：需要处理验证码的网站URL。

• website_key：在Recaptcha3中的网站密钥标识符。

选择之后，可以发现右侧也生成了对应代码，如图所示：

​

​

点击「Try」按钮即可进行测试，如上图所示，这里我们就得到了如下结果：

{
  "token": "03AFcWeA5mfdNlQD0RGX9PTWPs0l65QukjwbYObCue5hygRuA6jJmBtwR98S2bmmZOjbLh7ogEMDd8NzJdq8DoHOD_LHIUWmdEL3HJS0pP2nmTTSoU_ltxORWA4sVsrWiXDgkARA4wAhJCegD6PftkRuu0KKbqRsJ7KVKukUbLU1ThBu7P3r0fybwpS11yQmF7xpbEZeFzRm_osERk9tQzs1lEYORZSVA5dimbWi42TqUC87mJHCKO0HMiU404LOyER84It7ne51V5YXEHR_o6-ORr2CmBOawdTDTsqWUwT8vyEvzy-ov-pZdl0B0A_U59_uZd7vbIwv937-iXyzkVWbakUXNMdXlHffpFYd7OLTSBhJu6nasV3IhrbnxO8eGIbPDoHIyGpA74D882ALwTnXMgkcmGeGM9YuqCrf7F06cNKY7yKiisZIU-7v3ZnHV3JUkODGpXQ6dwq2fuP5o6kgeUQVdkv4fAZ_Tx_TB_R6gPSgwulr8Q5hH34bs-v1oUl2S9mLhXT9SWvgYizU_4FN2Ou23ETXTAVD_uI9fWaDgKaLOKI1i-xHCF_LKU3wKjyYJfQhFSCSyoeGL4o1j9lZ27cEHL5AlCm_jcCiXhe2_LT_dI-r5ozuyOGv-iDZ_1XTSSnCGdmroXX56XsZAytU52zBAlYVe_aRAojruc9KdkhK4kdeBESBbDLVe3-jNFwYspe0R93SORxXXIqR9CtZrIjI_2U8XjCHFz_euChdU_wkH5BjvONVbUT1DQNuoo0ugJL5kUkFrubHppOKvoZMwIKjjK_ZX1NBeCvQvYm6IpwBWfvM4hjGI7UVXH3iZkrX9PLATIIIkA8PxTeN45k8DulzOhKLSFKK196fRlH83S8UAaM-vjBxf32Vg83C1gWzKB5sYhxqEtZeB7DNpmAkozFfubljURr7YTjtq8Bgnj0PkfzbgKk8FRl-hMUb9BUjNNuSuFC7GZVim6xQnIV9ZPaAcuzJTYcOizFJePbVEXlc9A5Vq2rDh3D7Ld5o5oqc2kK4eCrO_38le6EVTs_fRY2nXy6RMyjjaJN12lOKYwYzGKhm52gTZTrJXqeTAW8o2KfwZ9iek-tr5qxj5b40iY4V2PY6SflMQvmKLAgFhB-yo-o5PEkikQ98T-bE-wG2-3kd5NRMiD132kIhf48zhVJUGeJqdV_3m8ukyqTk26KisM12kN-h9uYefvUCxzd_mBuWlHzH9rFMlJSe8Z6lcZIVcqNF4fcEM-ukNnwMUK5H_SC48U7O_xfOaEqEpAHDC7CCyVwlGCFh0uAT8KSpaNFfxBmMPXeYrGYn83PCgMg1NZA-7PrpeidXmWdBZ2yY8MA__7uCe8clCmINseBTCIbNmAHPlI_zJKqQfhXaDbaELeD62P0Pquu_SBtdEtqPeB9Esn_yjbK3IFvAaGSnFhwhHHK8dpOI7v-rJvTigPu8MMrEUTvug_zog81kCG8HY3xorTj2OdTwdEYpeMJ1VIHSjdTcnepLB0Cffx5wAdk-gf1TGEnEyTiwII4A4vtq8r0LFK4YObOzNmBTl3IoTNheYYKpheTKH3KShMK6hXDKxDRGEUhdsW4TRtVT-dwJDqY_F7J1RwKP-xDuN98VgwQmQuhJteQUALevgI2jAGFCFfSeFbQ8BOT6ekEI0m30zDX0kh83mkE7-u9qKljYifjqbLarMNPP51QRbvAS3mHlP17PMhIKzjuIka4T2Y9XdRwDgRRdEkYiJgDvkcABTknGBMezraon8JNDRhIJMUIKpidWTdhEQ79qAEfZkowdbnTdKeWeayi1OmV_W4aox-aC62H-VIn70McXXB6zRyYlA2NvTUWgNhHWkSO1SW7uflNEyUeWFRLBZV_firMEVfIGirHOAbQqsn83BirDNPHl4xevf4nRu4gWpgOGBrzeUXQeuMWO4ZFsdWxJ2VsT19t0H5DJtxtHYXFtPZ8tFDFY-r8JKFab4S6e5v8PCrfjCWkPmDaRJal_vLFa1V1dF1l0ARu9NLW4mEuT600azFms8cMlvuCTvWI2VWyn4Wk05UvcR8FYO2-ke4E-ZFRl0jSxjlEutzbOwm2ik4eF0Wh2DBliaSr1obHaxkmLJDUIzGQ3wi49Nyn0SSOdz_BGaxuRrrxCZ4ci0e2b5cxLtkv64Njy7IYJURaBuQk99ijdw7rg3pssAa_uJSMQeZe_kLtgEWF73uT4ceSOFPVuxMGLrJRQTBYxAHVKq7kloS5wtphUr2Sp-b4kezKnCV9HNfC5NRk2KqDT-bkJ6cUYN_0yauyZK1_F4BVTk36IOCe1Cqfe3K-wAZBzvrI_Vz8Li1uEWe0b5KOQ"
}

返回结果一共有多个字段，介绍如下：

• token，此次 Recaptcha3验证码 任务处理后验证结果。

可以看到我们得到了处理 Recaptcha3验证码 的验证结果，然后我们可以用于POST或GET模拟提交给目标网站，一次性使用，有效期120s，建议在60s内使用。下面将简要介绍一种方式来把生成的token提交给目标网站：

调用token验证所对应的Python版本代码：

import requests
​
url = "https://recaptcha-demo.appspot.c/recaptcha-v3-verify.php?action=examples/v3scores&token='{token}'"
​
r = requests.get(url)
if r.status_code == 200:
    return r.text

因此我们可以得到结果：

{
  "success": true,
  "hostname": "recaptcha-demo.appspot.com",
  "challenge_ts": "2024-09-14T08:52:26Z",
  "apk_package_name": null,
  "score": 0.9,
  "action": "examples/v3scores",
  "error-codes": []
}

可以看到，其中 success 表示此处验证的处理结果，所有我们成功通过Recaptcha3验证码的验证。

另外如果想生成对应的对接代码，可以直接复制生成，例如 CURL 的代码如下：

curl -X POST 'https://api.acedata.cloud/captcha/token/recaptcha3' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "website_url": "https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php",
  "website_key": "6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9",
  "page_action": "examples/v3scores"
}'

Python 的对接代码如下：

import requests
​
url = "https://api.acedata.cloud/captcha/token/recaptcha3"
​
headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}
​
payload = {
    "website_url": "https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php",
    "website_key": "6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9",
    "page_action": "examples/v3scores"
}
​
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"
}

结论

通过本文档，您已经了解了如何使用 Recaptcha3 协议识别 API 让用户无需识别和点选 Recaptcha3 验证码图片，仅需通过提交 Website Key 即可实现后台自动解码，完成验证。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。