Anti-Captcha 迁移指南：接口对照、错误码与灰度切换步骤

从 Anti-Captcha 迁到另一家验证码识别 API，难点通常不在改域名，而在三件事：

每种任务的字段是否真的一致；
错误码和计费口径怎么对应；
新平台在你的目标场景里能否同样被接受。

比较稳妥的顺序是：盘点现有任务 → 抽出适配层 → 按任务类型逐项核对 → 重写错误处理和成本统计 → 小流量分流对照 → 按指标逐步放量，并全程保留回退。

下文以迁到 NexCaptcha 为例。这套检查同样适用于迁往其他兼容任务 JSON 格式的服务。

第一步：盘点你在 Anti-Captcha 上实际用了什么

Anti-Captcha 采用任务模型，主要有三个接口：

POST createTask：提交任务；
POST getTaskResult：查询结果；
POST getBalance：查询余额。

鉴权方式是把 clientKey 放在请求体 JSON 里，不走 HTTP Authorization 头。

迁移前，先把代码里实际用到的部分列出来。不需要按对方文档全量对照：

任务类型：task.type 实际出现过哪些值，例如 RecaptchaV2TaskProxyless、RecaptchaV3TaskProxyless、TurnstileTaskProxyless、ImageToTextTask，以及带代理的版本。顺便统计每种类型的调用量，后面先测哪个就按这个排。
可选参数：是否用了 callbackUrl 接收结果推送，是否传了 softId 等。
结果字段：业务代码读的是 solution 里的哪个字段，gRecaptchaResponse、token 还是 text。另外看看有没有用 cost、createTime、endTime 做统计。
错误处理：哪些 errorCode 有专门分支，重试逻辑写在哪里。
接入方式：是直接调 HTTP，还是用了 Anti-Captcha 的 SDK 或第三方库。库里可能写死了主机名、任务类型名甚至轮询间隔，这时只换地址未必可行。需要改成自己的 HTTP 调用，或者确认新平台提供的 SDK 是否覆盖同样功能。

这份清单就是后面的验收表。清单上的每一行，都要在新平台上得到明确结论。

第二步：先加一层适配，再谈切换

如果业务代码到处直接拼 Anti-Captcha 的请求体，先把调用收拢成内部接口：提交任务、等待结果、查询余额。业务侧只拿统一的结果对象，包含答案、耗时、费用、平台名和错误类别。

这样两家平台可以按配置并存，分流、对照、回退都只改配置，不动业务代码。

下面是结构示意。这是伪代码，不对应任何平台的真实 SDK：

solve(task_spec):
    provider = router.pick(task_spec.type)              # 按任务类型和放量比例选平台
    task_id  = provider.create_task(task_spec)
    result   = provider.wait_result(task_id, timeout)   # 轮询或回调
    return normalize(result)  # 统一为 answer / latency / cost / provider / error_class

适配层里用轮询还是回调，取决于部署条件。两者的差别见验证码 API 轮询和回调的区别。

第三步：协议层逐项对照

NexCaptcha 官网公开的说明是：

接口同样是 createTask、getTaskResult、getBalance 任务流；
API 域名为 api.nexcaptcha.net，密钥同样放在请求体的 clientKey；
结果支持轮询，也支持 webhook；
宣称兼容 Anti-Captcha 的部分任务格式。

“部分”这两个字，就是迁移工作的重点。

环节	Anti-Captcha 文档	NexCaptcha 公开说明	迁移时要确认
鉴权	请求体 `clientKey`	请求体 `clientKey`	新旧密钥分开存放，配置名不要混用
提交任务	`createTask`，由 `task.type` 决定任务	`createTask`	你用到的每个 type 名称（含大小写）是否被接受
取结果	`status` 为 `processing` / `ready`，结果在 `solution`	`getTaskResult`，轮询或 webhook	状态取值、`solution` 内字段名是否一致
回调	`callbackUrl`	支持 webhook	参数名、推送格式、重试机制
错误	数字 `errorId` + 字符串 `errorCode`	未公开完整对照	是否沿用同名错误码，需逐项确认
计费	按任务扣费，结果附 `cost`	按千次成功识别计费，失败退款	统计口径如何对齐

