SolveHub
简体中文

验证码类型 · perimeterx

PerimeterX（HUMAN）识别 API：获取 _px3 Cookie

通过 SolveHub API 处理 PerimeterX / HUMAN 人机验证：应用 ID、目标站点、代理与浏览器 Cookie。了解需要提交的字段以及如何使用返回的 Cookie。

适用于授权自动化测试、风控 QA 与浏览器集成。请仅在有权测试的站点和业务流程中使用。

创建此类任务：向 POST /v1/tasks 发送下方 JSON，附带 Authorization: Bearer <API_KEY>、Content-Type: application/json 与 Idempotency-Key。先在实时价格确认该类型可用；完整创建与查询流程见快速开始。

必填页面地址 websiteURL、PerimeterX 应用 ID websiteKey（pxAppId）及 HTTP 代理。可选 useragent。不要把页面出现的 UUID 或访客 ID 代替应用 ID。

请求字段

外层 type 和 task 必填；以下 task.* 路径均位于 task 对象内。字段名区分大小写。长度限制按 UTF-8 字节计算。

字段 类型 必填 限制 说明
type 字符串 是 固定为 perimeterx 平台任务类型。
task JSON 对象 是 ≤ 7 MiB 此类型的任务参数。
task.type 字符串 否 如提供必须为 perimeterx 兼容旧请求格式；新接入可省略。
task.websiteURL HTTP(S) URL 是 ≤ 2048 字节 需要解题的目标页面完整 URL，不含账号密码。
task.websiteKey 字符串 是 ≤ 256 字节 PerimeterX 应用 ID，即 pxAppId；访客 UUID/vid 不能替代。
task.useragent 字符串 否 ≤ 512 字节 自定义浏览器 User-Agent；后续请求优先使用实际返回的 solution.useragent。
task.proxyType 字符串 是 仅 http 代理协议；提供时必须为 http。
task.proxyAddress 字符串 是 ≤ 256 字节 代理 IP 或主机名，必须与 proxyPort 同时提供。
task.proxyPort 字符串 是 1–5 字节，数值 1–65535 代理端口，必须为带引号的数字字符串。
task.proxyLogin 字符串 否 ≤ 256 字节 代理需要认证时填写用户名；不得单独提供而不填地址与端口。
task.proxyPassword 字符串 否 ≤ 256 字节 代理需要认证时填写密码；不得单独提供而不填地址与端口。

创建请求示例

{
  "type": "perimeterx",
  "task": {
    "websiteURL": "https://example.com/protected",
    "websiteKey": "PX_EXAMPLE_APP_ID",
    "proxyType": "http",
    "proxyAddress": "203.0.113.10",
    "proxyPort": "8080"
  }
}

cURL 调用

把示例中的 Key、站点信息与代理替换为你的实际值；Idempotency-Key 对同一次业务请求保持不变。

curl -sS -X POST 'https://www.tiam.codes/v1/tasks' \
  -H 'Authorization: Bearer sh_REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-perimeterx-0001' \
  --data-binary @- <<'JSON'
{
  "type": "perimeterx",
  "task": {
    "websiteURL": "https://example.com/protected",
    "websiteKey": "PX_EXAMPLE_APP_ID",
    "proxyType": "http",
    "proxyAddress": "203.0.113.10",
    "proxyPort": "8080"
  }
}
JSON

创建响应与查询

创建成功返回 HTTP 202，status 初始通常为 queued。保存 taskId，每约 2–3 秒调用 GET /v1/tasks/{taskId} 查询。本类型处理软时限为 210 秒；超过软时限可能进入 uncertain，有已受理任务的结果可继续核对，客户端不要用新幂等键盲目重建。

结果字段

只在 status=completed 时读取 solution；下表列出常用字段，实际字段以该任务响应为准。

字段 类型 读取方式
solution.cookies 对象 浏览器会话 Cookie；名称由目标页面决定，可含 _px3、_pxvid、_pxhd。
solution.useragent 字符串 后续请求与相同代理一起复用的 User-Agent。
solution.value 字符串，可选 有些结果会给空字符串，不能代替 Cookie 判断成功。

