Печать

Пожалуйста, войдите или зарегистрируйтесь.
1 час 1 день 1 неделя 1 месяц Навсегда

[omocaptchaHem]

Cloudflare Turnstile识别：API接入指南

Cloudflare Turnstile识别的核心，其实就是拿到一个 cf-turnstile-response token 并回填到目标表单里。本文用 OMOCaptcha 的 API V2 演示完整流程：读取页面上的 Turnstile sitekey（以 0x... 开头）和页面 URL，调用 createTask 创建任务，再轮询 getTaskResult 取出 token。全程附带可直接复制运行的 Python 与 Node.js 代码，帮你在自动化测试、监控等合法场景中完成 turnstile 识别。

什么是 Cloudflare Turnstile

Turnstile 是 Cloudflare 推出的隐私优先、通常无感（invisible）的人机验证组件，用来替代传统 CAPTCHA。它在后台评估浏览器信号，多数情况下无需用户点击图片或拼图，只在必要时弹出交互挑战。你可以在 Cloudflare 官方文档 (https://developers.cloudflare.com/turnstile/) 查阅其嵌入方式。

需要特别区分两个概念：

- Turnstile token：页面里 <div class="cf-turnstile" data-sitekey="0x..."> 组件生成的一次性凭证，表单提交时通过隐藏字段 cf-turnstile-response 上送，服务端用 siteverify 校验。本文讲的 cloudflare 验证码识别，指的就是获取这个 token。
- Cloudflare 全站拦截挑战（interstitial challenge）：那是站点级的 WAF 拦截页，产出的是 cf_clearance 之类的挑战 Cookie，属于另一套机制，和 Turnstile token 不是一回事。

搞清楚这一点很重要：Turnstile 识别产出的是 token，你要把它放回表单字段；而全站挑战返回的是会话 Cookie。二者不要混淆。

识别流程总览

Turnstile 识别是典型的「token 型验证码」流程，和 reCAPTCHA 识别 (https://blog.omocaptcha.com/ruhe-shibie-recaptcha) 与 hCaptcha 识别 (https://blog.omocaptcha.com/ruhe-shibie-hcaptcha) 完全一致：

1. 在目标页面上找到 Turnstile 的 sitekey（data-sitekey，以 0x 开头）和 页面 URL。
2. 调用 POST /createTask，任务类型用 Turnstile token 任务，携带 websiteURL 与 websiteKey。
3. 轮询 POST /getTaskResult，直到 status 变为 ready。
4. 从 solution 读出 token，回填到页面的 cf-turnstile-response 字段并提交表单。

所有接口基址为 https://api.omocaptcha.com/v2，HTTP 状态码恒为 200，成功与否由 errorId（0 表示成功）判断，采用与 AntiCaptcha 兼容的错误信封。

注意：下方代码使用的任务类型字符串为 TurnstileTokenTask。这是非确认类型，请以 OMOCaptcha API 文档 (https://omocaptcha.com/zh?utm_source=blog&utm_medium=organic) 中的确切 type 为准。已确认可用的类型包括 ImageToTextTask 与 RecaptchaV2TokenTask。

Python 完整示例

import requests
import time

CLIENT_KEY = "YOUR_API_KEY"
BASE = "https://api.omocaptcha.com/v2"

def solve_turnstile(website_url, website_key):
    # 1. 创建任务
    create = requests.post(
        f"(BASE)/createTask",
        json=(
            "clientKey": CLIENT_KEY,
            "task": (
                "type": "TurnstileTokenTask",  # 请在 OMOCaptcha 文档确认确切 type
                "websiteURL": website_url,
                "websiteKey": website_key,
            ),
        ),
        timeout=30,
    ).json()

    if create.get("errorId") != 0:
        raise RuntimeError(f"createTask 失败: (create.get('errorCode')) - (create.get('errorDescription'))")

    task_id = create["taskId"]

    # 2. 轮询结果，带退避
    delay = 3
    for _ in range(20):
        time.sleep(delay)
        res = requests.post(
            f"(BASE)/getTaskResult",
            json=("clientKey": CLIENT_KEY, "taskId": task_id),
            timeout=30,
        ).json()

        if res.get("errorId") != 0:
            raise RuntimeError(f"getTaskResult 失败: (res.get('errorCode'))")

        status = res.get("status")
        if status == "ready":
            # Turnstile token 通常在 solution.token
            return res["solution"].get("token") or res["solution"].get("gRecaptchaResponse")
        if status == "fail":
            raise RuntimeError("任务失败")

        delay = min(delay + 2, 10)  # 礼貌退避

    raise TimeoutError("轮询超时")

if __name__ == "__main__":
    token = solve_turnstile("https://example.com/login", "0xAAAAAAAAAAAAAAAAAA")
    print("cf-turnstile-response =", token)

拿到 token 后，把它写入页面的隐藏字段再提交：

# 例如配合 Selenium/Playwright 回填
# driver.execute_script(
#     "document.querySelector('[name=cf-turnstile-response]').value = arguments[0];",
#     token,
# )

Node.js 完整示例

const CLIENT_KEY = "YOUR_API_KEY";
const BASE = "https://api.omocaptcha.com/v2";

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function postJson(path, body) (
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), 30000); // 30s 超时
  try (
    const resp = await fetch(`$(BASE)$(path)`, (
      method: "POST",
      headers: ( "Content-Type": "application/json" ),
      body: JSON.stringify(body),
      signal: controller.signal,
    ));
    return await resp.json();
  ) finally (
    clearTimeout(timer);
  )
)

async function solveTurnstile(websiteURL, websiteKey) (
  // 1. 创建任务
  const create = await postJson("/createTask", (
    clientKey: CLIENT_KEY,
    task: (
      type: "TurnstileTokenTask", // 请在 OMOCaptcha 文档确认确切 type
      websiteURL,
      websiteKey,
    ),
  ));
  if (create.errorId !== 0) (
    throw new Error(`createTask 失败: $(create.errorCode)`);
  )
  const taskId = create.taskId;

  // 2. 轮询，带退避
  let delay = 3000;
  for (let i = 0; i < 20; i++) (
    await sleep(delay);
    const res = await postJson("/getTaskResult", ( clientKey: CLIENT_KEY, taskId ));
    if (res.errorId !== 0) throw new Error(`getTaskResult 失败: $(res.errorCode)`);
    if (res.status === "ready") (
      return res.solution.token  •  •  res.solution.gRecaptchaResponse;
    )
    if (res.status === "fail") throw new Error("任务失败");
    delay = Math.min(delay + 2000, 10000);
  )
  throw new Error("轮询超时");
)

solveTurnstile("https://example.com/login", "0xAAAAAAAAAAAAAAAAAA")
  .then((token) => console.log("cf-turnstile-response =", token))
  .catch(console.error);

价格与其它验证码

Turnstile 属于 OMOCaptcha 支持的 14 种验证码之一，从 from $0.27/1000 起步。一个 createTask 端点即可覆盖 reCAPTCHA、hCaptcha、FunCaptcha、GeeTest (https://blog.omocaptcha.com/geetest-jiyan-shibie) 等多种类型，无需为每种验证码切换服务商。

验证码类型  •  价格（每 1000 次）

reCAPTCHA v2  •  $0.27
FunCaptcha (Arkose)  •  $0.27
Cloudflare Turnstile  •  支持
hCaptcha  •  $0.60
GeeTest  •  $0.60

完整清单见 价格页 (https://omocaptcha.com/zh#pricing)。想横向对比，可参考验证码识别 API 价格 (https://blog.omocaptcha.com/yanzhengma-shibie-api-jiage)与最佳验证码识别服务推荐 (https://blog.omocaptcha.com/yanzhengma-shibie-fuwu-tuijian)。

OMOCaptcha 采用纯 AI 求解（无人工打码队列延迟），平均 0.42 秒返回、准确率高达 99%，比国际竞品便宜约 20–40%，并提供成功率低于 95% 全额退款的 SLA。若你正在从 2Captcha 迁移，也可以看看 2Captcha 替代方案 (https://blog.omocaptcha.com/2captcha-tidai-fangan)。

合理使用提醒

请仅将 turnstile 识别用于合法自动化场景：对你自己网站表单的 QA 与回归测试、可访问性、经授权/受合同约束的数据采集、负载测试与监控等。务必遵守目标站点的 robots.txt、服务条款与速率限制。请勿用于批量注册虚假账号、欺诈或规避封禁等行为。关于在合规前提下降低被拦截概率，可参考网页采集不被封锁 (https://blog.omocaptcha.com/wangye-caiji-bu-bei-fengsuo)。

注意本文所述是标准的 turnstile token 获取方式，属于正规的 API 集成，而非漏洞式的 turnstile 绕过；产出的 token 仍需经服务端正常校验。

FAQ

Turnstile token 和 Cloudflare 挑战 Cookie 有什么区别？
Turnstile token 是 cf-turnstile-response 字段的一次性凭证，用于表单提交时的人机校验；而 cf_clearance 等是全站拦截挑战产生的会话 Cookie。本文的 cloudflare 验证码识别针对的是前者。

sitekey 在哪里找？
查看页面 HTML 中 class="cf-turnstile" 的元素，其 data-sitekey 属性值即为 sitekey，通常以 0x 开头。把它连同页面 URL 传入 createTask 即可。

token 有有效期吗？
有。Turnstile token 是一次性且有时效的，建议获取后尽快回填并提交表单，不要长期缓存。

任务类型字符串写错了会怎样？
createTask 会返回非 0 的 errorId 与对应 errorCode。请以 OMOCaptcha 官方 API 文档中的确切 type 为准；已确认的类型有 ImageToTextTask 和 RecaptchaV2TokenTask。

我的数据安全吗？
OMOCaptcha 采用端到端加密，不存储验证码内容、不记录客户数据。任务与创建它的 API key 绑定（key-binding），用错 key 会返回 ERROR_TASK_KEY_MISMATCH。

立即开始 Cloudflare Turnstile识别

注册即送 1000 次免费识别，用上面的代码几分钟就能跑通 turnstile 识别。遇到问题欢迎邮件联系 support@omocaptcha.com，7x24 小时响应。

前往 OMOCaptcha 官网 (https://omocaptcha.com/zh?utm_source=blog&utm_medium=organic) 领取免费额度，用一个 API 搞定 Cloudflare Turnstile 及其它 14 种验证码。想快速上手可看验证码 API 快速上手 (https://blog.omocaptcha.com/yanzhengma-api-kuaisu-shangshou)。