图形验证码识别 API 接入指南：参数规范与会话保持

图形验证码识别 API 解决什么问题

图形验证码（Normal CAPTCHA / Image-to-Text）是传统的字符扭曲、数学算式类验证码，与 reCAPTCHA、Turnstile 等需要前端交互和加密 Token 的复杂验证码不同。图形验证码识别 API 的核心能力是图像 OCR 与公式解析，输入验证码图片，输出识别后的文本字符串。

开发者在自动化测试、公开数据采集或 CI 回归中遇到图形验证码时，需要将验证码图片提交给识别服务，拿到识别结果后填入目标站点的表单完成验证。主流服务采用 REST API 接口，任务类型通常命名为 ImageToTextTask。

技术规范：任务类型与 Base64 处理

任务类型定义

图形验证码识别任务在 REST 接口中通常定义为 ImageToTextTask。完整请求包含认证凭证（如 clientKey）和任务对象：

{
  "clientKey": "YOUR_API_KEY",
  "task": {
    "type": "ImageToTextTask",
    "body": "BASE64_ENCODED_IMAGE"
  }
}

Base64 编码规范

验证码图片需要转换为 Base64 编码字符串传输，这一步是接入时最容易出错的环节：

必须移除 Data URI 前缀：浏览器 toDataURL() 返回的字符串通常包含 data:image/png;base64, 前缀，提交给 API 时需要剥离这部分，只保留纯 Base64 编码。

换行符处理：某些编码库会在 Base64 字符串中插入换行符（\n），提交前需要移除。

支持的图片格式：主流服务支持 JPG、PNG、GIF 等常见格式，但对 WebP、AVIF 等新格式支持程度不一，接入前需要核对文档。

在 Playwright 或 Puppeteer 中提取验证码图片时，推荐直接获取元素的截图 Buffer 并转为 Base64：

// 伪代码示例，实际参数需查阅对应平台文档
const captchaElement = await page.locator('img.captcha');
const imageBuffer = await captchaElement.screenshot();
const base64Image = imageBuffer.toString('base64');

调优参数：提升识别准确率

图形验证码识别 API 调优参数对比：case、numeric、math 参数的使用场景与配置方法

不同业务场景的图形验证码有不同特征，主流识别 API 提供多种参数帮助优化识别率：

case：大小写敏感性

布尔值参数，控制是否严格区分英文字母大小写。某些站点要求精确匹配大小写，某些站点不区分。设置 "case": true 要求识别服务保留原始大小写，设置为 false 则可能统一转为小写或大写。

numeric：字符集筛选

限制识别结果的字符类型，常见取值：

0：无限制，可能包含数字、字母和符号
1：仅数字
2：仅字母
3：仅数字或字母，不包含符号

当明确知道验证码只包含数字（如纯数字 PIN 码）时，设置 "numeric": 1 可以显著提升准确率。

math：算式验证码

布尔值参数，标识验证码图片是数学算式（如 3 + 5 = ?）。设置 "math": true 时，识别服务返回计算结果（如 8），而不是公式本身的字符串（如 3+5）。

minLength / maxLength：长度约束

限制识别结果的字符长度范围，帮助过滤明显错误的结果。例如已知验证码固定为 4 位数字，可以设置 "minLength": 4, "maxLength": 4。

任务流程：创建、轮询与回调

图形验证码识别通常遵循标准的任务生命周期：

创建任务：向 /createTask 端点发送 POST 请求，包含任务类型和图片数据。
获取任务 ID：服务返回 taskId，用于后续查询结果。
轮询或回调：
- 轮询：定期调用 /getTaskResult 查询任务状态，直到 status 变为 ready。
- 回调：在创建任务时提供 callbackUrl，识别完成后服务主动推送结果。

轮询间隔通常建议 1-3 秒，避免过于频繁导致限流。回调方式需要提供公网可达的 HTTPS 端点，适合高并发场景。

任务状态流转：

processing（处理中）→ ready（完成）
                   ↘ failed（失败）

识别成功时，结果通常位于响应的 solution.text 字段。

NexCaptcha 采用统一的 createTask/getTaskResult 接口处理包括图形验证码在内的多种验证码类型，开发者可以在 NexCaptcha 首页查看支持的验证码类型和接入示例。

自动化集成的关键：会话保持

这是图形验证码识别在自动化流程中最容易失败的环节。

问题根源

图形验证码在服务端与生成时的会话（Session/Cookie）严格绑定。验证码图片生成时，目标站点会在服务端记录该图片对应的答案，并通过 Session ID 或 Cookie 关联。提交验证码答案时，服务端会校验提交者的 Session 是否与生成时一致。

