Python SDK 快速开始

按 API Key、Session、View 验证、Playwright 连接的顺序接入云端浏览器。

这一页和产品快速入门使用同一条主线：先准备 API Key 和 Project ID，再创建 session，最后用 Playwright 通过 CDP 连接云端浏览器。

先完成控制台验证

如果还没有创建过 API Key，先在控制台完成快速入门。文档里的 SDK 代码会复用同一个 Project ID 和 API Key。

1. 安装依赖

python3 -m venv .venv
source .venv/bin/activate

pip install lexmount==0.5.16 playwright python-dotenv
playwright install chromium

如果你使用的是 quickstart 示例仓库，也可以先安装仓库依赖：

pip install -r requirements.txt

2. 配置调用凭证

推荐把凭证放在环境变量或 .env 文件中，避免把 API Key 写进源码。

export LEXMOUNT_API_KEY="sk_..."
export LEXMOUNT_PROJECT_ID="project_..."

# 测试环境可选
export LEXMOUNT_BASE_URL="https://api.lexmount.cn"

字段含义：

字段	从哪里获取	用途
`LEXMOUNT_API_KEY`	Settings / API Keys	SDK 调用身份
`LEXMOUNT_PROJECT_ID`	API Key 页面同屏展示	决定 session 属于哪个项目
`LEXMOUNT_BASE_URL`	环境配置	指向正式或测试 API 服务

3. 创建一个云端浏览器 session

from lexmount import Lexmount

client = Lexmount()

with client.sessions.create(browser_mode="normal") as session:
    print("session id:", session.id)
    print("view url:", session.inspect_url)
    print("connect url:", session.connect_url)

这段代码对应控制台里的“创建 session”：

session.id：云端浏览器实例 ID，后续查询、停止、下载都围绕它进行。
session.inspect_url：远程 View 地址，可以打开来观察云端浏览器画面。
session.connect_url：CDP 连接地址，Playwright / Puppeteer 用它接管浏览器。

4. 用 Playwright 连接并导航

from lexmount import Lexmount
from playwright.sync_api import sync_playwright

client = Lexmount()

with client.sessions.create(browser_mode="normal") as session:
    with sync_playwright() as p:
        browser = p.chromium.connect_over_cdp(session.connect_url)
        context = browser.contexts[0] if browser.contexts else browser.new_context()
        page = context.pages[0] if context.pages else context.new_page()

        page.goto("https://example.com", wait_until="domcontentloaded")
        print("title:", page.title())

        browser.close()

这段代码对应控制台里的“View 导航”，只是把人工输入网址改成了 Playwright 操作：

SDK 创建云端浏览器 session。
Playwright 通过 connect_url 连接到这台远程浏览器。
代码在远程页面上执行 goto、读取标题等操作。
退出上下文管理器时，SDK 会关闭 session 并释放资源。

5. 开启下载或回放存储

下载文件和回放存储都需要显式开启。只打开当前任务需要的产物类型。

download_session = client.sessions.create(
    browser_mode="normal",
    downloads={"enabled": True},
)

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(download_session.connect_url)
    cdp = browser.new_browser_cdp_session()
    cdp.send(
        "Browser.setDownloadBehavior",
        {
            "behavior": "allow",
            "downloadPath": "/config/Downloads",
            "eventsEnabled": True,
        },
    )

replay_session = client.sessions.create(
    browser_mode="normal",
    recording={"persistent": True},
)

download-enabled session 产生文件后，用 client.sessions.downloads.list/get/archive 取回。recording-enabled session 关闭后，在控制台 session 详情页查看 replay 结果。

6. 和示例脚本的对应关系

示例	对应 quickstart 步骤	适合什么时候看
`demo.py`	创建 session、连接浏览器、访问页面	第一次验证 SDK 是否能跑通
`inspect_url_demo.py`	创建 session、打开 View、保留远程画面	需要边看远程浏览器边调试
`session_list.py`	查询 session 状态	想确认当前项目里还有哪些浏览器在运行
`session_downloads.py`	远程浏览器下载文件后取回	任务会产生文件下载结果
`context_basic.py`	复用浏览器上下文	需要保存登录态或浏览器数据
`extension_basic.py`	创建 session 时挂载扩展	需要 Chrome 扩展参与任务
`proxy_demo.py`	创建 session 时指定代理	需要自定义上游代理

完整说明见 Python 示例与参考。

常见问题

为什么要先用控制台验证？

控制台能把凭证、项目、session、View 和连接入口展示出来。先手动跑通，可以快速判断问题是在账号配置、浏览器启动，还是代码连接。

session 什么时候会结束？

session 由平台统一管理。任务完成后建议主动关闭；如果到达项目配置的会话超时时间，平台会根据最近 CDP 活跃情况决定清理时机。

View 和 Playwright 会冲突吗？

不会。View 是观察和人工接管入口，Playwright 使用 connect_url 控制同一个远程浏览器。调试时可以一边运行代码，一边通过 View 看页面状态。