API 参考

浏览器端点

所有 /v1/browser 端点，涵盖运行、保险库密钥、文件和配置文件，包括参数、限制、响应和错误。

浏览器智能体 API 位于 https://lovelyrouter.com/v1/browser 下。每个请求都需要用你的 API 密钥进行身份验证，格式为 Authorization: Bearer $LOVELY_API_KEY（身份验证）。除文件上传和截图外，请求体和响应体均为 JSON。运行从你的预付费余额中扣费，参见模式、模型与价格。

如需完整的入门演示，请从浏览器智能体概览开始。

运行对象#

一次运行就是交给智能体的一个任务。每个运行端点都返回此对象。标记为 仅限 API 的字段不会出现在 Webhook 负载中。

属性

idstring

唯一 id，brun_ 后跟 24 个字符。

objectstring

始终为 browser_run。

statusstring

running、waiting_for_human、succeeded、failed、timed_out 或 stopped。

goalstring

你发送的目标。

start_urlstring

运行开始时所在的 URL。

enginestring

始终为 chromium。

modestring

fast 或 accurate。

modelstring | null

你通过 model 选择的模型；使用内置模型时为 null。

model_usdnumber

仅在你选择了 model 时出现：该模型的 token 截至目前的费用，含 20% 附加费。

stepsinteger

截至目前记录的步数，包括等待人工的暂停。暂停不计费。

max_stepsinteger

运行的步数上限。

billable_time_sinteger

截至目前，超出每步和每次暂停所含 1 分钟的秒数。

time_usdnumber

billable_time_s 的费用，按每分钟 $0.005 计算。

current_urlstring

浏览器当前所在的页面，或运行结束时所在的页面。

answerstring | null

智能体完成后给出的回答。达到 max_steps 的运行也会根据最后一个页面给出回答。

dataobject | array | null

运行结束后的结构化输出，在你传入了 output_schema 或目标中要求了某种结构时返回。参见结构化输出。

data_errorstring

仅在结构化输出失败时出现，内容为失败原因。

errorstring | null

运行未成功的原因，例如 reached the step limit (50)、blocked by the website、no human response within 30 minutes、stopped by the user。

needsobject | null

当 status 为 waiting_for_human 时，说明运行正在等待什么。否则为 null。

profile_savedobject | null

使用 save_profile 时，运行结束时保存的配置文件：id、name 和 cookies（已保存的 Cookie 数量）。

usageobject

decision_calls 和 llm_calls：智能体调用模型的次数。仅供参考，费用已包含在每步价格中。

created_atstring

运行开始的时间（ISO 8601）。

finished_atstring | null

运行结束的时间。

tracearray

仅在传入 ?trace=1 时返回。每步一项：step、url、action（例如 click:e12、type:e3、choose:e5、secret:e4:shop_password、upload:e9、back、done，暂停时为 ask、approval、handoff）、description、ms（耗时）和 error（null，或该步失败的原因）。

charge_usdnumber | null

仅限 API。 运行的费用，在运行结束几秒后完成结算时给出。此前为 null。

reserved_usdnumber

仅限 API。 运行进行期间预留的金额；结算后为 0。

The run object

{
  "id": "brun_3f9a1c7e0b2d4e6f8a9b0c1d",
  "object": "browser_run",
  "status": "succeeded",
  "goal": "Find the price of the book \"A Light in the Attic\" and whether it is in stock.",
  "start_url": "https://books.toscrape.com/",
  "engine": "chromium",
  "mode": "fast",
  "model": null,
  "steps": 2,
  "max_steps": 50,
  "billable_time_s": 0,
  "time_usd": 0,
  "current_url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html",
  "answer": "\"A Light in the Attic\" costs £51.77 and is in stock (22 available).",
  "data": null,
  "error": null,
  "needs": null,
  "profile_saved": null,
  "usage": { "decision_calls": 3, "llm_calls": 1 },
  "created_at": "2026-10-11T09:30:00.000Z",
  "finished_at": "2026-10-11T09:30:07.000Z",
  "trace": [
    {
      "step": 1,
      "url": "https://books.toscrape.com/",
      "action": "click:e54",
      "description": "click link \"A Light in the ...\" → https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html",
      "ms": 2140,
      "error": null
    },
    {
      "step": 2,
      "url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html",
      "action": "done",
      "description": "Read the result and wrote the answer",
      "ms": 2875,
      "error": null
    }
  ],
  "charge_usd": 0.012,
  "reserved_usd": 0
}

