Captcha Ruler

Appearance

平台透传代理 ​

背景与目的 ​

在中转服务（captcha.yoxuba.com）尚未上线前，为了让业务方（浏览器扩展、SDK）能快速验证打码链路，且不把第三方打码平台的 API Key 下发给业务方，服务端提供一层「透传代理」：把第三方打码平台（2Captcha / Nopecha / CapMonster 等）的官方接口原样转发，API Key 由服务端注入。

业务方直接使用第三方平台官方 SDK，仅把 base_url 指向透传代理即可，几乎不动请求代码。

业务方（扩展/SDK，用第三方官方 SDK）
   │  HTTP（不带 API Key）
   ▼
透传代理  test-captcha.yoxuba.com/api/v1/proxyplatform/{platform}/*
   │  注入 API Key + 原样转发
   ▼
第三方打码平台官方接口

端点设计 ​

https://test-captcha.yoxuba.com/api/v1/proxyplatform/{platform}/{原生路径}
路径段含义
/api/v1/proxyplatform透传代理固定前缀
{platform}上游平台：2captcha / nopecha / capmonster
{原生路径}第三方平台官方接口的剩余路径，原样透传（含 query）

代理根据 {platform} 决定三件事：① 上游 host；② API Key 注入方式；③ 其余 path / method / query / body 原样转发。

端点设计评估

该设计合理：{platform} 段同时承担「选上游 host、定注入方式、路由分发」，其后整段原样透传，与官方 SDK 的 base_url 拼接逻辑天然契合——业务方改一个 base_url，SDK 内部拼出的子路径自动落到透传代理上。

透传映射示例 ​

代理端点透传到
POST /api/v1/proxyplatform/2captcha/createTaskhttps://api.2captcha.com/createTask
POST /api/v1/proxyplatform/2captcha/getTaskResulthttps://api.2captcha.com/getTaskResult
POST /api/v1/proxyplatform/nopecha/v1/token/recaptcha2https://api.nopecha.com/v1/token/recaptcha2
POST /api/v1/proxyplatform/capmonster/createTaskhttps://api.capmonster.cloud/createTask

接口示例：提交任务（以 2Captcha createTask 为例） ​

请求：

POST /api/v1/proxyplatform/2captcha/createTask
Content-Type: application/json
json
{
  "clientKey": "any",
  "task": {
    "type": "RecaptchaV2TaskProxyless",
    "websiteURL": "https://example.com",
    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
  }
}
  • clientKey：业务方可填任意占位值，代理透传时覆盖为真实 API Key，业务方无需知道真实 Key。

响应（原样返回第三方响应，代理不改动）：

json
{
  "errorId": 0,
  "taskId": 123456
}

处理中（status: processing）、完成（status: ready，含 solution）、错误（errorId: 1，含 errorCode）等状态与字段均与 2Captcha 官方完全一致，业务方按官方文档解析即可。轮询结果走 POST /api/v1/proxyplatform/2captcha/getTaskResult，请求/响应同样原样透传。

API Key 注入规则（核心） ​

业务方请求一律不带第三方 API Key，由代理按平台注入：

平台上游 host注入位置
2captchaapi.2captcha.comBody JSON 的 clientKey 字段（覆盖业务方传入值）
capmonsterapi.capmonster.cloudBody JSON 的 clientKey 字段（覆盖业务方传入值）
nopechaapi.nopecha.comHeader Authorization: Basic <key>

鉴权位置不一致

Nopecha 鉴权是 HTTP Header（Authorization: Basic），与 2Captcha / CapMonster（在 body clientKey）不同。代理必须按 {platform} 分支选择注入方式，不能用统一逻辑。

2Captcha 与 CapMonster 接口同构（同为 /createTask + /getTaskResult、clientKey 认证、task 对象），可共用同一套注入与透传逻辑，仅上游 host 不同。

透传规则 ​

  • HTTP method 原样转发（2Captcha 用 POST，Nopecha 结果查询为 GET，不能固定 method）
  • path 原样转发（{platform} 之后的整段，包括 Nopecha 的 /v1/token/{type} 类型段，不剥离）
  • query string 原样转发
  • request body 原样转发（仅按平台覆盖凭证字段 / 注入凭证 Header）
  • response：HTTP 状态码 + body 原样返回，代理不转换格式、不抽取字段

业务方对接（改 base_url 即可） ​

以 2Captcha 官方 SDK 为例，仅把 base_url 指向透传代理：

原: https://api.2captcha.com
改: https://test-captcha.yoxuba.com/api/v1/proxyplatform/2captcha

SDK 内部拼出的 /createTask、/getTaskResult 自然落到透传代理上，业务方其余代码无需改动。Nopecha SDK 同理，base_url 改为 https://test-captcha.yoxuba.com/api/v1/proxyplatform/nopecha。

Copyright © 2026