文档开发者工具SDKsPython SDK

Python SDK

概述

Scrapeless 官方 Python SDK 提供对浏览器自动化、抓取、爬取、Proxies、搜索结果以及 AI 聊天内容提取的访问能力。本指南遵循 SDK 仓库 README，包含可运行的示例和配置详情。

环境要求

包元数据中声明了 Python 3.8 或更高版本。根据所安装的 Playwright 或 Pyppeteer 版本，浏览器集成可能需要更新版本的 Python。

请使用虚拟环境，以便将 SDK 依赖与其他项目隔离开来。

安装

pip install scrapeless

该仓库使用 python-dotenv 加载环境变量，但其当前的包元数据并未将其列为依赖项。如有需要，请将其与 SDK 一起安装：

pip install python-dotenv

在使用相应的浏览器集成时，请单独安装 pyppeteer 或 playwright。

认证 / API 密钥

登录 Scrapeless 控制台并创建 API 密钥。在运行示例之前将其导出：

export SCRAPELESS_API_KEY="YOUR_API_KEY"

请将你的 API 密钥保存在环境变量或密钥管理器中，而不要将其提交到源代码管理系统。

Scrapeless() 会读取 SCRAPELESS_API_KEY。你也可以在客户端配置字典中传入 api_key 条目。

快速开始

将以下内容保存为 quickstart.py，在设置好 API 密钥后运行 python quickstart.py。

from scrapeless import Scrapeless
from scrapeless.types import UniversalScrapingRequest
 
client = Scrapeless()
result = client.universal.scrape(UniversalScrapingRequest(
    actor='unlocker.webunlocker',
    input={'url': 'https://example.com', 'method': 'GET', 'redirect': False}
))
print(result)

产品覆盖矩阵

产品SDK 服务覆盖范围
Agent Browserclient.browser创建并管理远程浏览器会话。
Browser Profilesclient.profiles跨会话持久化浏览器数据。
Scraping APIclient.scraping使用网站 actor 提取结构化数据。
Web Unlockerclient.universal从受保护的网站获取内容。
Crawlclient.scraping_crawl抓取单个页面或爬取整个网站。
Google Search APIclient.deepserp提取搜索引擎结果。
Proxiesclient.proxies生成代理连接 URL。
AI Scraperclient.ai_scraper创建 AI 聊天任务并获取其状态和结果。

使用示例

Browser

使用 pip install pyppeteer 安装浏览器集成。

高级浏览器会话管理，支持 Playwright 和 Pyppeteer 框架，具备可配置的反检测能力（例如指纹伪造、CAPTCHA 求解）以及可扩展的自动化工作流：

from scrapeless import Scrapeless
from scrapeless.types import ICreateBrowser
import asyncio
import pyppeteer
 
client = Scrapeless()
 
 
async def example():
    # Create a browser session
    config = ICreateBrowser(
        session_name='sdk_test',
        session_ttl=180,
        proxy_country='US',
        session_recording=True
    )
    session = client.browser.create(config).__dict__
    browser_ws_endpoint = session['browser_ws_endpoint']
    print('Browser WebSocket endpoint created:', browser_ws_endpoint)
 
    # Connect to browser using pyppeteer
    browser = await pyppeteer.connect({'browserWSEndpoint': browser_ws_endpoint})
    try:
        page = await browser.newPage()
        await page.goto('https://example.com')
        print(await page.title())
    finally:
        await browser.close()
 
 
asyncio.run(example())

Browser Profile

管理浏览器配置文件以实现持久会话。

from scrapeless import Scrapeless
 
client = Scrapeless()
profile = client.profiles.create('My Profile')
print(profile)

Scraping API

面向网站（例如电商、旅行平台）的直接数据提取 API。通过预构建的连接器获取结构化的产品信息、价格和评论：

from scrapeless import Scrapeless
from scrapeless.types import ScrapingTaskRequest
 
client = Scrapeless()
request = ScrapingTaskRequest(
    actor='scraper.google.search',
    input={'q': 'nike site:www.nike.com'}
)
result = client.scraping.scrape(request=request)
print(result)

Web Unlocker

使用 Web Unlocker（以 client.universal 暴露）从网站提取数据。

from scrapeless import Scrapeless
from scrapeless.types import UniversalScrapingRequest
 
client = Scrapeless()
result = client.universal.scrape(UniversalScrapingRequest(
    actor='unlocker.webunlocker',
    input={'url': 'https://example.com', 'method': 'GET', 'redirect': False}
))
print(result)

