API 教程

如何使用 API 解决 Cloudflare 挑战

自动化 Cloudflare Challenge
作者 CaptchaAI 中文团队
发布时间 Jun 11, 2026
如何使用 API 解决 Cloudflare 挑战
特色图片不可用

Cloudflare 验证流程 是一个全页插页式广告，在允许您访问受保护的网站之前显示“检查您的浏览器...”。与 Cloudflare Turnstile（可嵌入小部件）不同，挑战页面会阻止整个请求，直到您通过为止。 CaptchaAI 解决了这个问题并返回一个 qa_session_cookie cookie，该 cookie 授予对受保护资源的访问权限。

Cloudflare 验证流程 与 CaptchaAI 支持的其他验证码类型不同，存在三个关键要求：

  1. 代理是强制性的 — 求解器必须使用您的代理，以便 qa_session_cookie cookie 绑定到您控制的 IP。
  2. 返回用户代理 — cookie 绑定到特定的用户代理字符串。您必须使用响应中的确切用户代理。
  3. IP + 用户代理必须匹配 — 对受保护站点的所有后续请求都必须使用相同的代理和相同的用户代理。

本指南涵盖了工作 Python、Node.js 和 PHP 代码的完整流程。

寻找 Cloudflare Turnstile 吗？ 这是具有不同方法的不同验证码类型。读如何使用API​​解决Cloudflare Turnstile。

开始之前您需要什么

要求 细节
CaptchaAI API 密钥 从以下位置获取一份captchaai.com/api.php。 32 个字符的字符串。
目标页面网址 Cloudflare 保护页面的完整 URL。
工作代理 HTTP、HTTPS、SOCKS4 或 SOCKS5。代理必须能够到达目标站点。
您的 CaptchaAI 帐户启用代理 默认情况下禁用代理使用。在您第一次请求之前，请联系 CaptchaAI 支持人员启用它。
运行环境 Python 3.7+ 与 requests，或 Node.js 18+ 与内置 fetch。

重要提示： 您的帐户必须启用代理支持，然后才能使用 method=cloudflare_challenge。如果您尚未执行此操作，请先在 CaptchaAI 上开具支持票证。

如何识别Cloudflare 验证流程页面

Cloudflare 验证流程 显示为全页插页式广告，而不是嵌入式小部件。您面临的迹象：

  1. 在加载任何内容之前，页面会显示“正在检查您的浏览器...” 或“请稍等...”。
  2. URL 简要显示目标路径，但会重定向到挑战页面。
  3. 响应标头包括 cf-mitigated: challenge 或响应状态为 403，并带有 Cloudflare Ray ID。
  4. HTML 正文包含 <div id="challenge-body-text"> 或对 /cdn-cgi/challenge-platform/ 的引用。
  5. 通过挑战后，qa_session_cookie cookie 会出现在您的浏览器中。

相反，如果您看到带有复选框或微调器的表单中嵌入了一个小部件，那就是Cloudflare Turnstile— 具有不同解决方法的不同验证码类型。

求解流程

Identify Cloudflare 验证流程 page
              ↓
  POST to in.php
    method=cloudflare_challenge
    pageurl + proxy + proxytype
              ↓
       receive captcha ID
              ↓
     wait 20 seconds
              ↓
  GET res.php (action=get, id=…, json=1)
      ↓                      ↓
 CAPCHA_NOT_READY       status=1
  (wait 5s, retry)           ↓
                  extract qa_session_cookie + user_agent
                             ↓
              set cookie + User-Agent + same proxy
                             ↓
                   access protected page

Python实现

import time
import requests

API_KEY = "YOUR_CAPTCHAAI_API_KEY"
PAGE_URL = "https://example.com/protected-page"
PROXY = "user:password@123.123.123.123:8080"
PROXY_TYPE = "HTTP"

SUBMIT_URL = "https://ocr.captchaai.com/in.php"
RESULT_URL = "https://ocr.captchaai.com/res.php"


