极验 GeeTest v4 识别 API

POST

接口健康状态

24h 健康值
正常
  • 健康 / 正常
  • 可用
  • 少量可用
  • 基本不可用
正常

24 小时趋势

30 天趋势

极验 GeeTest v4 是 GeeTest 的无感打分 / 滑块拼图 / 点选图像 / 点选文字(v4 按风险自适应下发,同一个 captchaId 可能出不同题)。页面上先出现一条「点击按钮进行验证」的横条或浮层按钮;低风险用户点一下直接打勾放行,高风险才升级成滑动拼图、按提示顺序点击图标/文字,甚至五子棋这类推理题。弹窗右下角带极验 logo 与刷新、关闭按钮。

请求发到 POST https://api.everyinfra.com/api/v1/captcha,type 填 geetest,参数和 type 放在请求体同一层。 单价 $2.08 / 千次(每次成功识别 $0.002083),失败和空结果都不收费。

AI 提示词

#
请帮我用 EveryInfra 的「极验 GeeTest v4」接口写一个调用脚本。

接口约定:
- 请求:POST https://api.everyinfra.com/api/v1/captcha,请求头 Authorization: Bearer <API Key>;Key 从环境变量 EVERYINFRA_API_KEY 读取,不要写进代码。
- 请求体里 type 填 geetest,参数和它平铺在同一层。
- 必填参数:
  - website_url:验证码所在页面的完整 URL
  - website_key:页面里的站点公钥(sitekey)
- 可选参数:
  - risk_type:页面初始化极验 v4 时传的 `riskType`(如 `slide`、`icon`)。只有页面在 `initGeetest4` 里显式传了它才需要填:看 `gcaptcha4.geetest.com/load` 请求里的 `risk_type` 参数;页面没传就别填,填错会解成另一种题
- 示例请求体:
{
  "type": "geetest",
  "website_url": "https://gt4.geetest.com/",
  "website_key": "54088bb07d2df3c46b79f80300b0abbe",
  "risk_type": "slide"
}
- 计费:单价 $2.08 / 千次(每次成功识别 $0.002083),失败和空结果都不收费。
- 返回 422 时,按错误信息里的候选参数和允许值修正;返回 429 或 503 时,按 Retry-After 等待后重试。

写代码前,先问清楚我要处理多少个、结果存成什么格式,再把方案和大概花费讲给我确认。

请求参数

#
参数名位置类型必填默认值说明
Authorizationheaderstring是-Bearer 加你的 API Key。在控制台创建;不要放进网址或代码仓库。
typebodystring是geetest验证码类型,固定值。
website_urlbodystring是-验证码所在页面的完整 URL
website_keybodystring是-页面里的站点公钥(sitekey)
risk_typebodystring否-页面初始化极验 v4 时传的 riskType(如 slide、icon)。只有页面在 initGeetest4 里显式传了它才需要填:看 gcaptcha4.geetest.com/load 请求里的 risk_type 参数;页面没传就别填,填错会解成另一种题

代码示例

#
bash
curl -X POST 'https://api.everyinfra.com/api/v1/captcha' \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "type": "geetest",
  "website_url": "https://gt4.geetest.com/",
  "website_key": "54088bb07d2df3c46b79f80300b0abbe",
  "risk_type": "slide"
}'

OpenAPI 定义 (JSON)示例从环境变量 EVERYINFRA_API_KEY 读取 Key,复制出去的代码不含你的 Key。

响应示例

#
2026年10月25日 06:42(北京时间)用上方代码示例的参数真实调用所得。token 与 solution 是那次的真实返回;id、billing、quota 每次调用都不同,只给结构。
json
{  "id": "req_…",  "type": "geetest",  "solution": {    "captcha_id": "54088bb07d2df3c46b79f80300b0abbe",    "lot_number": "16b9dcb0b31a4d3c9dff2db8157dd7d8",    "pass_token": "447676b283c3d1730b7d8a0369b47a97a0ce49a888439583a5db418e0ce1db88",    "gen_time": "1792881725",    "captcha_output": "K1IaJ9ya0bTODk_LLqK2sN5GN6_dAbrWUju7GGKmMewkDLoKP9r2yW6buayxzB-IOoEBmI_L6g7i5MkpyhO6b5XGXaAFFcFMr-pJjstLBLjSV1Q6QK3j7PTTVcqDEJCQvZhVV8ITwzoJFQiEtRxN-mngBD9FJCy9-DQxhkQb70Sf76b7CpuPlvCVjpn4DNKeheTeVA21IPuAG7PSIWV9R82D4XRvdYcNDq7Dyw1Dnvgi13VdIAXeSsn4BIgRP0ClCOt48e77BDoWytF8gWIdc5Qe…"  },  "billing": {    "charged": …,    "charged_usd": …,    "balance_after_usd": …,    …  },  "quota": { … }}