结果以 solution.cookies 和 solution.useragent 为主；Cookie 名称随目标站配置变化，可能包含 _px3、_pxvid。结果示意：{"cookies":{"_px3":"EXAMPLE_COOKIE"},"useragent":"Mozilla/5.0 ..."}。后续请求应复用解题代理和返回的 User-Agent。

完成响应示例（平台字段与结果分开；价格与时间仅为示意）：

{
  "taskId": "00000000-0000-4000-8000-000000000001",
  "type": "perimeterx",
  "status": "completed",
  "priceMicros": 1000,
  "traceId": "00000000-0000-4000-8000-000000000002",
  "solution": {
    "value": "",
    "cookies": {
      "_px3": "EXAMPLE_COOKIE",
      "_pxvid": "EXAMPLE_VISITOR"
    },
    "useragent": "Mozilla/5.0 ..."
  },
  "createdAt": "2026-10-05T00:00:00Z",
  "finishedAt": "2026-10-05T00:00:30Z"
}

Python 创建并查询

示例使用 requests。把占位站点、代理和环境变量替换为实际值；创建请求网络异常时应使用同一幂等键与同一请求体重试，不能换键。任务进入 uncertain 时保留 taskId 继续查询或联系客服。

import os
import time
import requests

base = os.environ["SOLVEHUB_URL"].rstrip("/")
headers = {
    "Authorization": f"Bearer {os.environ['SOLVEHUB_API_KEY']}",
    "Idempotency-Key": "your-business-request-perimeterx-001",
}
payload = {
    "type": "perimeterx",
    "task": {
        "websiteURL": "https://example.com/protected",
        "websiteKey": "PX_EXAMPLE_APP_ID",
        "proxyType": "http",
        "proxyAddress": "203.0.113.10",
        "proxyPort": "8080",
    },
}
response = requests.post(f"{base}/v1/tasks", headers=headers, json=payload, timeout=20)
response.raise_for_status()
task_id = response.json()["taskId"]

deadline = time.monotonic() + 15 * 60
while time.monotonic() < deadline:
    response = requests.get(f"{base}/v1/tasks/{task_id}", headers=headers, timeout=20)
    response.raise_for_status()
    task = response.json()
    if task["status"] == "completed":
        solution = task["solution"]
        print(solution.get("cookies", {}), solution.get("useragent"))
        break
    if task["status"] in ("failed", "cancelled"):
        raise RuntimeError(task.get("errorCode", task["status"]))
    if task["status"] == "uncertain":
        print("任务待核对：", task_id)
        break
    time.sleep(3)
else:
    print("已到本地轮询时限，请稍后继续查询原任务：", task_id)

失败与排查

websiteKey 必须是应用 ID pxAppId；不要提交访客 UUID/vid。proxyPort 是字符串。后续访问复用同一代理、完整 Cookie 集和 solution.useragent。

创建请求常见错误为 400 INVALID_TASK、402 INSUFFICIENT_BALANCE、429 TASK_LIMIT_EXCEEDED 和 503 TYPE_UNAVAILABLE。已创建任务失败时公开错误码为 TASK_FAILED 或 TASK_TIMEOUT；uncertain 对应 TASK_UNCERTAIN。详见 平台 API 参考。

常见问题

  • websiteKey 应填什么？ 填目标站的 PerimeterX 应用 ID pxAppId。页面访客 UUID 和 vid 都不能替代它。
  • 可以省略代理吗？ 此类型不可以。proxyType 固定为 http，proxyAddress 与字符串 proxyPort 必须同时提供；只有代理需要认证时才填写 proxyLogin、proxyPassword。
  • 需要 SOCKS5 代理怎么办？ 此类型只接受 HTTP 代理；需要 socks5 时使用 perimeterx_cookies 类型（当前默认关闭，以 GET /v1/prices 为准）。
  • 为什么返回的 Cookie 不能使用？ 先确认提交的是当前目标页面、应用 ID、完整 Cookie 集；后续请求复用解题时的代理出口和返回的 solution.useragent。Cookie 名称由目标页面配置决定，不能只依赖 _px3。

处理窗口从任务确认受理后起算，不扣除已花费的排队时间。解题节点当前约 180 秒超时；平台保留 210 秒软时限以等待网络和轮询结果。

支持的 User-Agent

相关文档

从 cURL 开始接入注册账户

最近更新: