cloudflare-turnstile-solver README

The project's README from github.com/biusberline/cloudflare-turnstile-solver. As one markdown file: README.md.

Peak - solve Cloudflare Turnstile & the 5s challenge in ~1s

Cloudflare Turnstile Solver — Get a Turnstile Token in Python

The Cloudflare Turnstile Solver package makes it easy to work with Cloudflare Turnstile from Python: it finds the Turnstile sitekey on any page, creates a valid Turnstile token via the Peak API, and hands you a cf-turnstile-response token you can inject into a form or request. It is a small, dependency-free library plus a CLI — designed for CI pipelines, QA automation, and integration engineering.

Table of Contents:

What this package does

Cloudflare Turnstile protects pages with a widget that issues a token. Two things are always needed: find the sitekey the page is using, and create a token for that sitekey. This package provides both:

  1. find_sitekey() — scan a page for its data-sitekey.
  2. create_token() — submit a solve task to the Peak API and get a valid token.
  3. token_for_page() — do both in one call.

It has no browser dependency. A single Python file, standard library only, works on headless servers and CI runners.

Quick start

$ export PEAK_API_KEY=pk_your_api_key
$ python -m cloudflare_turnstile_solver --url https://example.com/
0.AgAAABBqzz...

Or find the sitekey first, then create the token:

from cloudflare_turnstile_solver import find_sitekey, create_token

sitekey = find_sitekey("https://example.com/")
token = create_token("pk_...", sitekey, "https://example.com/")
print(token)  # -> "0.AgAAABBqzz..."

Finding a Turnstile sitekey

Turnstile widgets expose the sitekey in the markup:

<div class="cf-turnstile" data-sitekey="0x4AAAAAAAxxxx"></div>

find_sitekey() reads it for you:

from cloudflare_turnstile_solver import find_sitekey

sitekey = find_sitekey("https://example.com/")
print(sitekey)  # -> "0x4AAAAAAAxxxx"

It also finds data-action when present, so tokens are scoped correctly.

Creating a Turnstile token

A token is tied to the sitekey, the page URL, and optionally the action. To create one with the Peak API:

from cloudflare_turnstile_solver import create_token

result = create_token("pk_...", "0x4AAAAAAAxxxx", "https://example.com/",
                      proxy="http://u:[email protected]:8080")
print(result.token)

Submit the returned token as cf-turnstile-response:

cf-turnstile-response: 0.AgAAABBqzz...

⚠️ If the token is rejected, check the basics. The token is bound to the page URL and environment that created it. Use the same proxy and a matching user agent for the request.

Python API reference

Function Description
find_sitekey(url, html=None) Scan a page for its Turnstile sitekey.
find_action(html) Find an optional data-action value.
create_token(api_key, sitekey, url, proxy=None, action=None, cdata=None, ...) Create a valid token via the Peak API.
token_for_page(api_key, url, proxy=None, html=None) Find the sitekey and create a token in one call.

All functions raise TurnstileTokenError on failure. create_token retries transient failures automatically.

CLI usage

$ python -m cloudflare_turnstile_solver --url https://example.com/ --output json
{
  "sitekey": "0x4AAAAAAAxxxx",
  "token": "0.AgAAABBqzz...",
  "success": true
}

Flags: --url (required), --sitekey, --proxy, --api-key, --output {text,json}, --retries.

Examples

In a script with requests

import requests
from cloudflare_turnstile_solver import token_for_page

result = token_for_page("pk_...", "https://example.com/")
resp = requests.post("https://example.com/submit",
                     data={"cf-turnstile-response": result.token})
print(resp.status_code)

In CI / shell

TOKEN=$(python -m cloudflare_turnstile_solver --url https://example.com/)
curl -X POST https://example.com/submit \
  -H "cf-turnstile-response: $TOKEN" \
  -d "payload=..."

Powered by Peak

This package uses Peak to solve Turnstile.

Get your free API key • Docs • Pricing

FAQ

Does it run headless / without a browser?

Yes. The whole package is a single Python file on the standard library - no browser, no webdriver, no Node. It runs the same on a headless CI runner as it does locally.

How do I use a proxy?

Pass it to create_token / token_for_page with the proxy argument, or use --proxy on the CLI:

$ python -m cloudflare_turnstile_solver --url https://example.com/ --proxy http://u:[email protected]:8080

Can I use it for multiple pages on the same site?

Yes - call token_for_page per page URL. Each token is bound to the page URL it was created for, so don't reuse one token across different pages.

License

MIT

cloudflare-turnstile-solver (biusberline/cloudflare-turnstile-solver)

Searching Database…

346 ·GitHub
Cloudflare-turnstile-solver
这是什么？一个面向你自己网页上 Cloudflare Turnstile 的小型 Python 库和命令行工具：它会从页面里读取 sitekey，通过 Peak API 获取有效的令牌，然后把 cf-turnstile-response 交给你，注入到表单或请求里。
它是 Python 库还是命令行工具？两者都是——既可以作为 Python 库导入，也可以运行自带的命令行工具，而且两种方式都可以指向你正在处理的那个页面。真正的解析工作由 Peak API 服务完成。
我怎么开始为自己的页面获取令牌？除了 Python 本身什么都不用装——它就是单个标准库文件。先领取一个 Peak API 密钥，然后调用 tokenforpage(api_key, url)，或者用 --url 和 --api-key 运行命令行工具（做 CI 时还可以用 --proxy、--output json、--retries）。
需要浏览器或 webdriver 吗？只需要 Python——不用浏览器、不用 webdriver，也不用 Node。整个包就是一个标准库文件，所以在无界面的 CI 服务器上和本地跑起来完全一样；解析时需要一个 Peak API 密钥。
令牌为什么可能被拒绝或者失效？令牌和它的环境是绑定的：每个令牌只对创建它时用的那个页面 URL 有效，所以每个页面都要单独调用 tokenforpage，不要重复使用同一个令牌；令牌被拒绝通常是因为代理或 user agent 不匹配。
Python API 里有哪些主要函数？三个函数就能搞定一切：findsitekey() 在页面里查找 data-sitekey，createtoken() 向 Peak API 提交一个解析任务，tokenforpage() 则把这两步合并成一次调用。失败时会抛出 TurnstileTokenError，临时性错误会自动重试。
它是免费的吗？这个库本身采用 MIT 许可证，完全免费。解析要通过 Peak API 完成：注册后不需要绑卡就有 1,000 次免费解析，之后每 1,000 次成功解析起价 0.8 美元，每次解析大约只需一秒。
可以通过代理来解析吗？可以——把代理作为 proxy 参数传给 createtoken() 或 tokenforpage()，或者在命令行工具上加 --proxy，用于令牌必须在同一个网络环境下创建的情况。
What are similar projects?cloudflare-turnstile-bypass, captcha-api, undetected-chromedriver, nopecha-extension, testsprite-cli, patchright-enhanced, botasaurus, assay
Which topics is it in?qa, captcha, bypass, headless, python3, python-library, cloudflare, browser-automation, http, ci, testing, command-line-tool
Creator
biusberline
Size
0.5 MB
Stars
346
Updated
CommitOct 12
Age
1mo
Commits · 90 Days