错误做法

在自动化脚本中，开发者容易犯的错误是用独立的 HTTP 请求重新下载验证码图片：

# 错误示例：独立请求会刷新 Session
import requests
captcha_url = driver.find_element('img.captcha').get_attribute('src')
image_data = requests.get(captcha_url).content  # 新 Session

这种做法会导致目标服务器刷新 Session，原有验证码作废。即使识别服务返回了正确的字符串,目标站点也会拒绝验证。

正确做法

方法一：DOM 元素直接截屏

通过浏览器自动化工具直接对验证码元素截屏,保持在同一个浏览器会话中：

# 伪代码：保持会话的正确方式
captcha_element = driver.find_element('img.captcha')
image_buffer = captcha_element.screenshot_as_png
base64_image = base64.b64encode(image_buffer).decode()

方法二：复用网络上下文

如果必须使用 HTTP 请求,确保复用浏览器的 Cookie 和 Session：

# 伪代码：复用 Cookie
cookies = driver.get_cookies()
session = requests.Session()
for cookie in cookies:
    session.cookies.set(cookie['name'], cookie['value'])
image_data = session.get(captcha_url).content

在 Playwright 中，可以使用 page.context() 获取的网络上下文发起请求，确保 Cookie 一致。

排障边界：识别成功 ≠ 验证通过

需要严格区分两个概念：

API 识别成功：识别服务成功返回字符串，任务状态为 ready。

目标站点接受：目标网站校验通过，允许用户继续操作。

即使 API 识别成功，目标站点仍可能拒绝验证，原因包括：

验证码过期：图形验证码通常有时效（30 秒到几分钟不等），识别耗时过长或提交延迟都会导致过期。
大小写不匹配：识别服务返回的大小写与实际要求不符，未正确配置 case 参数。
会话脱节：如前所述，Session/Cookie 不一致。
IP 限制或频率风控：目标站点检测到异常请求模式，触发额外防护。

排查时应逐层定位：先确认识别服务是否返回结果，再确认结果是否符合格式要求，最后确认会话和时效是否正常。

选型考量：准确率、延迟与计费口径

选择图形验证码识别 API 时，需要关注以下维度：

字符识别准确率

主流服务的准确率通常在 85%-95% 之间，受验证码复杂度（扭曲程度、干扰线、背景噪声）影响。准确率应以实际业务场景的验证码样本测试为准，不同站点的验证码特征差异很大。

任务延迟

图形验证码识别延迟通常在 1-5 秒（P50）到 5-15 秒（P95）之间。延迟包含网络传输、排队和识别计算时间。对于需要实时交互的场景（如用户注册流程），P95 延迟更有参考价值。

计费口径

需要明确计费规则：

按识别成功计费：只有返回结果时扣费，识别失败不计费。
按提交计费：无论识别成功与否都扣费。
退款策略：某些服务在识别错误时提供退款，但需要验证目标站点确实拒绝了结果，并在规定时间内提交退款请求。

单价通常按千次结算，图形验证码价格范围在 $0.5-$2 per 1000 次之间。实际有效单价需要综合考虑准确率和退款比例。

接入成本

SDK 支持、文档完整性和错误处理清晰度会影响接入效率。统一的 REST 接口可以降低维护多种验证码类型的复杂度。

NexCaptcha 的统一任务接口支持图形验证码和其他主流验证码类型,按成功识别计费并提供失败退款。延迟分位数和具体价格可以在 NexCaptcha 首页查看当前数据。

进一步的集成与排障

图形验证码识别 API 是自动化流程中的一个外部服务环节。完整集成需要处理：

异常处理：识别超时、网络错误、余额不足等异常的重试和降级策略。详细的超时分类和处理方案可以参考验证码 API 超时怎么处理。
结果注入：将识别结果填入目标站点表单，处理动态表单和 JavaScript 校验。
错误诊断：当验证持续失败时，逐层排查是识别错误、会话问题还是站点风控。验证码 token 返回后验证失败怎么排查提供了系统化的定位思路。
测试环境隔离：在 CI/CD 中集成验证码识别时，使用测试密钥和独立环境避免影响生产数据。Playwright 验证码测试怎么做介绍了测试密钥和环境隔离的实践。

图形验证码识别看似简单，实际工程化时需要处理编码规范、参数配置和会话一致性等多个细节。理解任务生命周期和排障边界,可以显著降低集成失败率。