验证码识别

NexCaptcha 验证码识别的产品与价格、产品参数模型、识别任务提交、任务记录与结果查询。提交任务只传产品编码与 adapter，由服务端按当前价格预扣费用；失败或过期的任务由服务端自动退款。

推荐流程：/captcha/products 选产品 → /captcha/schema 读取参数要求 → /captcha/buy 提交 → /captcha/query 轮询到终态。页面内的验证码可配合自动化动作中的 captchaInspect、captchaApply 采集参数与回填答案。业务接口的公共约定见服务与鉴权。

通过 MCP 处理页面验证码时，先免费调用 nex_browser_captcha_prepare 准备挑战，再仅传 prepareId 调用 nex_browser_captcha_submit 直接扣费，并用同一 ID 调用 nex_browser_captcha_complete。网格验证码后续轮次返回 nextPrepareId 与 nextPreparation，按需提交新的准备结果，无需报价或费用确认。

Grid 正常续轮不是识别失败；按返回的续作信息继续，避免重复提交。确认任务失败、过期或站点拒绝答案后，可核对原任务与账单，取得新挑战后自动重试，交互流程默认含首次最多 3 次；新付费提交计入次数。扣费或任务结果未知时只查询原记录，未核清不重复购买；余额不足停止后续付费。

在本页搜索

显示 5 / 5 个接口

GET/captcha/products

识别产品列表

列出当前启用的验证码识别产品与单次价格，productCode 用于读取参数模型和提交任务。

鉴权Bearer API Key

请求参数

无参数

注意事项

price 不需要再乘倍率或舍入。
提交任务前请先调用 /captcha/schema 读取该产品的参数要求。

响应字段

字段	类型	说明
`contextId`	`string`	本次请求的登录与团队上下文标识，可作为后续请求的 X-Nex-Service-Context
`data`	`object[]`	产品列表
`data[].productCode`	`string`	产品编码，区分大小写
`data[].name`	`string`	产品名称
`data[].description`	`string`	产品说明
`data[].price`	`number`	单次价格，USDT，已由服务端向上保留 3 位；实际扣费由服务端核算
`data[].iconBase64`	`string`	产品图标，可为 null
`data[].sortOrder`	`number`	排序值

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": [
    {
      "productCode": "RECAPTCHA_V2",
      "name": "reCAPTCHA v2",
      "description": "产品描述",
      "price": 0.005,
      "iconBase64": null,
      "sortOrder": 2
    }
  ],
  "contextId": "a3f5c2e1b7d94c0e8f6a1b2c3d4e5f60a3f5c2e1b7d94c0e8f6a1b2c3d4e5f6"
}

POST/captcha/schema

读取产品参数模型

读取产品当前的 adapter 参数 Schema、示例、结果契约与接入流程说明；免费，不创建任务。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
`productCode`	`string`	必填	产品编码，必须与 /captcha/products 完全一致，大小写和空格原样保留

注意事项

productCode 为空或纯空白返回 -1100；上游不识别的产品返回服务端错误码并保留原文 msg。
说明文案按 Accept-Language 返回，参数名与 Schema 原始描述不保证翻译。

响应字段

字段	类型	说明
`contextId`	`string`	本次请求的登录与团队上下文标识，可作为后续请求的 X-Nex-Service-Context
`data.productCode`	`string`	产品编码
`data.schema`	`object`	adapter 的 JSON Schema，包含 required、oneOf、取值与额外字段等约束
`data.example`	`object`	最小占位示例，必须替换为目标页面的真实参数
`data.integration`	`object`	适用流程、输入来源、结果类型 resultSchema 与限制
`data.integration.readiness`	`string`	接入状态；DOCUMENTATION_REQUIRED 表示文档未完善，不能据此创建付费任务
`data.integration.workflows`	`string[]`	允许的流程，如 HTTP_SUBMIT、BROWSER_RESULT、BROWSER_INTERACTION
`data.workflowGuide`	`object`	通用流程、完成阶段与失败处理指引

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "productCode": "RECAPTCHA_V2",
    "schema": {
      "type": "object",
      "required": [
        "websiteURL",
        "websiteKey"
      ],
      "properties": {
        "websiteURL": {
          "type": "string"
        },
        "websiteKey": {
          "type": "string"
        }
      }
    },
    "example": {
      "websiteURL": "https://example.com/register",
      "websiteKey": "<site-key>"
    },
    "integration": {
      "readiness": "READY",
      "workflows": [
        "HTTP_SUBMIT",
        "BROWSER_RESULT"
      ],
      "resultKind": "TOKEN",
      "resultSchema": {
        "type": "object"
      }
    },
    "workflowGuide": {}
  },
  "contextId": "a3f5c2e1b7d94c0e8f6a1b2c3d4e5f60a3f5c2e1b7d94c0e8f6a1b2c3d4e5f6"
}

