> ## 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.