创建运行#

POST/v1/browser/runs

启动一次运行，并立即返回 202 和运行对象。智能体在后台工作；你可以通过事件流、获取运行或 Webhook 跟踪进度。启动运行时会从你的余额中预留其最高费用（预留机制说明）。

响应中还包含 poll（一个带 ?wait=30 的现成状态路径）、events（该运行的事件流）；如果传入了 webhook，还包含 webhook_secret。webhook_secret 只在这里返回（流式启动时在第一个事件中返回）。

传入 "stream": true 时，响应改为 200 和该运行的事件流，从开始一直持续到运行结束。参见实时事件与屏幕。

请求体参数

goalstring必填

用平实的语言说明要做什么，并写明任务所需的每个值。最多 4,000 个字符。参见写出有效的目标。

start_urlstring必填

要打开的第一个页面。必须是 http 或 https URL。

modestring默认 fast

fast（每步 $0.006）或 accurate（每步 $0.012：拿不准时还会查看截图，并能运行只读的页面代码）。参见模式。

max_stepsinteger默认 50

步数上限，1 到 100。超出范围的值会被截取到范围边界。运行只为实际执行的步数计费。

output_schemaobject

用于生成 data 中 JSON 的 JSON Schema（draft 2020-12），或类似 {"title": "string", "items": [{"name": "string"}]} 的简写。最大 20 KB。

approvestring默认 risky

在执行会提交内容的操作（提交按钮、购买/预订/付款/发送/删除按钮，或在非搜索表单中按 Enter）之前何时暂停等待批准：risky（仅限购买、下单、发送、删除、提交申请）、submit（每一个此类操作）或 none。其他任何值都会返回 400。

humanboolean默认 true

智能体是否可以提问和交出浏览器。无人值守的运行请设为 false。

