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

> 来自 @hitheo/sdk 的托管无头浏览器会话。创建、查看、刷新、嵌入并结束会话，全程使用完整类型化的响应。

`theo.browser` 命名空间封装了 Theo Browser REST API。每个方法都返回强类型响应，失败时抛出 `TheoApiError`。

## 快速示例

```typescript theme={null}
import { Theo } from "@hitheo/sdk";

const theo = new Theo({ apiKey: process.env.THEO_API_KEY! });

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

console.log(session.live_view_url); // raw BrowserBase URL
console.log(session.embed_url);     // Theo-branded embed URL

// 2. 断开连接后刷新实时 URL
const live = await theo.browser.live(session.session_id, { force: true });
console.log(live.live_view_version); // monotonic — rekey your iframe on advance

// 3. 结束会话
await theo.browser.end(session.session_id);
```

## 方法

### `theo.browser.create(request?)`

创建一个新的托管浏览器会话。返回 `BrowserSessionHandle`。

```typescript theme={null}
const session = await theo.browser.create({
  url: "https://example.com",     // optional starting URL
  keep_alive: false,              // default: false
  proxies: false,                 // default: false (residential proxy pool)
  region: "us-west-2",            // default: us-west-2
});
```

### `theo.browser.list()`

列出调用方当前所有活跃的会话。返回 `BrowserSessionSnapshot[]`。

### `theo.browser.get(id)`

查看单个会话的详情。返回 `BrowserSessionSnapshot` —— 包含当前页面的 URL/标题/favicon，以及一个新生成的 `embed_url`（有效期 1 小时）。

### `theo.browser.live(id, options?)`

刷新可嵌入 iframe 的实时视图 URL。返回 `BrowserLiveView`。

在嵌入的 iframe 发送 `browserbase-disconnected` 消息后传入 `{ force: true }`，这样返回的 URL 会立即指向新的 CDP 页面 id。

### `theo.browser.end(id)`

结束会话并停止计费。返回 `BrowserEndResult`，其中包含最终时长、代理流量字节数以及费用。

## 类型

```typescript theme={null}
export interface BrowserSessionHandle {
  session_id: string;
  live_view_url: string | null;
  embed_url?: string | null;
  region: BrowserRegion;
  keep_alive: boolean;
  started_at: string;
  expires_at: string;
}

export interface BrowserSessionSnapshot extends BrowserSessionHandle {
  current_url?: string | null;
  current_title?: string | null;
  favicon_url?: string | null;
  last_active_at?: string;
  proxies?: boolean;
}

export interface BrowserLiveView {
  session_id: string;
  live_view_url: string;
  live_view_version: number;
  pages: Array<{
    id: string;
    url: string;
    title: string;
    favicon_url: string;
  }>;
}

export interface BrowserEndResult {
  session_id: string;
  duration_seconds: number;
  proxy_bytes: number;
  cost_cents: number;
}
```

## 相关内容

* [Browser Sessions API](/api-reference/browser/sessions) — REST endpoint reference
* [Embed the Theo Browser](/api-reference/browser/embed) — drop-in iframe integration


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