极验 GeeTest v4 识别 API
接口健康状态
- 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 等待后重试。
写代码前,先问清楚我要处理多少个、结果存成什么格式,再把方案和大概花费讲给我确认。请求参数
#| 参数名 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|---|
Authorization | header | string | 是 | - | Bearer 加你的 API Key。在控制台创建;不要放进网址或代码仓库。 |
type | body | string | 是 | geetest | 验证码类型,固定值。 |
website_url | body | string | 是 | - | 验证码所在页面的完整 URL |
website_key | body | string | 是 | - | 页面里的站点公钥(sitekey) |
risk_type | body | string | 否 | - | 页面初始化极验 v4 时传的 riskType(如 slide、icon)。只有页面在 initGeetest4 里显式传了它才需要填:看 gcaptcha4.geetest.com/load 请求里的 risk_type 参数;页面没传就别填,填错会解成另一种题 |
代码示例
#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。
响应示例
#{ "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 空结果
- 没有数据,不扣费。