跳到正文
Browsa
目录

RESThttps://browsa.io/v1

Browsa API

面向 AI 智能体的云浏览器。一次 API 调用即可在云端启动我们自研的浏览器 Phantom,再用 Playwright、Puppeteer 或原生 CDP 驱动它。也可以用自然语言描述任务,剩下的交给智能体。

llms.txt OpenAPI 规范

三步完成第一次调用

  1. 获取密钥

    免费注册:验证邮箱后送 100 积分,无需绑卡。密钥形如 agt_live_…。

    获取 API 密钥身份验证

  2. 发起第一次调用

    一个 POST 抓取页面。1 积分,无需 LLM 密钥。

  3. 查看结果

    HTTP 响应就是数据。下一步:用 Playwright 驱动浏览器或运行 AI 任务。

# One POST: the page as Markdown and links, rendered in a real browser.
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"]}'
响应 200
{
  "markdown": "...",
  "links": [...],
  "http_status": 200
}

两种模式,同一个端点

  • 一次性(burner):临时浏览器,TTL 5 分钟到 1 小时,到期自动销毁,按实际运行的分钟计费。适合抓取任务、一次性自动化和 CI 运行。
  • 持久(persistent):长期保存、与保险库同步的配置文件(Cookie、localStorage、指纹),按月计费,按需开启会话。适合需要跨运行保持登录状态的长期智能体。

所有端点都在 https://browsa.io 下。使用 X-API-Key: agt_live_… 进行身份验证。先免费注册(验证邮箱后送 100 积分,无需绑卡),再到控制台创建密钥。

快速开始

两种起步方式,大多数人需要第一种。

1. 抓取页面(无需智能体,无需 LLM)

一个 POST 即可返回干净的 Markdown 页面内容和链接,由真实浏览器渲染。1 积分,无需 LLM 密钥,HTTP 响应就是数据。

curl
# 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"}'

就这么简单。TTL 归零(或你 DELETE 它)时,浏览器即被销毁。按运行时间付费:每开始一个 12 分钟收 1 积分,整整 1 小时 5 积分。启动时会预扣所申请 TTL 的费用(5 分钟以内 1 积分,超过则 5 积分);结束后,未用到的计费块会退回。

身份验证

每个请求都需要在 X-API-Key 请求头中带上 API 密钥。密钥在控制台创建,格式为 agt_live_ 后跟 24 个十六进制字符。

HTTP
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
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 browsa
Python
from 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 browsa
TypeScript
import { 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 可指定某个已保存的密钥。

JSON
{
  "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