Crawl

从单个页面提取数据或遍历整个域名，并以 Markdown、JSON、HTML、截图和链接等多种格式导出。

from scrapeless import Scrapeless
 
client = Scrapeless()
 
result = client.scraping_crawl.scrape_url("https://example.com")
print(result)

Proxy

使用你的网关和会话设置生成代理 URL。

from scrapeless import Scrapeless
from scrapeless.types import ICreateProxy
 
client = Scrapeless()
proxy_url = client.proxies.proxy(ICreateProxy(
    country='US',
    session_duration=30,
    session_id=client.proxies.generate_session_id(),
    gateway='your-proxy-gateway:port'
))
print(proxy_url)

AI Scraper

批量提取 AI 聊天内容，以监控品牌提及、比较回答，并分析来自最新模型的竞争情报。通过单一集成即可获取 URL、提示词、Markdown 回答、引用等内容。

支持的 actor 包括 scraper.chatgpt、scraper.perplexity、scraper.copilot、scraper.gemini、scraper.aimode、scraper.overview、scraper.grok 和 scraper.alexa。input JSON 取决于所使用的 actor；有关详细参数，请参阅 AI Scraper 文档。可选的 webhook JSON 包含一个回调 url。

from scrapeless import Scrapeless
from scrapeless.types import AIScraperTaskRequest
 
 
def main():
    client = Scrapeless()  # Uses SCRAPELESS_API_KEY
    task = client.ai_scraper.create_task(AIScraperTaskRequest(
        actor='scraper.chatgpt',
        input={
            'prompt': 'Most reliable proxy service for data extraction',
            'country': 'US',
            'web_search': True,
        },
        # Optional: webhook={'url': 'https://your-webhook.example.com'},
    ))
    print('Created task:', task)
 
    result = client.ai_scraper.get_task_result(task['task_id'])
    print('Task status and result:', result)
    # If status is 'running', call get_task_result again later.
    # If status is 'failed', message contains the failure reason.
 
 
if __name__ == '__main__':
    main()

这两个方法都会原样返回 API JSON。创建操作会返回 task_id、status，并在可用时返回 task_result。结果获取操作会返回 status、可用时的 task_result，以及失败时的 message。状态为 success、failed 或 running；SDK 不会自动轮询。

create_task 接受 AIScraperTaskRequest 或字典；字典还允许附加额外的 API 参数。响应为字典。

Google Search API

from scrapeless import Scrapeless
from scrapeless.types import ScrapingTaskRequest
 
client = Scrapeless()
result = client.deepserp.scrape(ScrapingTaskRequest(
    actor='scraper.google.search',
    input={'q': 'nike site:www.nike.com'}
))
print(result)

如需更完整的集成示例，请浏览仓库的 examples 目录。

错误处理

捕获 ScrapelessError 以处理 API 请求失败。请单独检查 AI Scraper 响应的 status 以处理任务失败。

from scrapeless import Scrapeless, ScrapelessError
from scrapeless.types import UniversalScrapingRequest
 
client = Scrapeless()
try:
    result = client.universal.scrape(UniversalScrapingRequest(
        actor='unlocker.webunlocker',
        input={'url': 'https://example.com', 'method': 'GET'}
    ))
    print(result)
except ScrapelessError as error:
    print(f'Scrapeless API error: {error}')

当前的 Python 异常会暴露错误消息；它并未定义 status_code 属性。

配置 / 环境变量

API 密钥是必需的。端点覆盖是可选的；下表列出了它们的默认值。

向 Scrapeless 传入字典以覆盖配置：

import os
from scrapeless import Scrapeless
 
client = Scrapeless({
    'api_key': os.environ['SCRAPELESS_API_KEY'],
    'timeout': 30000,  # Request timeout in milliseconds
    'base_api_url': 'https://api.scrapeless.com',
    'browser_api_url': 'https://browser.scrapeless.com',
    'scraping_crawl_api_url': 'https://api.scrapeless.com',
})

显式配置优先于环境变量。默认请求超时为 30,000 毫秒。

环境变量用途 / 默认值
SCRAPELESS_API_KEY来自控制台的必需 API 密钥。
SCRAPELESS_BASE_API_URLhttps://api.scrapeless.com
SCRAPELESS_BROWSER_API_URLhttps://browser.scrapeless.com
SCRAPELESS_CRAWL_API_URLhttps://api.scrapeless.com

支持

该 SDK 基于 MIT 许可证发布。

相关项目

Node.js / TypeScript SDKGo SDK