human_timeout_minutesnumber默认 30`（由云端 Agent 启动的运行为 `5`）

每次暂停等待回复的时长，1 到 1,440 分钟。超出范围的值会被截取到范围边界。超时后运行以 timed_out 结束。

secretsarray

智能体可以输入的保险库密钥名称。

ephemeral_secretsobject

仅用于本次运行的密钥，运行结束时删除。这是一个从名称（规则与保险库名称相同）到以下对象的映射：

filesarray | string

智能体可以附加的已上传文件的名称或 id，或用 "*" 表示全部文件。

profilestring

作为起点的已保存配置文件的名称或 id。

save_profilestring

运行结束时，以此名称保存会话的 Cookie 和本地存储。最多 64 个字符。

allowed_domainsarray

浏览器可以访问的主机名，例如 "example.com" 或 "*.example.com"。最多 50 个。

webhookstring

接收 run.waiting 和 run.finished 事件的 https URL。

modelstring

来自 GET /v1/models 的模型 id，例如 claude-sonnet-5.5，用于智能体的思考、填写和数据提取。其 token 按正常价格加收 20% 计费。

max_model_usdnumber

与 model 搭配使用：该模型 token 费用的上限，含附加费。默认值根据 max_steps 和模型价格估算。

streamboolean默认 false

为 true 时返回该运行的事件流（text/event-stream），而不是 202 JSON。

screenboolean默认 false

与 stream 搭配使用：增加带浏览器屏幕画面的 frame 事件。

Shell

curl https://lovelyrouter.com/v1/browser/runs \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "goal": "Find the price of the book \"A Light in the Attic\" and whether it is in stock.",
    "start_url": "https://books.toscrape.com/"
  }'

Response

{
  "id": "brun_3f9a1c7e0b2d4e6f8a9b0c1d",
  "object": "browser_run",
  "status": "running",
  "goal": "Find the price of the book \"A Light in the Attic\" and whether it is in stock.",
  "start_url": "https://books.toscrape.com/",
  "engine": "chromium",
  "mode": "fast",
  "model": null,
  "steps": 0,
  "max_steps": 50,
  "billable_time_s": 0,
  "time_usd": 0,
  "current_url": "https://books.toscrape.com/",
  "answer": null,
  "data": null,
  "error": null,
  "needs": null,
  "profile_saved": null,
  "usage": { "decision_calls": 0, "llm_calls": 0 },
  "created_at": "2026-10-11T09:30:00.000Z",
  "finished_at": null,
  "poll": "/v1/browser/runs/brun_3f9a1c7e0b2d4e6f8a9b0c1d?wait=30",
  "events": "/v1/browser/runs/brun_3f9a1c7e0b2d4e6f8a9b0c1d/events",
  "charge_usd": null,
  "reserved_usd": 0.445
}

获取运行#

GET/v1/browser/runs/{id}

返回运行对象。带上 wait 时，请求会一直挂起，直到运行状态（或暂停类型）发生变化，或经过 wait 秒，然后返回当前状态。运行处于 waiting_for_human 时会立即返回。

查询参数

waitinteger默认 0

运行处于 running 时挂起请求的秒数，最多 50。

tracestring

传 1 会附加 trace，即截至目前的步骤列表。

Shell

curl "https://lovelyrouter.com/v1/browser/runs/brun_3f9a1c7e0b2d4e6f8a9b0c1d?wait=30&trace=1" \
  -H "Authorization: Bearer $LOVELY_API_KEY"

响应为运行对象；传入 trace=1 时附带 trace。

流式获取运行#

GET/v1/browser/runs/{id}/events

以 Server-Sent Events（text/event-stream）返回运行的实时事件，直到运行结束。第一个事件是带 trace 的运行对象；之后是 activity（智能体当前在做什么）、step（每个完成的步骤）、run（每一步之后，以及暂停开始或结束时），使用 screen 时还有 frame（浏览器屏幕画面）。最后的事件是带 charge_usd 的已结束运行和 end。已结束的运行会立即发送其 run 事件和 end。以 : 开头的行是保活注释。参见实时事件与屏幕。

Query parameters

screenstring

1 增加 frame 事件：data（浏览器的 base64 JPEG 画面）和 at。连接时发送一帧，之后页面每次变化时发送，最多约每秒 4 帧。

事件	`data`
`run`	带 `charge_usd` 和 `reserved_usd` 的运行对象；第一个包含 `trace`
`activity`	`step`、`kind`（`starting`、`reading`、`waiting`、`deciding`、`thinking`、`checking`、`acting`、`answering`、`extracting`）和 `text`
`step`	一条 `trace` 记录
`frame`	`data`（base64 JPEG）和 `at`
`end`	`id`

cURL

curl -N "https://lovelyrouter.com/v1/browser/runs/brun_3f9a1c7e0b2d4e6f8a9b0c1d/events?screen=1" \
  -H "Authorization: Bearer $LOVELY_API_KEY"

响应

event: run
data: {"id":"brun_3f9a1c7e0b2d4e6f8a9b0c1d","object":"browser_run","status":"running","steps":1,"trace":[…],…}

event: frame
data: {"data":"/9j/4AAQSkZJRgABAQ…","at":"2026-10-11T09:30:03.120Z"}

event: activity
data: {"step":2,"kind":"answering","text":"Reading the result and writing the answer"}

event: step
data: {"step":2,"url":"https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html","action":"done","description":"Read the result and wrote the answer","ms":2875,"error":null}

event: run
data: {"id":"brun_3f9a1c7e0b2d4e6f8a9b0c1d","status":"succeeded","answer":"\"A Light in the Attic\" costs £51.77 and is in stock (22 available).","charge_usd":0.012,…}

event: end
data: {"id":"brun_3f9a1c7e0b2d4e6f8a9b0c1d"}

列出运行#

GET/v1/browser/runs

以简要形式返回你最近的 50 次浏览器智能体运行，最新的在前。如需完整状态，请获取单个运行。

字段	含义
`id`	运行 id
`billing_status`	结算前为 `running`，之后为 `succeeded`、`failed`、`timed_out` 或 `stopped`
`goal`	目标的前 200 个字符
`steps`	已计费的步数，结算前为 `0`
`created_at`	运行开始的时间

cURL

curl https://lovelyrouter.com/v1/browser/runs \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "id": "brun_3f9a1c7e0b2d4e6f8a9b0c1d",
      "billing_status": "succeeded",
      "goal": "Find the price of the book \"A Light in the Attic\" and whether it is in stock.",
      "steps": 2,
      "created_at": "2026-10-11T09:30:00.000Z"
    }
  ]
}

回复运行#

POST/v1/browser/runs/{id}/reply

回复处于 waiting_for_human 的运行。每次只能发送一种回复，且须与 needs.kind 对应。返回 200 和运行对象，其 status 恢复为 running。参见人工介入。

请求体参数

answerstring

用于 question：供智能体阅读的文本。最多 2,000 个字符。

secretstring

用于 question：由智能体在当前网站上输入、但它自己看不到的值。最多 4,096 个字符。可以填入该网站上任何文本类字段，包括密码和 PIN 字段。

approveboolean

用于 approval：true 表示允许智能体点击按钮，false 表示拒绝。

denyboolean

用于 approval：true 等同于 "approve": false。

reasonstring

拒绝时附带的原因，供智能体阅读。最多 500 个字符。

doneboolean

用于 takeover：人工操作完成时为 true。智能体会从当前页面继续。

failedboolean

用于 takeover：人工未能完成时为 true。

notestring

与 done 或 failed 搭配：说明人做了什么，供智能体阅读。最多 500 个字符。

错误：请求体不符合任何回复格式时返回 400；409 This run is not waiting for a reply；回复与当前暂停不匹配时返回 409 This run is waiting for a reply of kind "question"（或 approval、takeover）。

cURL

curl https://lovelyrouter.com/v1/browser/runs/brun_5b7d9f1a3c5e7a9b1d3f5a7c/reply \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"secret": "481923"}'

Reply bodies

{"answer": "Use the billing address."}
{"approve": true}
{"approve": false, "reason": "Wrong delivery date"}
{"done": true, "note": "Solved the CAPTCHA"}
{"failed": true, "note": "The site asked for a phone call"}

接管运行#

POST/v1/browser/runs/{id}/takeover

请求运行在当前步骤完成后把浏览器交给你。返回 202 和运行对象。下一次查询状态时会显示 waiting_for_human，needs.kind 为 takeover，并带有 live_view_url。操作完成后，发送 {"done": true} 回复即可交还浏览器。

如果运行正在等待问题回复或批准，接管会在你回复之后开始。已结束的运行返回 409 和 This run has finished。

请求体参数

instructionsstring

作为暂停的 prompt 显示。最多 500 个字符。默认值：The user asked to take over the browser.

cURL

curl https://lovelyrouter.com/v1/browser/runs/brun_5b7d9f1a3c5e7a9b1d3f5a7c/takeover \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"instructions": "I will pick the delivery slot myself."}'

停止运行#

POST/v1/browser/runs/{id}/stop

停止一次运行。运行会在下一个步骤边界以 stopped 结束；如果正在等待人工，则立即结束。返回 202 和停止前的运行对象；下一次查询状态时显示 stopped。被停止的运行按已执行的步数付费，且不返回 data。

cURL

curl -X POST https://lovelyrouter.com/v1/browser/runs/brun_3f9a1c7e0b2d4e6f8a9b0c1d/stop \
  -H "Authorization: Bearer $LOVELY_API_KEY"

获取截图#

GET/v1/browser/runs/{id}/screenshot

返回浏览器的 JPEG 截图（image/jpeg）。运行的浏览器处于打开状态时，返回当前画面；否则返回最近保存的一张：暂停等待人工开始时的页面，或已结束运行的最终页面。needs.screenshot 中保存的就是这个路径。没有截图时返回 404 和 No screenshot yet。要持续观看屏幕，请使用 screen=1 流式获取运行。

cURL

curl https://lovelyrouter.com/v1/browser/runs/brun_5b7d9f1a3c5e7a9b1d3f5a7c/screenshot \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -o screen.jpg

保存密钥#

PUT/v1/browser/vault/{name}

保存一个只写密钥，或替换同名的密钥。智能体只能在列出的源（origin）上输入它，模型永远看不到它。参见登录、密钥与配置文件。

路径参数

namestring必填

1 到 64 个字符：小写 a-z、0-9、_、.、-，必须以字母或数字开头。

请求体参数

valuestring必填

密钥值，最大 4 KB（超出返回 413）。对于 totp：base32 种子（16 个及以上由 A-Z、2-7 组成的字符）。

kindstring默认 password

password（仅限密码字段）、username 或 text（文本类字段，不含密码字段），或 totp（以当前的 6 位验证码输入）。

originsarray必填

1 到 20 个源，例如 https://github.com 或 https://*.example.com。仅限 https，http://localhost 和 http://127.0.0.1 除外。

cURL

curl -X PUT https://lovelyrouter.com/v1/browser/vault/github_password \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"value": "correct-horse-battery-staple", "kind": "password", "origins": ["https://github.com"]}'

Response

{ "name": "github_password", "kind": "password", "origins": ["https://github.com"], "stored": true }

列出密钥#

GET/v1/browser/vault

按名称列出你的密钥，不含值。

cURL

curl https://lovelyrouter.com/v1/browser/vault \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "name": "github_password",
      "kind": "password",
      "origins": ["https://github.com"],
      "created_at": "2026-10-11T09:00:00.000Z",
      "updated_at": "2026-10-11T09:00:00.000Z",
      "last_used_at": "2026-10-11T09:12:31.000Z"
    }
  ]
}

删除密钥#

DELETE/v1/browser/vault/{name}

删除一个密钥。列出了该密钥的运行将无法再输入它。密钥不存在时返回 404 和 No such secret。

cURL

curl -X DELETE https://lovelyrouter.com/v1/browser/vault/github_password \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Response

{ "deleted": "github_password" }

上传文件#

PUT/v1/browser/files/{name}

上传一个智能体可附加到表单中的文件，或替换同名文件（保留其 id）。以原始字节作为请求体发送，并用 Content-Type 指明文件类型。参见文件上传。

路径与查询参数

namestring必填

位于路径中，需 URL 编码。1 到 128 个字符：字母、数字、空格和 . _ - ( ) + ,，必须以字母、数字或 _ 开头。

descriptionstring

查询参数。说明文件是什么，帮助智能体做出选择。最多 300 个字符。

每个文件最大 10 MB（超出返回 413），每个账户最多 100 个文件（超出返回 409 file limit reached (100); delete some first）。

cURL

curl -X PUT "https://lovelyrouter.com/v1/browser/files/Maria_Garcia_CV_2026.pdf?description=Resume" \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/pdf" \
  --data-binary @Maria_Garcia_CV_2026.pdf

Response

{
  "id": "file_7a3c9e1b5d2f8a4c6e0b",
  "name": "Maria_Garcia_CV_2026.pdf",
  "mime": "application/pdf",
  "bytes": 84213,
  "sha256": "5f2b8c…",
  "description": "Resume",
  "created_at": "2026-10-11T09:20:44.000Z",
  "last_used_at": null
}

通过表单上传文件#

POST/v1/browser/files

与上传文件相同，但使用 multipart/form-data。返回相同的文件对象。

表单字段

filefile必填

文件本身。其类型取自该 part 的 content type。

namestring

保存时使用的名称。默认为上传文件的文件名。

descriptionstring

说明文件是什么。最多 300 个字符。

cURL

curl https://lovelyrouter.com/v1/browser/files \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -F "file=@Maria_Garcia_CV_2026.pdf;type=application/pdf" \
  -F "description=Resume"

列出文件#

GET/v1/browser/files

列出你已上传的文件，按名称排序。last_used_at 是最近一次有运行附加该文件的时间。

cURL

curl https://lovelyrouter.com/v1/browser/files \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "id": "file_7a3c9e1b5d2f8a4c6e0b",
      "name": "Maria_Garcia_CV_2026.pdf",
      "mime": "application/pdf",
      "bytes": 84213,
      "sha256": "5f2b8c…",
      "description": "Resume",
      "created_at": "2026-10-11T09:20:44.000Z",
      "last_used_at": "2026-10-11T09:47:10.000Z"
    }
  ]
}

删除文件#

DELETE/v1/browser/files/{name}

按名称或 id 删除文件。文件不存在时返回 404 和 No such file。

cURL

curl -X DELETE https://lovelyrouter.com/v1/browser/files/Maria_Garcia_CV_2026.pdf \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Response

{ "deleted": "Maria_Garcia_CV_2026.pdf" }

列出配置文件#

GET/v1/browser/profiles

列出你保存的会话，最近更新的在前。运行通过 save_profile 创建或更新配置文件，通过 profile 从某个配置文件开始。origins 是该配置文件保存了 Cookie 或本地存储的网站；bytes 是它的大小。

cURL

curl https://lovelyrouter.com/v1/browser/profiles \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Response

{
  "object": "list",
  "data": [
    {
      "id": "prof_4c1e9a7b2d0f3e5a8b6c",
      "name": "shop-login",
      "origins": ["https://shop.example.com"],
      "bytes": 18342,
      "created_at": "2026-10-10T16:02:11.000Z",
      "updated_at": "2026-10-11T09:15:40.000Z",
      "last_used_at": "2026-10-11T09:14:58.000Z"
    }
  ]
}

删除配置文件#

DELETE/v1/browser/profiles/{id}

按 id 或名称删除配置文件。配置文件不存在时返回 404 和 No such profile。

cURL

curl -X DELETE https://lovelyrouter.com/v1/browser/profiles/shop-login \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Response

{ "deleted": "shop-login" }

错误#

出错时返回一个 JSON 响应体，包含 type 和便于阅读的 message。消息会指出出错的字段。另请参阅错误。

状态码	`type`	触发条件
`400`	`invalid_request_error`	请求体或参数无效，例如 `"goal" is required (max 4,000 characters)`、`Unknown vault secret(s): …`、`Unknown file(s): …`、`Unknown profile "…"`。
`401`	`authentication_error`	API 密钥缺失、无效、已吊销或已过期。
`402`	`insufficient_quota`	余额低于运行的预留金额，或预留金额会超出密钥的消费上限。
`404`	`not_found`	你的账户中不存在该运行、密钥、文件、配置文件或截图。
`409`	`invalid_request_error`	运行没有在等待这种回复、已经结束，或你的文件已达 100 个上限。
`413`	`invalid_request_error`	文件超过 10 MB，或保险库密钥超过 4 KB。
`429`	`rate_limit_exceeded`	已有 10 个运行正在进行（浏览器智能体运行与数据工具运行合并计算）。
`502`	`tool_unavailable`	运行无法启动，不会收费，请重试。
`503`	`tool_unavailable`	浏览器智能体暂时不可用。

Error

{
  "error": {
    "type": "invalid_request_error",
    "message": "\"start_url\" must be an http(s) URL"
  }
}