Python 中的 GeeTest v4:只读一次 ID,每次提交都识别

GeeTest v4 在 Python 里归结为一个 id 加每次表单提交一次调用。只从页面上读一次 captcha_id,用 CapSkip SDK 的 solver.geetest_v4() 要一个 pass,再把它返回的五个值 captcha_id、lot_number、pass_token、gen_time 和 captcha_output 以相同的名字原样发送回去。这项识别由 CapSkip GeeTest v4 识别工具 在你自己的 Windows PC 上完成,采用统一授权,所以被拒绝的 pass 只需要再识别一次,不会产生额外费用。每次尝试前都不用先去获取任何东西,这是它和 gt 与 challenge 这一对参数的区别所在,那种做法见 GeeTest v3 流程.
识别 GeeTest v4 之前你需要什么
- Windows 上的 CapSkip 5.0.0 或更高版本(更新日志列出该版本支持识别 GeeTest v4,日期为 2026 年 11 月 14 日),以及 Python SDK 1.8.0 或更高版本(2026 年 11 月 16 日)。 API 文档中的 GeeTest v4 部分 描述了该请求。
- Python 3.10 或更高版本,这是 capskip 1.8.0 和 requests 2.34.2 声明的最低版本。我运行过的版本是 Windows 11 上的 Python 3.11.7、3.13.7 和 3.14.0。用 python -m pip install capskip requests 安装这两个包。capskip 包还会安装 httpx 和 aiofiles,只有异步客户端会用到它们。
- CapSkip 的地址。Local mode(127.0.0.1)只有运行它的那台 PC 才能访问。在 Server mode 下,它会改为监听你的网络地址或公网 IP,这样其他机器上的脚本也能访问它。设置指南的 连接设置 一节说明了在哪里切换模式。
我用了两个自己写的模拟服务器来测试,一个充当 CapSkip,一个充当带评论表单的站点。没有发生真实的识别,所以我给不出真实的识别耗时,模拟服务器里的每条站点规则也都是我定的。在真实站点上,后端会用私钥生成签名,把这五个值转发给 GeeTest,具体见 GeeTest 服务端 API 参考 中的说明。模拟服务器无法证明真实后端会接受任何内容。
第 1 步:在页面上找到 captcha_id
把第一个代码块保存为 comment_geetest.py,之后的每个代码块按顺序添加到文件末尾。第 3 步之后文件就完整了。把 PAGE_URL 指向显示该小组件的页面。在 Server mode 下,把 CapSkip 所在机器的地址填到 host 里。
# python -m pip install capskip requests
import re
import requests
from capskip import ApiException, CapSkip
PAGE_URL = "https://example.com/comment" # the page that shows the widget
FIELDS = ("captcha_id", "lot_number", "pass_token", "gen_time", "captcha_output")
# Local mode. In Server mode, use the address of the CapSkip machine.
solver = CapSkip(host="127.0.0.1", port=8080)captcha_id 是公开的,对每位访客都一样,所以只需读取一次并重复使用。页面把它作为 captchaId 选项交给 initGeetest4,小组件脚本也会把它作为 captcha_id 查询参数,放在发往 gcaptcha4.geetest.com/load 的请求里。CapSkip GeeTest v4 页面描述的是 32 个字符的 id,但 SDK 不检查格式,所以这个正则接受任何单词字符或连字符。它按名称查找该选项,而不是解析整个调用,因此在嵌套、单引号和键顺序不同的情况下都能正常工作。
def read_captcha_id(html):
"""Return the captcha_id the page gives to the GeeTest v4 script."""
for pattern in (
r"\bcaptchaId[\"']?\s*:\s*[\"']([\w-]+)[\"']", # initGeetest4({captchaId: ...})
r"[?&]captcha_id=([\w-]+)", # a gcaptcha4.geetest.com/load address
):
found = re.search(pattern, html)
if found:
return found.group(1)
raise RuntimeError("no captcha_id in the page, read it from the Network tab")
def open_session():
session = requests.Session()
page = session.get(PAGE_URL, timeout=30) # cookies arrive with the page
return session, read_captcha_id(page.text)我在六个模拟页面上运行了 read_captcha_id:id 在双引号里;在单引号里并夹在其他选项之间;在嵌套对象里,带引号的键并不排第一;在变量里,键放在最后;只出现在 load 地址里;以及哪里都没有,因为由脚本在运行时构建这个调用。遇到最后这种情况,打开一次浏览器的 Network 标签页,筛选 gcaptcha4,然后从 load 请求里复制 captcha_id。我没有在真实站点上运行过这个函数。
第 2 步:用 geetest_v4() 要一个 pass
方法签名是 solver.geetest_v4(captcha_id, url, **options)。SDK 提交任务,持续轮询直到答案就绪,然后返回一个字典,所以你不需要写等待循环。url 是小组件所在页面的完整地址。下面的代码块只保留表单需要的五个字段,并且只在你设置了 risk_type 时才加上它。
def pick(result):
if result.get("isOffline"):
print("offline pass: the site decides whether to accept it")
missing = [name for name in FIELDS if name not in result]
if missing:
raise RuntimeError(f"GeeTest answer did not parse, missing {missing}")
return {name: result[name] for name in FIELDS}
def get_pass(captcha_id, risk_type=None):
options = {"risk_type": risk_type} if risk_type else {}
return pick(solver.geetest_v4(captcha_id, PAGE_URL, **options))字典里的五个值是各自独立的键。它还包含 captchaId,这是 CapSkip 给任务分配的编号,不是小组件的 id:表单要的是带下划线的 captcha_id。键 code 保存着原始的 JSON 字符串,按 API 文档所说,res.php 就是这样打包这五个值的。SDK 会替你解析它,在遵循文档的模拟服务器上,code 是一个字符串,解析后正好是这五个值。请提交这些独立的字段,不要提交 code。
当 GeeTest 无法访问时,它的小组件会以离线模式放行访客,此时字典里还会带上设为 True 的 isOffline,否则没有这个键。pick 函数会打印一条提示,并且仍然返回这五个字段,因为是否接受离线通过由站点决定。
risk_type 选项适用于允许调用方选择挑战类型的站点。按 API 文档,可用的值有 slide、icon、nine、word、phrase、match、winlinze、svg_seed、svg_icon 和 ai,而且只有站点允许时 GeeTest 才会采用,所以其他情况下请省略它。SDK 只检查它是不是字符串:slide 和 nine 原样到达了模拟服务器,riskType 被改名为 risk_type,而像 risk_type=bogus 这样捏造的值也被发出去了。
在发送任何内容之前,SDK 会在以下情况抛出 ValidationException:captcha_id 缺失、为空或不是字符串,页面地址为空或不是绝对的 http 或 https URL,risk_type 不是字符串,riskType 和 risk_type 的值不同,以及任何 API 不接受的选项。这包括 userAgent,hCaptcha 和 MTCaptcha 的方法接受它,而这个方法不接受,还有 v3 的名字 gt 和 challenge。针对一个没有服务器监听的端口,这些情况每一种都在远不到百分之一秒内抛出。对于同样的错误,API 文档给出的是 ERROR_PAGEURL 和 ERROR_BAD_PARAMETERS,所以直接调用 in.php 的调用方会看到这些错误码,而你看到的是异常。
geetest_v4() 方法会在 CapSkip 内部运行一个真实的浏览器,所以 SDK 给它用的是 recaptchaTimeout(默认 300 秒),而不是 defaultTimeout。我两个都检查了。把 defaultTimeout 设为 3 秒、模拟服务器始终不回答时,调用在 9 秒后仍在轮询。把 recaptchaTimeout 设为 3 时,它在 3.76 秒后抛出 TimeoutException,因为 SDK 分别在 0、0.25、0.76 和 1.76 秒发出询问,再休眠 2 秒,然后才检查截止时间。同样的节奏也会延迟成功的返回:1 秒后就绪的 pass 在 1.76 秒返回,2 秒后就绪的在 3.76 秒返回,6 秒后就绪的在 7.76 秒返回。这些数据来自 Python 3.14.0、capskip 1.8.0 和默认轮询,针对的是模拟服务器。CapSkip GeeTest v4 页面给出的数据是:点击一下即可通过的约 1 到 4 秒,滑块约 15 到 20 秒,所以请按你的站点可能出现的最慢类型来设置 recaptchaTimeout。
第 3 步:提交这五个值,下一次提交前再识别一次
用上面的名字发送这五个值,放在你自己的字段旁边,并对照页面自己的提交在 Network 标签页里发送的内容。这个函数还会把页面作为 Referer 发送。requests 库既不加 Referer,也不加 Origin,而有些框架会拒绝两者都没有的 HTTPS 表单提交,我的模拟服务器就是这样返回了 403。
POST_URL = PAGE_URL # the form's action address, if it differs from the page
def post_comment(session, fields, author, text):
return session.post(
POST_URL,
data={"author": author, "comment": text, **fields}, # your form's own fields
headers={"Referer": PAGE_URL}, # requests sends none by itself
timeout=30,
)每次表单提交都要重新识别。API 文档是这么说的,我的模拟服务器也遵循它:它拒绝了同样五个值的第二次提交,理由是已经用过;也拒绝了在识别 3 秒后才提交、而有效期设为 2 秒的 pass。所以循环在遍历评论的过程中为每条评论要一个 pass,而 captcha_id 只在 open_session 时读取一次。只有在出现 ERROR_CAPTCHA_UNSOLVABLE,或站点提示验证码检查失败时,它才会请求新的识别。其他任何 ApiException 都会直接抛出,因为错误的密钥会以同样的方式再次失败。
判断是否被拒绝,要用你站点上的一整句话,这里是 captcha check failed。只用 captcha 这个单词来判断,会匹配到空评论之后重新显示的评论页面,它仍然带有小组件标记,结果因为与验证码无关的错误白白用掉了三个任务。更短的 check failed 则匹配到了 Referer 检查返回的 403 页面。
def submit_all(session, captcha_id, comments, passes=None):
saved = 0
for index, (author, text) in enumerate(comments):
for attempt in range(1, 4):
ready = passes[index] if passes and attempt == 1 else None
try:
fields = ready or get_pass(captcha_id) # a new solve per form post
except ApiException as err:
if "ERROR_CAPTCHA_UNSOLVABLE" not in str(err):
raise # a wrong key or a bad request fails again
print(f"comment {index + 1}, attempt {attempt}: unsolvable, new task")
continue
reply = post_comment(session, fields, author, text)
if "Comment saved" in reply.text: # your site's success sign
saved += 1
break
if "captcha check failed" not in reply.text.lower(): # your phrase
raise RuntimeError(f"refused ({reply.status_code}), not the captcha")
print(f"comment {index + 1}, attempt {attempt}: pass refused, new solve")
else:
raise RuntimeError(f"comment {index + 1}: no luck after 3 attempts")
return saved
if __name__ == "__main__":
session, captcha_id = open_session()
comments = [("alice", "First"), ("alice", "Second"), ("alice", "Third")]
print(submit_all(session, captcha_id, comments), "comments saved")用 python comment_geetest.py 运行它(py comment_geetest.py 也行)。针对模拟服务器,脚本在 Python 3.11.7、3.13.7 和 3.14.0 上的表现相同:
| 模拟设置 | 发生了什么 |
|---|---|
| 三条评论,默认设置 | 三个任务使用同一个 captcha_id,三次提交都被接受 |
| 手写的提交:同样五个值提交了两次 | 第二次提交因已被使用而被拒绝 |
| 手写的提交:pass 在识别 3 秒后提交,模拟服务器的有效期为 2 秒 | 因过期而被拒绝,下一次新的识别则通过了 |
| 开头有两次无法识别的回答 | 重试两次,第三个任务的 pass 被接受 |
| 连续三次无法识别的回答 | 用掉三个任务后抛出 RuntimeError |
| 离线 pass,站点接受 | 打印了一条提示,用了一个任务后提交被接受 |
| 离线 pass,站点拒绝 | 三个任务,然后 RuntimeError |
| 空评论,页面连同小组件标记再次显示 | 用了一个任务后 RuntimeError。如果用 captcha 这个单词来判断,则用掉三个任务 |
| 不带 Referer 头的表单提交 | 403,用了一个任务后 RuntimeError |
| 开启了密钥验证,SDK 使用默认密钥 | 用了一个任务后 ApiException。换成正确的 apiKey 后被接受 |
请把这张表当作对我的模拟服务器和我的脚本的测试,而不是对 GeeTest 的测试。文档说要尽快提交,并且每次表单提交都要重新识别。单次使用和两秒的有效期是我的模拟服务器自己的规则。
用 AsyncCapSkip 同时提交多条
异步客户端值得用只有一个原因:一个 pass 要花几秒钟,而三个可以同时请求。AsyncCapSkip 基于 httpx,所以 asyncio.gather 能让这些识别重叠进行,而表单提交仍然使用普通的 requests。在模拟服务器每个 pass 耗时 3.0 秒的情况下,三次提交逐个识别需要 11.35 秒,重叠识别需要 4.09 秒,环境是 Python 3.14.0,模拟服务器里同时打开了三个任务。
两个代码块里的端口 8080 是 2captcha 风格服务的默认值,所以请使用 CapSkip 设置中显示的端口。更大的并发池写法见文章 用 Python 并行识别验证码。把第 3 步中的主代码块替换为下面这个。识别失败会在 solve_all 里变成 None,submit_all 再用一次调用重新请求,所以错误的密钥最终仍然得到同样的 ApiException。请求的 pass 数量,只要是你能在它们还新鲜时提交完的就行,较长的列表请分批处理。
import asyncio
from capskip import AsyncCapSkip
async def solve_all(captcha_id, count):
# Local mode. In Server mode, use the address of the CapSkip machine.
async_solver = AsyncCapSkip(host="127.0.0.1", port=8080)
jobs = [async_solver.geetest_v4(captcha_id, PAGE_URL) for _ in range(count)]
results = await asyncio.gather(*jobs, return_exceptions=True)
return [pick(r) if isinstance(r, dict) else None for r in results]
def submit_overlapped(comments):
session, captcha_id = open_session()
passes = asyncio.run(solve_all(captcha_id, len(comments)))
return submit_all(session, captcha_id, comments, passes)
if __name__ == "__main__":
comments = [("alice", "First"), ("alice", "Second"), ("alice", "Third")]
print(submit_overlapped(comments), "comments saved")常见错误
CapSkip 的错误码来自 API 文档,异常行来自 SDK 源码,最后一行是我对文档中每次表单提交都要重新识别这句话的理解。
| 错误 | 原因 | 修复 |
|---|---|---|
| ValidationException | SDK 在你的机器上拒绝了这些参数,没有联系 CapSkip,原因是第 2 步中的某一条 | 异常文本会指出有问题的参数 |
| ERROR_CAPTCHA_UNSOLVABLE | 这个任务没能得到 pass | 提交一个新任务,submit_all 最多会这样尝试三次。文档说应用可能会返回在 Settings 里设置的替换文本,所以如果你改过它,请匹配改过的文本 |
| ERROR_KEY_DOES_NOT_EXIST 或 ERROR_WRONG_USER_KEY | 应用会检查密钥(API Key Validation),而你的密钥缺失或错误。不带 apiKey 的调用使用密钥 capskip,模拟服务器用第一个错误码回应了它 | 把你的真实密钥作为 apiKey 传给 CapSkip() |
| ERROR_PROXY_FORMAT | 文档把它列为 CapSkip 无法读取的代理值,并要求不带协议前缀。SDK 把带前缀的值原样发送了出去 | 写成 login:password@IP:PORT,不要带 http:// |
| NetworkException | 任务发出时,该主机和端口没有应答,我在 Windows 上大约 2 秒后看到了这个结果。如果服务器在轮询途中不再回应,则会得到 TimeoutException | 确认 CapSkip 已打开,并且 host 和 port 与连接设置一致 |
| TimeoutException | 在 recaptchaTimeout 内没有 pass 到达,默认是 300 秒,除非你设置了别的值 | 在 CapSkip 应用里查看这个任务,然后重新运行脚本 |
| 站点提示验证码检查失败 | 这是我的推断,不是文档列出的清单:这五个值之前被用过、太旧了,或者被改动过 | 每组值只提交一次,并立即原样提交,同时带上页面作为 Referer |
常见问题
我可以从另一台电脑调用 CapSkip 吗?
可以,通过 Server mode。在 CapSkip 所在 PC 的连接设置里把它打开,然后把那台 PC 的地址作为 host 传给 CapSkip(),如果开启了 API Key Validation,再把你的密钥作为 apiKey 传入。Server mode 在启动时会把 CapSkip 的端口对所有地址开放,所以要靠一条针对你不信任的机器的 Windows Firewall 阻止规则来挡住其他人。再加一条允许规则不会改变任何事。它仍然是你自己的 Windows 机器,仍然没有计量。
GeeTest v4 需要代理吗?
刚开始不需要。API 文档说,测试时用一个地址就可以,并说 GeeTest 的频率限制针对的是来自同一地址的持续请求。如果量大,请在应用里加载一个代理池,或者给单个任务指定它自己的代理,任务代理的优先级高于代理池。 关于验证码识别工具代理的文章 介绍了如何选择代理。在 Python 中,这个选项可以是一个字典, proxy={"type": "HTTP", "uri": "login:password@IP:PORT"},也可以是一个普通字符串,旁边再带上 proxytype。两种形式到达模拟服务器时都是 proxy 和 proxytype 字段。
如果页面给我的是 gt 和 challenge 呢?
那说明站点使用的是 GeeTest v3,它每次尝试都需要一个新的 challenge,返回的是 challenge、validate 和 seccode。这个流程见 用 Python 处理 GeeTest v3.
简短版结论
GeeTest v4 在 Python 里就是读一次 captcha_id、每次表单提交识别一次,再把五个字段原样发回去。因为 CapSkip 是一个 无限量验证码识别工具 并且运行在你自己的 PC 上,所以重复识别不会增加账单。 Python 验证码识别页面 列出了其他类型的 SDK 调用。