def solve_cloudflare_challenge(api_key, pageurl, proxy, proxytype):
    """Solve a Cloudflare 验证流程 and return qa_session_cookie cookie + User-Agent."""

    # Step 1: Submit the task
    submit_resp = requests.post(
        SUBMIT_URL,
        data={
            "key": api_key,
            "method": "cloudflare_challenge",
            "pageurl": pageurl,
            "proxy": proxy,
            "proxytype": proxytype,
            "json": 1,
        },
        timeout=30,
    )
    submit_resp.raise_for_status()
    submit_data = submit_resp.json()

    if submit_data.get("status") != 1:
        raise RuntimeError(f"Submit failed: {submit_data}")

    captcha_id = submit_data["request"]
    print(f"Task created — captcha ID: {captcha_id}")

    # Step 2: Wait before first poll (Cloudflare 验证流程 takes longer)
    time.sleep(20)

    # Step 3: Poll for result
    for _ in range(60):
        result_resp = requests.get(
            RESULT_URL,
            params={
                "key": api_key,
                "action": "get",
                "id": captcha_id,
                "json": 1,
            },
            timeout=30,
        )
        result_resp.raise_for_status()
        result_data = result_resp.json()

        if result_data.get("request") == "CAPCHA_NOT_READY":
            time.sleep(5)
            continue

        if result_data.get("status") == 1:
            return {
                "qa_session_cookie": result_data["result"],
                "user_agent": result_data["user_agent"],
            }

        raise RuntimeError(f"Polling error: {result_data}")

    raise TimeoutError("Cloudflare 验证流程 solve timed out")


# Solve the challenge
solution = solve_cloudflare_challenge(API_KEY, PAGE_URL, PROXY, PROXY_TYPE)
print(f"qa_session_cookie: {solution['qa_session_cookie']}")
print(f"User-Agent: {solution['user_agent']}")

# Step 4: Access the protected page using the SAME proxy and User-Agent
session = requests.Session()
session.headers.update({"User-Agent": solution["user_agent"]})
session.cookies.set("qa_session_cookie", solution["qa_session_cookie"], domain="example.com")

proxies = {
    "http": f"http://{PROXY}",
    "https": f"http://{PROXY}",
}

response = session.get(PAGE_URL, proxies=proxies, timeout=30)
print(f"Status: {response.status_code}")
print(f"Content length: {len(response.text)} chars")

这有什么作用：

  1. 使用 method=cloudflare_challenge、页面 URL 和您的代理向 in.php 提交挑战。
  2. 等待 20 秒，然后每 5 秒轮询一次 res.php。
  3. 接收 qa_session_cookie cookie 值和求解器的用户代理字符串。
  4. 使用相同的代理、cookie 和用户代理向受保护的页面发出请求。

重要： qa_session_cookie cookie 绑定到代理 IP 和用户代理。如果其中任何一个发生更改，Cloudflare 都会拒绝该请求并再次显示质询。

Node.js 实现

const API_KEY = "YOUR_CAPTCHAAI_API_KEY";
const PAGE_URL = "https://example.com/protected-page";
const PROXY = "user:password@123.123.123.123:8080";
const PROXY_TYPE = "HTTP";

const SUBMIT_URL = "https://ocr.captchaai.com/in.php";
const RESULT_URL = "https://ocr.captchaai.com/res.php";

function sleep(ms) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

async function solveCloudflareChallenge(apiKey, pageurl, proxy, proxytype) {
  // Step 1: Submit the task
  const submitResp = await fetch(SUBMIT_URL, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      key: apiKey,
      method: "cloudflare_challenge",
      pageurl: pageurl,
      proxy: proxy,
      proxytype: proxytype,
      json: "1",
    }),
  });

  const submitData = await submitResp.json();
  if (submitData.status !== 1) {
    throw new Error(`Submit failed: ${JSON.stringify(submitData)}`);
  }

  const captchaId = submitData.request;
  console.log(`Task created — captcha ID: ${captchaId}`);

  // Step 2: Wait before first poll
  await sleep(20_000);

  // Step 3: Poll for result
  for (let i = 0; i < 60; i++) {
    const resultResp = await fetch(
      `${RESULT_URL}?${new URLSearchParams({
        key: apiKey,
        action: "get",
        id: captchaId,
        json: "1",
      })}`
    );

    const resultData = await resultResp.json();

    if (resultData.request === "CAPCHA_NOT_READY") {
      await sleep(5_000);
      continue;
    }

    if (resultData.status === 1) {
      return {
        cfClearance: resultData.result,
        userAgent: resultData.user_agent,
      };
    }

    throw new Error(`Polling error: ${JSON.stringify(resultData)}`);
  }

  throw new Error("Cloudflare 验证流程 solve timed out");
}

(async () => {
  const solution = await solveCloudflareChallenge(
    API_KEY,
    PAGE_URL,
    PROXY,
    PROXY_TYPE
  );
  console.log(`qa_session_cookie: ${solution.cfClearance}`);
  console.log(`User-Agent: ${solution.userAgent}`);

  // Step 4: Access protected page with cookie, User-Agent, and same proxy
  // Note: Node.js fetch does not natively support proxies.
  // Use a proxy agent library like undici, https-proxy-agent, or node-fetch with proxy.
  // Example with undici:
  //
  // import { ProxyAgent } from 'undici';
  // const proxyAgent = new ProxyAgent(`http://${PROXY}`);
  //
  // const response = await fetch(PAGE_URL, {
  //   headers: {
  //     'User-Agent': solution.userAgent,
  //     'Cookie': `qa_session_cookie=${solution.cfClearance}`,
  //   },
  //   dispatcher: proxyAgent,
  // });

  console.log("Use the qa_session_cookie cookie and User-Agent with the same proxy for all subsequent requests.");
})();

