穿云 Python SDK 开发者指南

Published2026-04-08 Updated2026-04-08

穿云 Python SDK 是一款基于 psf/requests 高度封装的库，专为绕过 Cloudflare 防护而设计。它内置了自动化的会话管理与指纹模拟逻辑，支持自动处理 Cookie 和 JA3/HTTP2 指纹，无需手动配置复杂的底层参数。

1. 环境准备与安装

版本要求：Python 3.6 及以上。
安装命令：

# 使用官方 PyPI 源安装
python3 -m pip install cloudbypass -i https://pypi.org/simple

2. 同步请求示例（Session）

Session 类继承自 requests.Session，支持所有原生方法。初始化时可传入 apikey 和 proxy（用于通过 API 通道的代理地址）。

from cloudbypass import Session

if __name__ == '__main__':
    # 初始化会话：传入服务密钥与代理地址
    with Session(apikey="您的APIKEY", proxy="http://proxy:port") as session:
        # 发起请求，SDK 会自动处理 Cloudflare 5秒盾
        resp = session.get("https://opensea.io/category/memberships")

        # 查看响应状态及穿云状态码 (x-cb-status)
        print(f"HTTP 状态码: {resp.status_code}")
        print(f"穿云服务状态: {resp.headers.get('x-cb-status')}")
        print(resp.text)

3. 异步请求示例（AsyncSession）

AsyncSession 类继承自 aiohttp.ClientSession，适用于高并发采集场景。

import asyncio
from cloudbypass import AsyncSession

async def main():
    async with AsyncSession(apikey="您的APIKEY", proxy="http://proxy:port") as session:
        resp = await session.get("https://opensea.io/category/memberships")
        print(f"Status: {resp.status}")
        html = await resp.text()
        print("Body Content:", html[:50], "...")

if __name__ == '__main__':
    asyncio.run(main())

4. 调用 V2 接口（处理 JS 质询/Turnstile）

针对安全等级极高的网站，建议在请求中明确指定 V2 逻辑。

from cloudbypass import Session

if __name__ == '__main__':
    with Session(apikey="您的APIKEY", proxy="http://proxy:port") as session:
        # 使用 V2 逻辑访问高强度防护页面
        resp = session.get("https://etherscan.io/accounts/label/lido", part="0")
        print(f"V2 请求状态: {resp.status_code}")
        print(resp.text)

5. 穿云动态/时效代理提取

通过 Proxy 类，您可以灵活管理全球 200+ 国家和地区的 3.5 亿个动态 IP 资源。

from cloudbypass import Proxy

if __name__ == '__main__':
    # 初始化代理对象 (格式：用户名-res:密码)
    proxy = Proxy("username-res:password")

    # 1. 提取动态住宅代理并指定地区（如美国 US）
    dynamic_proxy = str(proxy.set_dynamic().set_region('US'))
    print(f"动态代理: {dynamic_proxy}")

    # 2. 提取时效代理（如 30 分钟有效期）
    expire_proxy = str(proxy.copy().set_expire(1800).set_region('US'))
    print(f"时效代理: {expire_proxy}")

    # 3. 批量提取 5 个 10 分钟有效期的代理
    pool = proxy.copy().set_expire(600).set_region('US').limit(5)
    for p in pool:
        print(f"批量提取: {p}")

6. 核心注意事项

重定向处理：SDK 会自动处理所有重定向操作。请注意，每一次重定向响应均会正常消耗 API 积分。
环境变量配置：为了安全和便捷，您可以使用以下环境变量预设参数：
- CB_APIKEY: 您的服务密钥
- CB_PROXY: 代理服务地址
- CB_APIHOST: 针对定制用户的自定义服务地址
查询余额：

from cloudbypass import get_balance
# 获取账户当前剩余积分
print(f"当前余额: {get_balance('您的APIKEY')}")

获取密钥：穿云控制台
更多详情：请参考穿云 API 官方文档

穿云API 技术文档