NexCaptcha 目前没有公开逐任务的兼容清单和错误码对照表。最可靠的做法分两步：先拿第一步整理的任务清单向对方确认，再用小流量实测验证。

第四步：按任务类型核对参数

兼容问题往往出在高级参数上，基础字段反而很少出错。

reCAPTCHA：v2、v3、Enterprise 是不同的任务。v3 的 action 和分数要求、Enterprise 的附加参数，都要逐个对上。版本判断和参数提取方法见 reCAPTCHA 识别 API 怎么接。
Turnstile：除了站点地址和 sitekey，如果页面传了 action、cData，要确认新平台是否用同名字段接收。另外，Turnstile 组件和 Cloudflare 整页 Challenge 是两类任务。原来按哪种接入，新平台就要选对应的那种。
GeeTest：v3 和 v4 的参数结构不同，不能混用，差异见极验 v3 和 v4 区别。
图形验证码：ImageToTextTask 的图片编码、大小限制、大小写敏感、字符集约束等选项，要确认新平台都有对应项。
代理模式：带代理的任务要核对代理字段格式。Proxyless 和带代理两种版本，在新平台上不一定一一对应。

第五步：重写错误处理，不要照搬

Anti-Captcha 用 errorId（0 表示成功）加 errorCode 字符串报告错误。常见的有：

ERROR_KEY_DOES_NOT_EXIST
ERROR_NO_SLOT_AVAILABLE
ERROR_ZERO_BALANCE
ERROR_CAPTCHA_UNSOLVABLE
ERROR_RECAPTCHA_INVALID_SITEKEY

不少旧代码直接按数字 errorId 判断，这是迁移中的高风险点。新平台即使沿用同名错误码，数字也未必相同；如果用的是独立的错误码体系，就要全部重新映射。

建议在适配层把错误归成几类，业务代码只看类别：

配置类（密钥无效、sitekey 无效、参数错误）：不重试，直接告警；
容量类（暂无可用处理资源等）：退避后重试；
余额类：停止提交并告警，避免任务空转；
识别失败类：有限次数重试，并计入失败统计。

超时和长时间 processing 也要单独处理，否则切换后容易出现任务堆积。可参考验证码 API 超时怎么处理和任务一直 processing 怎么办。

第六步：用同一口径比较成本

两家的计费方式不同：

Anti-Captcha：每个任务直接扣美元费用，getTaskResult 会返回 cost 字段。按其错误码文档，ERROR_CAPTCHA_UNSOLVABLE 这类无法识别的任务仍可能计费。报错/投诉接口也有适用类型和时限限制，以其文档为准。
NexCaptcha：官网按千次成功识别标价，失败退款，量大有阶梯优惠。首页的最低单价不代表所有验证码类型的价格。

因为计费方式不同，直接比单价意义不大。更接近真实成本的算法是：

有效成本 = 统计窗口内的总支出 ÷ 被目标站点接受、业务真正完成的次数

分母不计入“拿到 token 但提交被拒”的次数。被拒的原因可能是 token 时效、注入位置、会话或 IP，不一定出在识别服务上，排查思路见验证码 token 返回后验证失败怎么排查。更多平台的计费口径对比见打码平台费用对比。

第七步：小流量分流对照，再逐步放量

Token 类结果通常只能用于一次提交，而且有时效。同一次验证不能把两家的 token 各用一遍，所以对照要按请求分流，不能镜像双发。

按请求分流的小流量对照与回退流程：适配层把流量分到两个平台，按类型比较延迟、接受率和有效成本

具体做法：

控制条件：在自有或获授权的环境中进行，两组使用同一批目标、同一网络出口、同样的并发，放在同一时间段。
放量顺序：先从调用量大、参数简单的任务类型开始。按 5%、20%、50% 这样的比例逐级放量，具体比例按自己的业务量调整。
分类型记录指标：每种任务类型单独统计以下几项，平均值和 P95 分开看，不要混用：
- 结果返回率；
- 从提交到 ready 的 P50 和 P95 延迟；
- 目标站点接受率；
- 业务完成率；
- 有效成本。
预设回退条件：例如某类型的接受率连续多个窗口明显低于 Anti-Captcha 对照组，就把这个类型切回原平台，查清原因后再放量。

官网展示的延迟、接受率等数据是站方口径，最终以你自己的对照结果为准。