两种模式,同一个端点
- 一次性(burner):临时浏览器,TTL 5 分钟到 1 小时,到期自动销毁,按实际运行的分钟计费。适合抓取任务、一次性自动化和 CI 运行。
- 持久(persistent):长期保存、与保险库同步的配置文件(Cookie、localStorage、指纹),按月计费,按需开启会话。适合需要跨运行保持登录状态的长期智能体。
快速开始
两种起步方式,大多数人需要第一种。
1. 抓取页面(无需智能体,无需 LLM)
一个 POST 即可返回干净的 Markdown 页面内容和链接,由真实浏览器渲染。1 积分,无需 LLM 密钥,HTTP 响应就是数据。
# Scrape any URL → clean Markdown + links in one call.
curl -X POST https://browsa.io/v1/quick/scrape \
-H "X-API-Key: agt_live_…" \
-H "Content-Type: application/json" \
-d '{"url":"https://news.ycombinator.com","formats":["markdown","links"]}'
# → { "markdown": "...", "links": [...], "http_status": 200 }2. 自己驱动浏览器:通过 CDP 使用 Playwright
三行代码,拿到一个由你的代码控制的云浏览器。创建一个一次性浏览器,再把 Playwright/Puppeteer 连接到返回的 cdp_http URL,并在 X-API-Key 请求头中带上密钥。无需基础设施,无需调教指纹。
# Provision a burner agent - returns CDP URL you can attach to.
curl https://browsa.io/v1/agents \
-H "X-API-Key: agt_live_…" \
-H "Content-Type: application/json" \
-d '{"ttl":"10m","initial_url":"https://example.com"}'# pip install browsa
from browsa import Client
from playwright.sync_api import sync_playwright
API_KEY = "agt_live_…"
client = Client(api_key=API_KEY)
agent = client.create_agent(ttl="10m")
with sync_playwright() as p:
browser = p.chromium.connect_over_cdp(agent["cdp_http"], headers={"X-API-Key": API_KEY})
context = browser.contexts[0]
page = context.pages[0] if context.pages else context.new_page()
page.goto("https://example.com")
print(page.title())// npm i browsa playwright
import { Client } from "browsa";
import { chromium } from "playwright";
const apiKey = "agt_live_…";
const client = new Client({ apiKey });
const agent = await client.createAgent({ ttl: "10m" });
const browser = await chromium.connectOverCDP(agent.cdp_http, { headers: { "X-API-Key": apiKey } });
const context = browser.contexts()[0];
const page = context.pages()[0] ?? await context.newPage();
await page.goto("https://example.com");
console.log(await page.title());就这么简单。TTL 归零(或你 DELETE 它)时,浏览器即被销毁。按运行时间付费:每开始一个 12 分钟收 1 积分,整整 1 小时 5 积分。启动时会预扣所申请 TTL 的费用(5 分钟以内 1 积分,超过则 5 积分);结束后,未用到的计费块会退回。
身份验证
每个请求都需要在 X-API-Key 请求头中带上 API 密钥。密钥在控制台创建,格式为 agt_live_ 后跟 24 个十六进制字符。
X-API-Key: agt_live_aabbccddeeff001122334455也支持 Bearer 认证(密钥格式相同),方便总是设置 Authorization 请求头的客户端。
请妥善保管密钥。原始密钥只在创建时显示一次。我们只保存 sha256(secret)。如果密钥泄露,请在控制台吊销并创建新密钥。
幂等性
所有 POST /v1/quick/* 端点、POST /v1/tasks、POST /v1/auto 和 POST /v1/sessions/{id}/messages 都支持 Idempotency-Key 请求头(与 Stripe 兼容)。POST /v1/agents 不支持:每次调用都会启动一个新浏览器并计费。每个逻辑请求传一个 UUID,平台会把完整响应缓存 24 小时。用相同的幂等键重试,会逐字节返回缓存的响应体,并带上 Idempotent-Replay: true:不会再创建一次性浏览器,也不会重复扣费。
curl -X POST https://browsa.io/v1/quick/scrape \
-H "X-API-Key: agt_live_…" \
-H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com"}'凡是客户端库会自动重试的地方都应使用它(例如带退避的 requests.Session)。否则一次短暂的网络抖动就可能让抓取重复执行并扣费两次。
请求 ID
每个响应(无论成功还是出错)都带有 X-Request-Id 响应头。错误响应的 JSON 体中也包含 request_id。遇到任何问题,请把它发给 support@browsa.io,方便我们在日志中找到你的请求。
SDKs
对 REST API 的零依赖封装,提供类型化响应、长轮询 waitForJob、HMAC Webhook 签名校验,并把完整的 {code, error, request_id} 错误结构映射为类型化错误。Python 与 TypeScript 接口完全一致。
Python
pip install browsafrom browsa import Client
c = Client(api_key="agt_live_...")
job = c.run_task(
task="Go to news.ycombinator.com and return the top story title.",
llm="claude-opus-5-5",
llm_api_key="sk-ant-...",
)
print(job.final_result)
print("watch live:", job.live_url)包:PyPI 上的 browsa(Python 3.9+,零依赖,MIT)。
TypeScript / Node
npm i browsaimport { Client } from "browsa";
const c = new Client({ apiKey: "agt_live_..." });
const job = await c.runTask({
task: "Go to news.ycombinator.com and return the top story title.",
llm: "claude-opus-5-5",
llmApiKey: "sk-ant-...",
});
console.log(job.finalResult);
console.log("watch live:", job.liveUrl);包:npm 上的 browsa(Node 18+,零依赖,ESM + CJS,完整 .d.ts,MIT)。
MCP 服务器:Claude Desktop、Cursor、Cline
只需一个配置块,就能在任何兼容 MCP 的客户端中使用平台。智能体可获得 13 个工具:run_task、get_job、cancel_job、respond_to_job、list_job_files、create_schedule、list_schedules、list_llm_keys、credits、list_webhooks、create_webhook、delete_webhook、list_identities。
配置中无需 LLM 密钥。在工作区保存一个 LLM 密钥后,服务器会优先使用你保存的默认密钥。BROWSA_LLM_API_KEY 是可选的。如果没有保存密钥也没有设置 llm,任务会回退到 Browsa 的默认托管模型档位("llm": "browsa",每个任务加收该档位的积分),服务器也会告知你。显式指定 llm 却没有密钥时,返回 LLM_KEY_REQUIRED。设置 BROWSA_LLM_KEY_ID 可指定某个已保存的密钥。
{
"mcpServers": {
"browsa": {
"command": "npx",
"args": ["-y", "@browsa/mcp"],
"env": {
"BROWSA_API_KEY": "agt_live_..."
}
}
}
}把它放进 ~/Library/Application Support/Claude/claude_desktop_config.json(macOS)或 %APPDATA%\Claude\claude_desktop_config.json(Windows),然后重启 Claude Desktop。试着问:“打开 news.ycombinator.com,告诉我排名第一的帖子标题。”
包:npm 上的 @browsa/mcp(适用于 Claude Desktop、Cursor、Cline、Continue、Zed,MIT)。Claude Code、Cursor 和 VS Code 的配置方法见 MCP 服务器指南。
示例
各包页面提供快速开始示例和 Webhook 接收端示例:PyPI 上的 Python 包、npm 上的 TypeScript 包。完整脚本请看实战示例和框架指南。
OpenAPI 规范
可导入 Postman、Insomnia、Swagger UI 或任何 OpenAPI 3.1 客户端。完整接口定义发布在 https://browsa.io/openapi.yaml。
# Generate a typed client in any language with openapi-generator-cli
npx @openapitools/openapi-generator-cli generate \
-i https://browsa.io/openapi.yaml \
-g typescript-axios -o ./browsa-client