POST/captcha/buy

提交识别任务

按产品与 adapter 参数创建异步识别任务并预扣一次费用；创建成功不代表已识别成功。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
`productCode`	`string`	必填	产品编码，取自 /captcha/products
`adapter`	`object`	必填	产品参数对象，按 /captcha/schema 的 schema 填写真实挑战参数；部分产品允许 {}，但不能省略或传 null

注意事项

业务参数校验后直接提交一次，由服务端按当前价格核算并扣费；客户端不预查价格、库存或套餐，权限与余额由服务端校验。
提交后不自动重试；超时或结果不明时先查 /captcha/records 与 /billing/trades 核对，不要重复购买。
同一登录与团队下参数完全相同的购买仍在处理中时返回 -1100；未选择团队时同样返回 -1100。
费用由服务端按当前价格核算；adapter 不会存入任务记录，也不会回显。
本接口只创建识别任务，不会替你向目标网站提交答案。

响应字段

字段	类型	说明
`contextId`	`string`	本次请求的登录与团队上下文标识，可作为后续请求的 X-Nex-Service-Context
`data`	`object`	新建的任务记录，state 初始为 CREATED
`data.id`	`number`	本地任务 ID，查询时使用
`data.userId`	`number`	提交用户 ID
`data.teamId`	`number`	提交时所在团队 ID
`data.taskId`	`string`	上游任务 ID，不作为查询参数
`data.productCode`	`string`	产品编码
`data.price`	`number`	实际预扣金额，退款后保持原值
`data.product`	`string`	提交时产品快照的 JSON 文本
`data.state`	`string`	状态：CREATED、SUBMITTING、PROCESSING、SUCCEEDED、FAILED、EXPIRED
`data.solution`	`string`	识别答案对象的 JSON 文本，可能含 text、token 或产品专属字段
`data.createdAt`	`string`	创建时间
`data.updatedAt`	`string`	更新时间

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "id": 101,
    "userId": 1001,
    "teamId": 2001,
    "taskId": "upstream-task-7f3a",
    "productCode": "RECAPTCHA_V2",
    "price": 0.005,
    "product": "{\"productCode\":\"RECAPTCHA_V2\",\"name\":\"reCAPTCHA v2\",\"price\":0.005}",
    "state": "CREATED",
    "solution": "{}",
    "createdAt": "2026-10-23 10:00:00",
    "updatedAt": "2026-10-23 10:00:00"
  },
  "contextId": "a3f5c2e1b7d94c0e8f6a1b2c3d4e5f60a3f5c2e1b7d94c0e8f6a1b2c3d4e5f6"
}

GET/captcha/records

识别任务记录

分页查询当前用户在当前团队下的识别任务，包含全部状态。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
`page`	`number`	可选	页码，默认 1
`size`	`number`	可选	每页数量，默认 20，上限 1000
`keyword`	`string`	可选	关键词，模糊匹配 productCode

注意事项

按本地 ID 倒序返回；退款后 price 仍是原预扣金额，退款流水见 /billing/trades。

响应字段