PHP实现

<?php
$apiKey    = "YOUR_CAPTCHAAI_API_KEY";
$pageUrl   = "https://example.com/protected-page";
$proxy     = "user:password@123.123.123.123:8080";
$proxyType = "HTTP";

// Step 1: Submit the task
$submit = file_get_contents("https://ocr.captchaai.com/in.php?" . http_build_query([
    "key"       => $apiKey,
    "method"    => "cloudflare_challenge",
    "pageurl"   => $pageUrl,
    "proxy"     => $proxy,
    "proxytype" => $proxyType,
    "json"      => 1,
]));

$submitData = json_decode($submit, true);
if ($submitData["status"] !== 1) {
    die("Submit failed: " . $submit);
}

$captchaId = $submitData["request"];
echo "Task created — captcha ID: $captchaId\n";

// Step 2: Wait and poll
sleep(20);

$cfClearance = null;
$userAgent   = null;

for ($i = 0; $i < 60; $i++) {
    $result = file_get_contents("https://ocr.captchaai.com/res.php?" . http_build_query([
        "key"    => $apiKey,
        "action" => "get",
        "id"     => $captchaId,
        "json"   => 1,
    ]));

    $resultData = json_decode($result, true);

    if ($resultData["request"] === "CAPCHA_NOT_READY") {
        sleep(5);
        continue;
    }

    if ($resultData["status"] === 1) {
        $cfClearance = $resultData["result"];
        $userAgent   = $resultData["user_agent"];
        echo "qa_session_cookie: $cfClearance\n";
        echo "User-Agent: $userAgent\n";
        break;
    }

    die("Polling error: " . $result);
}

if (!$cfClearance) {
    die("Solve timed out");
}

// Step 3: Access the protected page
$ch = curl_init($pageUrl);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_PROXY          => "123.123.123.123:8080",
    CURLOPT_PROXYUSERPWD   => "user:password",
    CURLOPT_HTTPHEADER     => ["User-Agent: $userAgent"],
    CURLOPT_COOKIE         => "qa_session_cookie=$cfClearance",
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "Status: $httpCode\n";
echo "Content length: " . strlen($response) . " chars\n";

Cloudflare 验证流程 与 Cloudflare Turnstile

这是两种不同的 Cloudflare 保护，需要不同的解决方法：

Cloudflare 验证流程 Cloudflare Turnstile
它看起来像什么 全页插页式广告（“正在检查您的浏览器……”） 表单上的嵌入式小部件（复选框或微调器）
API方法 cloudflare_challenge turnstile
需要代理吗？ 是——强制 否 — 可选
你得到什么 qa_session_cookie cookie + 用户代理 Turnstile令牌
如何使用结果 对所有请求设置 cookie + User-Agent + 相同的代理 将token 提交表单字段并提交
IP绑定 Cookie与代理IP绑定 Token 不绑定 IP
典型用例 绕过 DDoS 防护门以抓取内容 提交受保护的表单（登录、注册、结账）

如果您看到表单中嵌入了一个小部件，请使用闸机解决指南反而。

常见错误

# 错误 会发生什么 处理方式
1 不提供代理 API拒绝请求 将 proxy 和 proxytype 添加到您的请求中。 Cloudflare 验证流程 必须使用代理。
2 对后续请求使用不同的代理 Cloudflare 拒绝 qa_session_cookie cookie 使用完全相同的代理来解决和访问受保护的页面。
3 使用不同的用户代理 Cloudflare 拒绝请求 使用 API 响应中的 user_agent 值，而不是您自己的用户代理。
4 不使用json=1 响应不包含 user_agent 字段 始终传递 json=1，因此响应包括 result (qa_session_cookie) 和 user_agent。
5 帐户未启用代理 API 返回错误 在发出请求之前，请联系 CaptchaAI 支持人员在您的帐户上启用代理使用。
6 Cookie 已过期 一段时间后再次被阻止访问 qa_session_cookie cookie 过期。当请求开始被阻止时重新解决。典型的使用寿命为 15-30 分钟。
7 旋转栅门令人困惑的挑战 发送方法错误，解决失败 挑战 = 全页插页式广告 = cloudflare_challenge。旋转门 = 嵌入式小部件 = turnstile。