参数怎么取

#

下面全部是可以直接照做的定位方法:DOM 属性名、JS 全局变量名、script 上的 query 参数。

第一步先判 v3 还是 v4,判错了参数完全对不上。

看 <script> 的 src:v4 是 https://static.geetest.com/v4/gt4.js(实测极验官网 demo 页就是这一条),全局函数是 initGeetest4;v3 是 https://static.geetest.com/static/js/gt.0.5.0.js,全局函数是 initGeetest(不带 4)。在 Console 里敲 typeof initGeetest4 返回 "function" 就是 v4。

取 captcha_id(填进我们的 website_key),三个办法,按可靠度排序:

① 最可靠:看网络请求。 打开 DevTools Network,刷新页面,过滤 gcaptcha4,会看到组件自己发的第一个请求:
https://gcaptcha4.geetest.com/load?captcha_id=<32位小写十六进制>&challenge=<uuid>&client_type=web&callback=geetest_<13位毫秒时间戳>

query 里的 captcha_id 就是要填的值。这一步不会被前端改名或混淆绕过,因为它是组件发出去的。

② 看 JS 配置。 全文搜 initGeetest4(,第一个参数对象里的 captchaId 键。⚠ 注意大小写换形:前端配置叫驼峰 captchaId,网络请求和服务端校验叫下划线 captcha_id,是同一个值,不要以为是两个参数。

③ 小程序页面上是自定义组件属性:<captcha4 id="captcha" captchaId="{{captchaId}}" bindSuccess="..." />。

⚠ 不要去 DOM 上找 data-sitekey 这类属性,极验没有。 它是纯 JS 配置,不像 Turnstile / reCAPTCHA 把 key 挂在 HTML 属性上,按那个习惯找会一无所获。appendTo("#captcha") 里那个 #captcha 只是容器 id,跟 key 无关。

取到之后可以自测对不对(我实测过):

curl "https://gcaptcha4.geetest.com/load?captcha_id=<你的ID>&challenge=11111111-2222-3333-4444-555555555555&client_type=web&callback=geetest_$(date +%s)000"

返回 {"status": "success", "data": {"lot_number":...}} 说明 ID 有效;返回 {"status":"error","code":"-50103","msg":"not captcha"} 说明 ID 抄错了。

website_url 填验证码所在那一页的完整地址(含路径),不是站点首页。

怎么确认目标站用的就是它

#

组件在页面加载时就开始采集全程行为轨迹(鼠标/触摸的移动路径、按下与释放时序)、设备与浏览器环境特征,连同题面作答一起上报;服务端风控引擎给出风险判定,据此决定直接放行还是升级题型。通过后前端拿到一组一次性参数,业务后端再带着这组参数向极验 https://gcaptcha4.geetest.com/validate 做二次校验才算数。

容易搞混的

最容易和极验 v3 搞混:同厂商上一代,参数集完全不同(v3 要 gt + 每次现取的 challenge,v4 只要 captcha_id)。其次容易和网易易盾搞混,因为两者的滑动拼图外观非常接近、且在中国大陆站点上都高频出现;判别只看脚本域名:static.geetest.com 是极验,cstaticdun.126.net 是易盾。

常见部署场景

  • 航司与旅行票务(极验官网按行业分类首位就是「航司」,英文站对应 Travel & Hotel)
  • 金融银行、证券基金(官网独立行业方案页)
  • 电商与零售的抢购、领券环节
  • 游戏与社交平台的注册、登录、找回密码
  • 国际站点:v4 内置 15 种语言(zho/eng/zho-tw/zho-hk/udm/jpn/ind/kor/rus/ara/spa/pon/por/fra/deu),不是只做中国大陆

已知的坑

#
  • v4 的 /load 请求里也有一个叫 challenge 的参数,但它不是 v3 那个 challenge。 v4 的 challenge 是客户端自己随机生成的 UUID,v3 的 challenge 是服务端 API1 下发、一次性、页面加载完就已消耗。只看到「challenge」这个词就判成 v3 是最常见的误判。实测:我随手编一个 UUID 传进 v4 的 /load,照样返回 status: success。

  • 判版本更稳的两条判据:页面上有没有一个服务端下发的静态 challenge(有 gt + challenge 一对 = v3;只有 captcha_id = v4);以及成功后回传几个字段(v3 是三个 geetest_challenge / geetest_validate / geetest_seccode;v4 是四到五个 lot_number / captcha_output / pass_token / gen_time,加上你自己带的 captcha_id)。

  • v4 的五个字段必须一起提交回目标站,少一个会被拒。字段名照抄不要改大小写。

  • captchaObj.getValidate() 只在 onSuccess 回调里返回对象,其他时候一律返回 false,不是解错了,是取的时机不对。

  • 服务端二次校验还需要一个 sign_token,它是用只存在于服务端的 captcha_key 对 lot_number 做 HMAC-SHA256 得到的。那把 key 不在页面上,不要浪费时间去找,它是目标站自己的密钥,不是我们要的参数。

  • captcha_id 是站点级静态值,同一站点长期不变,可以缓存复用;v3 的 challenge 恰恰相反,每次都要现取。

  • 极验官方文档站有两套:docs.geetest.com/gt4/* 与 docs.geetest.com/BehaviorVerification/* 讲的是 v4(中/英),docs.geetest.com/captcha/* 讲的是 v3。翻错文档会拿到完全不同的参数表。

常见问题

#

极验 GeeTest v4 要传哪些参数?

必填 website_url、website_key;可选 risk_type。请求里 type 传 geetest。

解出来的东西怎么用?

返回一组字段(要一起提交),取 solution.captcha_id、solution.lot_number、solution.pass_token、solution.gen_time、solution.captcha_output。把这五个字段一起提交回目标站

initGeetest4 要去页面的哪里找?

重点找 initGeetest4、initGeetest、gcaptcha4。本页「参数去页面哪里取」一节写了全部位置与取法,含可直接粘进控制台的一行命令。

怎么确认目标站用的就是 极验 GeeTest v4?

最容易和极验 v3 搞混:同厂商上一代,参数集完全不同(v3 要 gt + 每次现取的 challenge,v4 只要 captcha_id)。其次容易和网易易盾搞混,因为两者的滑动拼图外观非常接近、且在中国大陆站点上都高频出现;判别只看脚本域名:static.geetest.com 是极验,cstaticdun.126.net 是易盾。

有什么容易踩的坑?

v4 的 /load 请求里也有一个叫 challenge 的参数,但它不是 v3 那个 challenge。 v4 的 challenge 是客户端自己随机生成的 UUID,v3 的 challenge 是服务端 API1 下发、一次性、页面加载完就已消耗。只看到「challenge」这个词就判成 v3 是最常见的误判。实测:我随手编一个 UUID 传进 v4 的 /load,照样返回 status: success。

多少钱一次,失败扣不扣?

$2.08 / 千次。按成功计费:失败或空结果不形成最终扣款;如有预留则恢复。账单按次记,标价按每千次是为了让量级读得出来。

参考资料

#

下列资料用于核对验证码厂商、题型和页面术语,不表示相关厂商对 EveryInfra 的授权或背书。 EverySolve 的参数、返回字段、可用状态和计费,以本页说明和公开类型目录为准。

#

看全部验证码类型

错误与计费

#
401
缺少 Key 或 Key 无效。
402
余额不足,先充值。
422
参数名或取值不对,按错误信息给的候选改;不扣费。
429
超过每分钟请求上限,按 Retry-After 等待后再试。
503
暂时无法完成,预扣的费用退回;结果未知时先核对,不要直接重发。
200 空结果
没有数据,不扣费。

错误码

自有访问统计常开;Google Analytics 仅在你点「同意分析」后启用。 隐私政策