# NovaCaptcha — 企业级智能验证码与视觉识别开放平台开发文档 (v2.2)

> **综合一次通过率**：`99.6%` ｜ **图像分类平均耗时**：`0.08s` ｜ **协议过盾平均耗时**：`2.4s ~ 4.2s` ｜ **集群 SLA 可用性**：`99.99%`
> **计费标准**：`1 USDT = 7,000 点`（折合 `1 RMB = 1,000 点`），仅在任务成功（`status: "ready"`）时扣费，识别失败或超时 **0 扣费**。

---

## 目录 (Table of Contents)

1. [快速开始与接口鉴权规范](#1-快速开始与接口鉴权规范)
2. [Google reCAPTCHA v2 标准版 / Invisible 隐形版过盾](#2-google-recaptcha-v2-标准版--invisible-隐形版过盾)
3. [Google reCAPTCHA v2 Enterprise 企业版过盾](#3-google-recaptcha-v2-enterprise-企业版过盾)
4. [Google reCAPTCHA v3 无感高分 Token](#4-google-recaptcha-v3-无感高分-token)
5. [Cloudflare Turnstile 挑战过盾](#5-cloudflare-turnstile-挑战过盾)
6. [九宫格 3x3 / 4x4 / 1x1 动态补图图像分类](#6-九宫格-3x3--4x4--1x1-动态补图图像分类)
7. [Arkose Labs FunCaptcha 协议过盾与 6/10 宫格识图](#7-arkose-labs-funcaptcha-协议过盾与-610-宫格识图)
8. [通用英数 / 算术图文验证码 OCR](#8-通用英数--算术图文验证码-ocr)
9. [极验 GeeTest v3/v4 与 Amazon AWS WAF 过盾](#9-极验-geetest-v3v4-与-amazon-aws-waf-过盾)
10. [账户余额查询与完整错误码字典](#10-账户余额查询与完整错误码字典)
11. [Chrome / Edge / 指纹浏览器插件安装与配置详解](#11-chrome--edge--指纹浏览器插件安装与配置详解)
12. [Playwright / Puppeteer / Selenium 自动化集成指南](#12-playwright--puppeteer--selenium-自动化集成指南)

---

## 1. 快速开始与接口鉴权规范

### 1.1 鉴权方式
在 NovaCaptcha 开发者控制台注册并登录后，您将获得一枚专属密钥（格式为 `ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`）。所有 API 请求均采用 `POST` 方法，请求头为 `Content-Type: application/json`，并在 JSON 根节点携带 `clientKey`。

### 1.2 核心接口端点
| 接口路径 | 方法 | 说明 | 推荐超时时间 |
| :--- | :--- | :--- | :--- |
| `/createTask` | `POST` | 创建并执行识别或协议过盾任务（支持同步直出 `solution`） | 图像分类 `15s` / 协议过盾 `120s` |
| `/getTaskResult` | `POST` | 根据 `taskId` 查询异步任务状态与结果 | `15s` |
| `/getBalance` | `POST` | 查询当前账户剩余可用点数与折合额度 | `10s` |

### 1.3 通用返回格式
```json
{
  "errorId": 0,
  "taskId": "rv2-1794368123456",
  "status": "ready",
  "solution": {
    "gRecaptchaResponse": "03AFcWeA...",
    "token": "03AFcWeA..."
  }
}
```
- 当 `errorId == 0` 且 `status == "ready"` 时，`solution` 字段内即为您所需的验证 Token 或图像识别坐标结果。
- 当 `errorId != 0` 时，任务未成功，**系统不会扣除任何点数**，具体原因可查看 `errorCode` 与 `errorDescription`。

---

## 2. Google reCAPTCHA v2 标准版 / Invisible 隐形版过盾

- **任务类型 (`task.type`)**：`ReCaptchaV2TaskProxyless`
- **单次消耗**：`15 点 / 次`（折合 `$0.00214`）
- **平均耗时**：`2.8s ~ 4.6s`（实测一次通过率 `99.5%`）

### 2.1 请求参数说明
| 字段名 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| `clientKey` | `string` | 是 | 您的开发者密钥 `ak_live_...` |
| `task.type` | `string` | 是 | 固定填 `ReCaptchaV2TaskProxyless` |
| `task.websiteURL` | `string` | 是 | 触发验证码的目标网页完整地址 |
| `task.websiteKey` | `string` | 是 | 目标网页中的 `data-sitekey` 属性或 iframe URL 中的 `k=` 参数 |
| `task.isInvisible` | `boolean` | 否 | 是否为无复选框的 Invisible 隐形版 reCAPTCHA v2，默认 `false` |
| `task.proxy` | `string` | 否 | 可选自定义代理（格式 `http://user:pass@ip:port`），不传则自动使用平台高匿住宅代理池 |

### 2.2 Python 完整调用示例
```python
import requests

API_BASE = "https://your-domain.com"
CLIENT_KEY = "ak_live_YOUR_CLIENT_KEY"

payload = {
    "clientKey": CLIENT_KEY,
    "task": {
        "type": "ReCaptchaV2TaskProxyless",
        "websiteURL": "https://www.google.com/recaptcha/api2/demo",
        "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
    }
}

resp = requests.post(f"{API_BASE}/createTask", json=payload, timeout=120).json()
if resp.get("errorId") == 0 and resp.get("status") == "ready":
    token = resp["solution"]["gRecaptchaResponse"]
    print("过盾成功 gRecaptchaResponse:", token)
else:
    print("过盾失败:", resp)
```

### 2.3 拿到 Token 后如何在网页中提交？
```javascript
// 1. 将返回的 gRecaptchaResponse 填入隐藏 textarea
document.querySelector('#g-recaptcha-response').value = token;
// 2. 如果目标网站绑定了 data-callback 回调函数，可直接触发或点击提交按钮
document.querySelector('form').submit();
```

---

## 3. Google reCAPTCHA v2 Enterprise 企业版过盾

- **任务类型 (`task.type`)**：`RecaptchaV2EnterpriseTaskProxyless`
- **单次消耗**：`20 点 / 次`

### 请求示例
```json
{
  "clientKey": "ak_live_YOUR_CLIENT_KEY",
  "task": {
    "type": "RecaptchaV2EnterpriseTaskProxyless",
    "websiteURL": "https://store.steampowered.com/join",
    "websiteKey": "6LdIFr0ZAAAAAO3vz0O0OQGW82s61n237_Qa_2p7",
    "enterprisePayload": {
      "s": "OPTIONAL_S_TOKEN_FROM_PAGE"
    }
  }
}
```

---

## 4. Google reCAPTCHA v3 无感高分 Token

- **任务类型 (`task.type`)**：`RecaptchaV3TaskProxyless`
- **单次消耗**：`15 点 / 次`

### 请求参数说明
| 字段名 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| `task.type` | `string` | 是 | 固定填 `RecaptchaV3TaskProxyless` |
| `task.websiteURL` | `string` | 是 | 目标网页完整 URL |
| `task.websiteKey` | `string` | 是 | reCAPTCHA v3 的 SiteKey |
| `task.pageAction` | `string` | 否 | 页面调用 `grecaptcha.execute(key, {action: '...'})` 时的 action 值（如 `login`、`verify`） |
| `task.minScore` | `number` | 否 | 期望最低分数，支持 `0.3`、`0.7`、`0.9`，默认 `0.7` |

---

## 5. Cloudflare Turnstile 挑战过盾

- **任务类型 (`task.type`)**：`TurnstileTaskProxyless`
- **单次消耗**：`15 点 / 次`
- **平均耗时**：`1.8s ~ 2.9s`（实测通过率 `99.8%`）

### 5.1 请求参数说明
| 字段名 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| `task.type` | `string` | 是 | 固定填 `TurnstileTaskProxyless` |
| `task.websiteURL` | `string` | 是 | 目标网页完整 URL |
| `task.websiteKey` | `string` | 是 | Turnstile 组件的 `data-sitekey`（形如 `0x4AAAAAAA...`） |
| `task.action` | `string` | 否 | 可选，对应 `turnstile.render` 中的 `action` 字段 |
| `task.cData` | `string` | 否 | 可选，对应 `turnstile.render` 中的 `cData` 字段 |

### 5.2 Node.js 调用示例
```javascript
const response = await fetch("https://your-domain.com/createTask", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    clientKey: "ak_live_YOUR_CLIENT_KEY",
    task: {
      type: "TurnstileTaskProxyless",
      websiteURL: "https://peet.ws/turnstile-test/non-interactive.html",
      websiteKey: "0x4AAAAAAABS7vwvV6VFfMcD"
    }
  })
});
const data = await response.json();
console.log("Turnstile Token:", data.solution.token);
```

---

## 6. 九宫格 3x3 / 4x4 / 1x1 动态补图图像分类

- **任务类型 (`task.type`)**：`HCaptchaClassification`
- **单次消耗**：`2 点 / 次`（`1 USDT = 3,500 次调用`）
- **平均耗时**：`0.08s ~ 0.45s`（一次准确率 `99.7%`）

### 6.1 请求参数详解
| 字段名 | 类型 | 必填 | 描述 |
| :--- | :--- | :--- | :--- |
| `task.type` | `string` | 是 | 填 `HCaptchaClassification` |
| `task.queries` | `array[string]` | 是 | 图像 Base64 字符串数组（不含 `data:image/jpeg;base64,` 前缀或含前缀均可自动解析）。既可传入 1 张 300×300 / 450×450 九宫格整图，也可传入多张 100×100 动态替换单图。 |
| `task.question` | `string` | 是 | 题目提示语，支持英文或中文（如 `"Select all images with crosswalks"`、`"traffic lights"`、`"人行横道"`） |
| `task.grid` | `string` | 否 | 显式指定网格规格：`"3x3"`（9格）、`"4x4"`（16格）或 `"1x1"`（动态补图单张判断）。不传时系统自动识别。 |

### 6.2 请求与返回示例
```json
// 请求报文
{
  "clientKey": "ak_live_YOUR_CLIENT_KEY",
  "task": {
    "type": "HCaptchaClassification",
    "queries": ["/9j/4AAQSkZJRgABAQAAAQABAAD..."],
    "question": "Select all squares with motorcycles",
    "grid": "3x3"
  }
}

// 响应报文
{
  "errorId": 0,
  "taskId": "vis-1794368991",
  "status": "ready",
  "solution": {
    "objects": [false, true, false, false, true, true, false, false, false],
    "indices": [1, 4, 5]
  }
}
```
- `solution.objects`：长度为 9（3x3）或 16（4x4）的布尔数组，`true` 代表该位置格子需要点击。
- `solution.indices`：需要点击的格子下标数组（从 `0` 开始计数，左上角为 `0`，右下角为 `8` 或 `15`）。

---

## 7. Arkose Labs FunCaptcha 协议过盾与 6/10 宫格识图

### 7.1 6 宫格 / 10 宫格图像识别 (`FunCaptchaClassification` · 3点/次)
```json
{
  "clientKey": "ak_live_YOUR_CLIENT_KEY",
  "task": {
    "type": "FunCaptchaClassification",
    "image": "BASE64_ENCODED_SPRITE_IMAGE",
    "question": "Pick the dice pair with the same top side"
  }
}
```
返回 `solution.objects` 为命中子图的 0-based 索引数组（如 `[2]` 代表点击第 3 张图）。

### 7.2 完整协议过盾拿 Token (`FunCaptchaTaskProxyless` · 20点/次)
```json
{
  "clientKey": "ak_live_YOUR_CLIENT_KEY",
  "task": {
    "type": "FunCaptchaTaskProxyless",
    "websiteURL": "https://www.roblox.com",
    "websitePublicKey": "A2A14B1D-1AF3-C791-9BBC-EE33CC7A0A6F",
    "funcaptchaApiJSSubdomain": "https://roblox-api.arkoselabs.com",
    "data": "{\"blob\":\"YOUR_DATA_BLOB_STRING\"}"
  }
}
```

---

## 8. 通用英数 / 算术图文验证码 OCR

- **任务类型 (`task.type`)**：`ImageToTextTask`
- **单次消耗**：`1 点 / 次`（`1 USDT = 7,000 次调用`）

```json
// 请求
{
  "clientKey": "ak_live_YOUR_CLIENT_KEY",
  "task": {
    "type": "ImageToTextTask",
    "body": "BASE64_IMAGE_STRING"
  }
}

// 响应
{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "text": "8k3m9"
  }
}
```

---

## 9. 极验 GeeTest v3/v4 与 Amazon AWS WAF 过盾

### 9.1 GeeTest v3 / v4 (`GeeTestTaskProxyless` · 15点/次)
```json
{
  "clientKey": "ak_live_YOUR_CLIENT_KEY",
  "task": {
    "type": "GeeTestTaskProxyless",
    "websiteURL": "https://example.com/login",
    "gt": "022397c99c9f646f6477822485f30404",
    "challenge": "1234567890abcdef1234567890abcdef",
    "version": 3
  }
}
```

---

## 10. 账户余额查询与完整错误码字典

### 10.1 查询余额 (`POST /getBalance`)
```bash
curl -X POST "https://your-domain.com/getBalance" \
  -H "Content-Type: application/json" \
  -d '{"clientKey": "ak_live_YOUR_CLIENT_KEY"}'
```
返回：
```json
{
  "errorId": 0,
  "balance": 7000,
  "balanceUSD": 1.0,
  "email": "developer@example.com"
}
```

### 10.2 标准错误码字典
| 错误码 (`errorCode`) | 是否扣费 | 原因说明与处理建议 |
| :--- | :--- | :--- |
| `ERROR_KEY_DOES_NOT_EXIST` | 否 | `clientKey` 不存在或已重置，请前往用户控制台复制最新密钥 |
| `ERROR_KEY_OR_BALANCE` | 否 | 账户可用点数不足以支付当前题型，请通过 USDT 或 CDK 充值 |
| `ERROR_CAPTCHA_UNSOLVABLE` | 否 | 目标站点响应超时或挑战刷新失败，直接重新发起请求即可 |
| `ERROR_VISION_NODE_UNREACHABLE` | 否 | 视觉推理节点瞬时繁忙，建议间隔 1 秒自动重试 |

---

## 11. Chrome / Edge / 指纹浏览器插件安装与配置详解

1. **下载与解压**：在网站导航栏进入「浏览器插件」页面，下载 `novacaptcha_extension.zip` 并解压到本地固定目录。
2. **Chrome / Edge 手动加载**：
   - 打开 `chrome://extensions/`，开启右上角 **「开发者模式」**。
   - 点击左上角 **「加载已解压的扩展程序」**，选择解压后的文件夹。
   - 点击插件图标，填入服务端 **API 网关地址** 与您的 **`ClientKey`**，点击保存。
3. **AdsPower / 比特浏览器 (BitBrowser) 批量部署**：
   - 在指纹浏览器后台进入「应用中心 / 扩展管理」→「上传自定义扩展」，上传插件包并设为全局自动启用，所有新建浏览器环境即可免配置全自动过盾。

---

## 12. Playwright / Puppeteer / Selenium 自动化集成指南

### 12.1 Python Playwright 自动加载插件并注入配置
```python
from playwright.sync_api import sync_playwright

EXT_DIR = "/absolute/path/to/novacaptcha_extension"

with sync_playwright() as p:
    context = p.chromium.launch_persistent_context(
        user_data_dir="/tmp/pw_novacaptcha_profile",
        headless=False,
        args=[
            f"--disable-extensions-except={EXT_DIR}",
            f"--load-extension={EXT_DIR}",
            "--no-sandbox",
        ],
    )
    page = context.new_page()
    page.goto("https://www.google.com/recaptcha/api2/demo")
    # 插件将自动点击复选框、识别九宫格与动态补图，等待 g-recaptcha-response 生成即可
    page.wait_for_function(
        "() => document.querySelector('#g-recaptcha-response')?.value?.length > 100",
        timeout=60000
    )
    token = page.eval_on_selector("#g-recaptcha-response", "el => el.value")
    print("插件自动过盾完成，Token 长度:", len(token))
    context.close()
```

### 12.2 Node.js Puppeteer 自动加载插件
```javascript
const puppeteer = require('puppeteer');
const path = require('path');

(async () => {
  const extPath = path.resolve('./novacaptcha_extension');
  const browser = await puppeteer.launch({
    headless: false,
    args: [
      `--disable-extensions-except=${extPath}`,
      `--load-extension=${extPath}`,
      '--no-sandbox'
    ]
  });
  const page = await browser.newPage();
  await page.goto('https://www.google.com/recaptcha/api2/demo', { waitUntil: 'networkidle2' });
})();
```