故障排除

ERROR_BAD_PROXY

您提交的代理无法访问或标记为错误。使固定：

  1. 独立测试代理——它能到达目标站点吗？
  2. 尝试不同的代理。
  3. 确保 IP 身份验证代理的格式为 login:password@IP:PORT 或 IP:PORT。

ERROR_PROXY_CONNECTION_FAILED

CaptchaAI 无法通过您的代理加载挑战页面。代理可能暂时关闭或目标站点阻止它。尝试不同的代理。

ERROR_CAPTCHA_UNSOLVABLE

该挑战无法解决。常见原因：

  • 代理太慢或不可靠。
  • 目标站点具有 Cloudflare 之外的额外保护。
  • 使用新的请求和不同的代理重试。

cookie 已过期，或者 Cloudflare 已轮换其挑战。重新解决挑战以获得新鲜饼干。监控您的成功率并在到期前主动重新解决。

响应缺少 user_agent 字段

您的请求中未包含 json=1。如果没有 json=1，响应是纯文本并且不包含用户代理。始终使用 json=1 作为 Cloudflare 验证流程。

检查所有三个要求：

  1. 与所使用的求解器相同的代理。
  2. 来自 user_agent 响应字段的相同用户代理。
  3. Cookie 域与目标站点匹配。

如果这三个都正确并且您仍然收到 403，则 cookie 可能已过期。解决。

对于所有 CaptchaAI 错误代码，请参阅错误处理参考（即将推出）或 API 文档docs.captchaai.com。

为什么CaptchaAI适用于Cloudflare 验证流程

因素 细节
完整的浏览器解决 CaptchaAI 使用真实的浏览器实例通过 Cloudflare JavaScript 挑战
返回您需要的一切 qa_session_cookie cookie + 用户代理在单个响应中
代理支持 适用于 HTTP、HTTPS、SOCKS4 和 SOCKS5 代理
相同的API模式 提交 → 轮询 → 结果流程与所有其他 CaptchaAI 支持的类型相同
定价 基于线程的计划起价为 15/month

完整的可运行示例

需要一个包含环境设置、轮询、重试和错误处理的完整工作项目吗？

请参阅 GitHub 上的完整可运行示例 →

常问问题

Cloudflare 验证流程 页面是什么？

这是使用 Cloudflare 反机器人保护的网站显示的全页插页式广告。该页面显示“正在检查您的浏览器...”或“请稍等...”并阻止访问，直到浏览器通过 JavaScript 质询、特征检查或 Turnstile 小部件。

对于 Cloudflare 验证流程，API 返回什么？

两个值：(1) qa_session_cookie — 授予受保护站点访问权限的 cookie，(2) user_agent — 求解器使用的确切用户代理字符串。两者都必须包含在您后续的请求中。

为什么需要代理？

Cloudflare 将 qa_session_cookie cookie 绑定到解决挑战的 IP 地址。如果您从 CaptchaAI 的 IP 解析，但随后从您自己的 IP 访问该站点，则 cookie 会被拒绝。通过提供您自己的代理，求解器将使用您的 IP，并且 cookie 通过该代理处理您的所有请求。

通常为 15-30 分钟，但因地点而异。有些网站设置了更长的过期时间。监控您的请求并在您再次开始收到 403 响应时重新解决。

我可以在没有代理的情况下解决 Cloudflare 验证流程 问题吗？

否。此验证码类型必须使用代理。 CaptchaAI 需要它，因为 Cloudflare 强制求解器和后续请求之间的 IP 一致性。

Cloudflare 验证流程 和Turnstile有什么区别？

挑战是阻止所有访问的整页插页式广告。 Turnstile 是特定表单上的嵌入式小部件。它们使用不同的 API 方法（cloudflare_challenge 与 turnstile），Challenge 需要代理，而 Turnstile 不需要。请参阅上方的对照表了解更多。

开始解决Cloudflare 验证流程

  1. 启用代理支持 — 如果尚未启用，请联系 CaptchaAI 支持
  2. 获取您的 API 密钥 —captchaai.com/api.php
  3. 准备代理 — HTTP/HTTPS/SOCKS4/SOCKS5，必须能够到达目标站点
  4. 复制上面的 Python、Node.js 或 PHP 代码 — 将占位符替换为您的密钥、URL 和代理
  5. 对所有后续请求使用返回的 qa_session_cookie + User-Agent + 相同代理

如果您遇到问题，请检查上方的故障排除部分，或完整的Cloudflare 验证流程 错误和修复指导。

相关文章

该文章已禁用评论。