> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitheo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 浏览器会话

> 创建、查看、刷新和结束 Theo 浏览器会话——支持 iframe 嵌入式实时视图的无头浏览器自动化。

Theo Browser 为你的应用提供一个受管理的无头 Chromium 会话，LLM 智能体可以通过自然语言工具（`browser_navigate`、`browser_act`、`browser_extract`、`browser_observe`、`browser_screenshot`）来驱动它，并通过**可 iframe 嵌入的实时视图**将会话呈现出来，让你的用户可以实时观看（或接管）。

以下四个端点均限定于调用者的 API 密钥范围，并受 `connectors` 权限范围限制。会话默认硬性上限为 20 分钟，并在空闲超时后自动关闭（可通过 `THEO_BROWSER_SESSION_MAX_SECONDS` / `THEO_BROWSER_SESSION_IDLE_SECONDS` 配置）。

## 端点

| 方法 | 路径 | 用途 |
| - | - | - |
| `POST` | `/api/v1/browser/sessions` | 创建新会话（返回可直接用于 iframe 的实时视图 + 嵌入 URL） |
| `GET` | `/api/v1/browser/sessions` | 列出活跃会话 |
| `GET` | `/api/v1/browser/sessions/:id` | 查看单个会话 |
| `GET` | `/api/v1/browser/sessions/:id/live` | 刷新实时视图 URL（支持 `?force=1`） |
| `DELETE` | `/api/v1/browser/sessions/:id` | 结束会话（停止计费） |

## 创建会话

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://www.hitheo.ai/api/v1/browser/sessions \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://news.ycombinator.com",
      "keep_alive": false,
      "proxies": false,
      "region": "us-west-2"
    }'
  ```

  ```typescript SDK theme={null}
  import { Theo } from "@hitheo/sdk";
  const theo = new Theo({ apiKey: process.env.THEO_API_KEY! });

  const session = await theo.browser.create({
    url: "https://news.ycombinator.com",
    keep_alive: false,
    region: "us-west-2",
  });

  console.log(session.live_view_url); // 直接用于 iframe
  console.log(session.embed_url);     // 或用于带 Theo 品牌外壳的 iframe
  ```
</CodeGroup>

### 请求体

<ParamField body="url" type="string">
  可选的起始 URL。会话启动后会立即导航到该地址，因此第一个实时视图 URL 就已指向真实页面（避免 `about:blank` 目标绑定问题）。
</ParamField>

<ParamField body="keep_alive" type="boolean" default="false">
  在智能体断开连接后仍保持会话存活。如果你之后需要重新连接 Stagehand，则必须设置此项。
</ParamField>

<ParamField body="proxies" type="boolean" default="false">
  通过 Theo 的住宅代理池路由流量。按 MB 计费更高。
</ParamField>

<ParamField body="region" type="string" default="us-west-2">
  数据中心区域：`us-west-2` · `us-east-1` · `eu-central-1` · `ap-southeast-1`。
</ParamField>

### 响应（201）

```json theme={null}
{
  "session_id": "bb_sess_abc123",
  "live_view_url": "https://www.browserbase.com/devtools/inspector.html?wss=...&debug=true",
  "live_view_version": 1,
  "embed_url": "https://hitheo.ai/embed/browser/bb_sess_abc123?token=...",
  "embed_token_expires_at": "2026-04-10T13:00:00Z",
  "region": "us-west-2",
  "keep_alive": false,
  "started_at": "2026-04-10T12:00:00Z",
  "expires_at": "2026-04-10T12:20:00Z"
}
```

<Note>
  **`embed_url` 是零配置路径。** 直接将它放入你自己产品中的 `<iframe src="...">`，即可获得带 Theo 品牌的浏览器窗口（地址栏、实时状态指示、重连界面），无需任何 SDK 集成。该令牌是短期有效的——请从你的后端调用 `GET /:id` 来获取一个新的令牌。
</Note>

## 刷新实时视图 URL

BrowserBase 的调试器 URL 固定指向某个特定的 CDP 页面目标。当智能体进行导航、点击打开新标签页，或页面销毁了其目标时，嵌入的 WebSocket 连接会断开。Theo 会在每次智能体工具调用后自动强制刷新——但你自己的界面也应支持按需刷新：

<CodeGroup>
  ```bash curl theme={null}
  curl https://www.hitheo.ai/api/v1/browser/sessions/bb_sess_abc123/live?force=1 \
    -H "Authorization: Bearer $THEO_API_KEY"
  ```

  ```typescript SDK theme={null}
  const refreshed = await theo.browser.live("bb_sess_abc123", { force: true });
  // refreshed.live_view_version 是单调递增的——每当它增加时就应重新为
  // iframe 生成新 key，即使 live_view_url 看起来相同。
  ```
</CodeGroup>

**为什么 `live_view_version` 很重要。** 当 iframe 触发 `browserbase-disconnected` postMessage 时，应带 `?force=1` 重新获取。上游服务商可能返回相同的 URL 字符串，但在背后悄悄替换了底层的页面目标。请使用 `live_view_version`（而不是 URL 相等性判断）来决定何时应为 iframe 重新生成 key。

### 响应

```json theme={null}
{
  "session_id": "bb_sess_abc123",
  "live_view_url": "https://www.browserbase.com/devtools/inspector.html?wss=...&debug=true",
  "live_view_version": 4,
  "pages": [
    {
      "id": "79B2FCDA9D8DE8B841B451C1B4DA5277",
      "url": "https://news.ycombinator.com/item?id=123",
      "title": "Claude Design | Hacker News",
      "favicon_url": "https://news.ycombinator.com/favicon.ico"
    }
  ]
}
```

## 列出活跃会话

```bash theme={null}
curl https://www.hitheo.ai/api/v1/browser/sessions \
  -H "Authorization: Bearer $THEO_API_KEY"
```

返回 `{ sessions: BrowserSessionSnapshot[] }`——与 `GET /:id` 中单个会话的结构相同。

## 查看会话

```bash theme={null}
curl https://www.hitheo.ai/api/v1/browser/sessions/bb_sess_abc123 \
  -H "Authorization: Bearer $THEO_API_KEY"
```

每次调用都会生成一个全新的 `embed_url`（有效期 1 小时），因此长时间运行的仪表盘可以不断重新发起 iframe，而无需创建新的会话。

## 结束会话

```bash theme={null}
curl -X DELETE https://www.hitheo.ai/api/v1/browser/sessions/bb_sess_abc123 \
  -H "Authorization: Bearer $THEO_API_KEY"
```

### 响应

```json theme={null}
{
  "session_id": "bb_sess_abc123",
  "duration_seconds": 142,
  "proxy_bytes": 0,
  "cost_cents": 4
}
```

<Warning>
  请始终显式结束会话。空闲/最长时长清理器最终会关闭它们，但在此之前，你会按已经过的实际时长被计费。
</Warning>

## 错误

| 状态码 | 代码 | 说明 |
| - | - | - |
| 400 | `url_blocked` | 起始 URL 未通过 SSRF / 允许列表校验 |
| 401 | `invalid_api_key` | API 密钥缺失或无效 |
| 404 | `session_not_found` | 未知的会话 ID（或不属于调用者） |
| 404 | `live_view_unavailable` | 会话已结束或从未生成实时 URL |
| 429 | `browser_session_limit` | 达到每用户并发上限（默认：3） |
| 501 | `browser_unconfigured` | 该部署未配置 BrowserBase 凭据 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.