字段	类型	说明
`contextId`	`string`	本次请求的登录与团队上下文标识，可作为后续请求的 X-Nex-Service-Context
`data.count`	`number`	匹配到的总条数
`data.size`	`number`	每页数量，回显请求值
`data.page`	`number`	当前页码，回显请求值
`data.total`	`number`	总页数
`data.data`	`object[]`	当前页记录
`data.data[].id`	`number`	本地任务 ID，查询时使用
`data.data[].userId`	`number`	提交用户 ID
`data.data[].teamId`	`number`	提交时所在团队 ID
`data.data[].taskId`	`string`	上游任务 ID，不作为查询参数
`data.data[].productCode`	`string`	产品编码
`data.data[].price`	`number`	实际预扣金额，退款后保持原值
`data.data[].product`	`string`	提交时产品快照的 JSON 文本
`data.data[].state`	`string`	状态：CREATED、SUBMITTING、PROCESSING、SUCCEEDED、FAILED、EXPIRED
`data.data[].solution`	`string`	识别答案对象的 JSON 文本，可能含 text、token 或产品专属字段
`data.data[].createdAt`	`string`	创建时间
`data.data[].updatedAt`	`string`	更新时间

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "count": 1,
    "size": 20,
    "page": 1,
    "total": 1,
    "data": [
      {
        "id": 101,
        "userId": 1001,
        "teamId": 2001,
        "taskId": "upstream-task-7f3a",
        "productCode": "RECAPTCHA_V2",
        "price": 0.005,
        "product": "{\"productCode\":\"RECAPTCHA_V2\",\"name\":\"reCAPTCHA v2\",\"price\":0.005}",
        "state": "SUCCEEDED",
        "solution": "{\"token\":\"03AFcWeA...\"}",
        "createdAt": "2026-10-23 10:00:00",
        "updatedAt": "2026-10-23 10:00:00"
      }
    ]
  },
  "contextId": "a3f5c2e1b7d94c0e8f6a1b2c3d4e5f60a3f5c2e1b7d94c0e8f6a1b2c3d4e5f6"
}

POST/captcha/query

查询识别结果

查询单个本地任务的进度与答案，非终态时服务端会向上游刷新。

鉴权Bearer API Key

请求参数

字段	类型	是否必填	说明
`id`	`number`	必填	本地任务 ID，不是上游 taskId

注意事项

建议每 3 到 5 秒查询一次，SUCCEEDED、FAILED、EXPIRED 为终态，到达后停止轮询；每用户 3 秒最多 5 次。
FAILED 与 EXPIRED 由服务端自动按原价退款；网络错误或未知状态不等于失败，也不会退款。没有取消或手动退款接口。
不存在、非本人或非当前团队的任务返回 -1005。

响应字段

字段	类型	说明
`contextId`	`string`	本次请求的登录与团队上下文标识，可作为后续请求的 X-Nex-Service-Context
`data`	`object`	更新后的任务记录
`data.id`	`number`	本地任务 ID，查询时使用
`data.userId`	`number`	提交用户 ID
`data.teamId`	`number`	提交时所在团队 ID
`data.taskId`	`string`	上游任务 ID，不作为查询参数
`data.productCode`	`string`	产品编码
`data.price`	`number`	实际预扣金额，退款后保持原值
`data.product`	`string`	提交时产品快照的 JSON 文本
`data.state`	`string`	状态：CREATED、SUBMITTING、PROCESSING、SUCCEEDED、FAILED、EXPIRED
`data.solution`	`string`	识别答案对象的 JSON 文本，可能含 text、token 或产品专属字段
`data.createdAt`	`string`	创建时间
`data.updatedAt`	`string`	更新时间

响应示例

{
  "code": 0,
  "msg": "成功",
  "data": {
    "id": 101,
    "userId": 1001,
    "teamId": 2001,
    "taskId": "upstream-task-7f3a",
    "productCode": "RECAPTCHA_V2",
    "price": 0.005,
    "product": "{\"productCode\":\"RECAPTCHA_V2\",\"name\":\"reCAPTCHA v2\",\"price\":0.005}",
    "state": "SUCCEEDED",
    "solution": "{\"token\":\"03AFcWeA...\"}",
    "createdAt": "2026-10-23 10:00:00",
    "updatedAt": "2026-10-23 10:00:12"
  },
  "contextId": "a3f5c2e1b7d94c0e8f6a1b2c3d4e5f60a3f5c2e1b7d94c0e8f6a1b2c3d4e5f6"
}