AI浏览器 API接口调用教程｜附配置文件

随着大模型能力不断增强，“AI浏览器”逐渐成为很多企业和开发者关注的工具。它不仅可以像普通浏览器一样访问网页，还可以结合 AI 能力完成网页理解、自动检索、内容摘要、表单填写、数据采集、页面操作、自动化测试等任务。对于开发者而言，真正能让 AI 浏览器发挥价值的方式，往往不是手动使用界面，而是通过 API 接口调用 将其接入自己的业务系统、工作流或自动化脚本中。

本文将以通用的 AI 浏览器 API 调用方式为例，系统讲解接口调用流程、鉴权方式、请求参数、配置文件写法、常见调用示例以及开发中的注意事项。你可以根据实际使用的 AI 浏览器产品，对接口地址、模型名称和参数字段做少量调整。

一、什么是 AI 浏览器 API？

AI浏览器 API 可以理解为一个支持“浏览器自动化 + AI理解能力”的服务接口。传统浏览器自动化工具，例如 Selenium、Playwright，主要负责打开网页、点击按钮、输入文本、截图、获取 DOM 等操作；而 AI浏览器 API 则在此基础上增加了大模型能力，可以通过自然语言指令完成更加复杂的任务。

例如，你可以通过 API 发送这样的任务：

打开目标网站，搜索“2024年人工智能发展报告”，总结前三篇文章的核心观点。

AI浏览器服务会自动完成以下步骤：

1. 启动浏览器环境；
2. 访问指定网页或搜索引擎；
3. 理解页面结构和内容；
4. 自动点击、滚动、搜索、打开页面；
5. 提取关键信息；
6. 返回结构化结果。

这种能力非常适合以下场景：

• 自动化信息检索；
• 电商商品信息采集；
• 网页内容摘要；
• 竞品监控；
• SEO数据分析；
• 表单自动填写；
• 自动化测试；
• 企业内部知识检索；
• 多网页任务代理。

二、调用 AI浏览器 API 前的准备工作

在正式调用接口之前，通常需要完成以下准备。

1. 获取 API Key

大多数 AI浏览器服务都会通过 API Key 进行身份认证。你需要登录服务商后台，在“开发者中心”“API管理”或“密钥管理”页面创建密钥。

拿到密钥后，一般会得到类似下面的字符串：

sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

建议不要把 API Key 直接写死在代码中，更安全的方式是放在环境变量或配置文件中，并确保不要提交到 Git 仓库。

2. 确认 API Base URL

接口基础地址通常类似：

https://api.example.com/v1

在本文示例中，我们假设 AI浏览器 API 的基础地址为：

https://api.aibrowser.example.com/v1

实际使用时，请替换成你所使用平台提供的真实地址。

3. 确认主要接口

一个典型的 AI浏览器 API 通常至少包含以下接口：

不同产品命名可能不同，但核心思路基本一致。

三、API 鉴权方式

常见的鉴权方式是通过 HTTP Header 传递 Bearer Token。

示例：

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

使用 curl 请求时，可以这样写：

curl -X POST "https://api.aibrowser.example.com/v1/browser/tasks" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "打开百度，搜索AI浏览器API调用教程，并总结前3个结果",
    "mode": "agent"
  }'

其中：

• Authorization 用于身份验证；
• Content-Type 表示请求体格式为 JSON；
• instruction 是你希望 AI浏览器执行的自然语言任务；
• mode 可以表示执行模式，例如代理模式、只读模式、自动操作模式等。

四、推荐项目目录结构

如果你准备在项目中集成 AI浏览器 API，可以采用如下目录结构：

ai-browser-demo/
├── config/
│   ├── config.yaml
│   └── config.example.yaml
├── src/
│   ├── client.py
│   ├── task.py
│   └── main.py
├── logs/
│   └── app.log
├── .env
├── requirements.txt
└── README.md

各文件作用如下：

五、配置文件示例

下面是一个完整的配置文件示例。实际使用时，你可以根据服务商文档调整字段。

1. config/config.example.yaml

api:
  base_url: "https://api.aibrowser.example.com/v1"
  timeout: 60
  retry: 3

browser:
  headless: true
  viewport:
    width: 1440
    height: 900
  locale: "zh-CN"
  timezone: "Asia/Shanghai"
  user_agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"

ai:
  model: "browser-agent-v1"
  temperature: 0.2
  max_steps: 20
  max_tokens: 4096

task:
  default_mode: "agent"
  save_screenshot: true
  return_markdown: true

log:
  level: "INFO"
  file: "logs/app.log"

2. .env 示例

AI_BROWSER_API_KEY=sk-your-api-key-here
AI_BROWSER_BASE_URL=https://api.aibrowser.example.com/v1

注意：.env 文件通常包含敏感信息，不建议提交到代码仓库。你可以在 .gitignore 中加入：

.env
config/config.yaml
logs/

六、Python 调用示例

下面使用 Python 演示如何调用 AI浏览器 API。首先安装依赖：

pip install requests python-dotenv pyyaml

也可以将依赖写入 requirements.txt：

requests>=2.31.0
python-dotenv>=1.0.0
PyYAML>=6.0.1

1. 封装 API 客户端

创建 src/client.py：

import os
import time
import requests
from dotenv import load_dotenv

load_dotenv()


class AIBrowserClient:
    def __init__(self, base_url=None, api_key=None, timeout=60, retry=3):
        self.base_url = base_url or os.getenv("AI_BROWSER_BASE_URL")
        self.api_key = api_key or os.getenv("AI_BROWSER_API_KEY")
        self.timeout = timeout
        self.retry = retry

        if not self.base_url:
            raise ValueError("缺少 AI_BROWSER_BASE_URL")
        if not self.api_key:
            raise ValueError("缺少 AI_BROWSER_API_KEY")

    def _headers(self):
        return {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }

    def request(self, method, path, json=None):
        url = f"{self.base_url}{path}"

        last_error = None

        for i in range(self.retry):
            try:
                response = requests.request(
                    method=method,
                    url=url,
                    headers=self._headers(),
                    json=json,
                    timeout=self.timeout
                )

                if response.status_code >= 400:
                    raise RuntimeError(
                        f"API请求失败：{response.status_code}, {response.text}"
                    )

                return response.json()

            except Exception as e:
                last_error = e
                if i < self.retry - 1:
                    time.sleep(1.5 * (i + 1))

        raise last_error

这个客户端主要做了几件事：

1. 从环境变量读取 API Key 和 Base URL；
2. 统一封装请求头；
3. 支持超时时间配置；
4. 支持简单重试；
5. 对错误状态码进行异常抛出。

2. 创建浏览器任务

创建 src/task.py：

from client import AIBrowserClient


class BrowserTaskService:
    def __init__(self, client: AIBrowserClient):
        self.client = client

    def create_task(self, instruction, url=None, mode="agent"):
        payload = {
            "instruction": instruction,
            "mode": mode,
            "url": url,
            "options": {
                "return_markdown": True,
                "save_screenshot": True,
                "max_steps": 20
            }
        }

        return self.client.request(
            method="POST",
            path="/browser/tasks",
            json=payload
        )

    def get_task(self, task_id):
        return self.client.request(
            method="GET",
            path=f"/browser/tasks/{task_id}"
        )

这里封装了两个方法：

• create_task()：创建一个新的 AI浏览器任务；
• get_task()：根据任务 ID 查询执行状态和结果。

3. 编写主程序

创建 src/main.py：

import time
from client import AIBrowserClient
from task import BrowserTaskService


def main():
    client = AIBrowserClient()
    service = BrowserTaskService(client)

    result = service.create_task(
        url="https://www.example.com",
        instruction="请访问该网站首页，提取页面标题、主要导航栏目和正文摘要。",
        mode="agent"
    )

    task_id = result.get("task_id")

    if not task_id:
        print("创建任务失败：", result)
        return

    print("任务已创建，task_id =", task_id)

    while True:
        task = service.get_task(task_id)
        status = task.get("status")

        print("当前状态：", status)

        if status in ["completed", "failed", "cancelled"]:
            print("任务结果：")
            print(task)
            break

        time.sleep(3)


if __name__ == "__main__":
    main()

运行：

python src/main.py

如果调用成功，你可能会得到类似结果：

{
  "task_id": "task_123456",
  "status": "completed",
  "result": {
    "title": "Example Domain",
    "summary": "该页面是一个示例域名页面，用于文档示例。",
    "links": [
      {
        "text": "More information",
        "url": "https://www.iana.org/domains/example"
      }
    ],
    "markdown": "# Example Domain\n\nThis domain is for use in illustrative examples..."
  }
}

七、JavaScript / Node.js 调用示例

如果你的项目使用 Node.js，也可以用 fetch 或 axios 调用。

安装依赖：

npm install axios dotenv

创建 .env：

AI_BROWSER_API_KEY=sk-your-api-key-here
AI_BROWSER_BASE_URL=https://api.aibrowser.example.com/v1

示例代码：

import axios from "axios";
import dotenv from "dotenv";

dotenv.config();

const apiKey = process.env.AI_BROWSER_API_KEY;
const baseURL = process.env.AI_BROWSER_BASE_URL;

const client = axios.create({
  baseURL,
  timeout: 60000,
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
});

async function createTask() {
  const response = await client.post("/browser/tasks", {
    url: "https://www.example.com",
    instruction: "请访问该网站，并提取页面标题、主要内容和所有外部链接。",
    mode: "agent",
    options: {
      return_markdown: true,
      save_screenshot: true,
      max_steps: 20,
    },
  });

  return response.data;
}

async function getTask(taskId) {
  const response = await client.get(`/browser/tasks/${taskId}`);
  return response.data;
}

async function main() {
  const created = await createTask();
  const taskId = created.task_id;

  console.log("任务已创建：", taskId);

  while (true) {
    const task = await getTask(taskId);
    console.log("当前状态：", task.status);

    if (["completed", "failed", "cancelled"].includes(task.status)) {
      console.log("最终结果：", JSON.stringify(task, null, 2));
      break;
    }

    await new Promise((resolve) => setTimeout(resolve, 3000));
  }
}

main().catch(console.error);

八、常见参数说明

不同 AI浏览器产品的参数不完全一样，但通常会包含以下几类。

1. 基础参数

2. 浏览器参数

3. AI参数

九、结构化数据提取示例

AI浏览器 API 的一个重要用途是从网页中提取结构化数据。例如，你希望从新闻网页中提取标题、发布时间、作者和正文摘要，可以发送如下请求：

{
  "url": "https://news.example.com/article/123",
  "instruction": "请提取该新闻页面的结构化信息。",
  "mode": "read_only",
  "options": {
    "extract_schema": {
      "title": "文章标题",
      "author": "作者",
      "publish_time": "发布时间",
      "summary": "200字以内摘要",
      "keywords": "关键词数组"
    }
  }
}

返回结果可能如下：

{
  "task_id": "task_news_001",
  "status": "completed",
  "result": {
    "title": "人工智能行业加速发展",
    "author": "张三",
    "publish_time": "2024-06-01 10:30:00",
    "summary": "本文介绍了人工智能行业在模型、算力、应用落地等方面的最新进展。",
    "keywords": ["人工智能", "大模型", "产业应用"]
  }
}

结构化提取的好处是结果更容易被程序消费，比如可以直接写入数据库、同步到知识库、生成报表或触发后续工作流。

十、会话模式与任务模式的区别

很多 AI浏览器 API 会提供两种调用方式：任务模式 和 会话模式。

1. 任务模式

任务模式适合一次性请求。你发送一条指令，系统完成后返回结果。

适用场景：

• 提取某个网页内容；
• 总结某篇文章；
• 查询一次搜索结果；
• 执行简单页面操作。

优点是简单直接，不需要维护状态。

2. 会话模式

会话模式会创建一个可持续存在的浏览器上下文。你可以连续发送多条指令，AI浏览器会保留 Cookie、登录状态、页面上下文等信息。

适用场景：

• 需要登录后操作；
• 多步骤业务流程；
• 连续搜索和比对；
• 长时间监控网页变化；
• 自动化后台管理操作。

示例流程：

POST /browser/sessions
POST /browser/sessions/{session_id}/commands
POST /browser/sessions/{session_id}/commands
DELETE /browser/sessions/{session_id}

创建会话请求示例：

{
  "browser": {
    "headless": true,
    "locale": "zh-CN",
    "viewport": {
      "width": 1440,
      "height": 900
    }
  }
}

发送命令示例：

{
  "instruction": "打开后台系统登录页，输入用户名和密码并登录。",
  "sensitive_inputs": {
    "username": "your_username",
    "password": "your_password"
  }
}

在涉及账号密码时，建议使用专门的敏感字段传递，避免明文出现在日志中。

十一、错误处理与重试机制

实际开发中，API 调用可能会失败。常见错误包括：

推荐实现指数退避重试：

import time

def sleep_with_backoff(attempt):
    delay = min(2 ** attempt, 30)
    time.sleep(delay)

对于非幂等操作，例如提交订单、发布内容、删除数据，不建议盲目重试。可以通过业务唯一 ID 或幂等键来避免重复执行。

十二、安全与合规注意事项

调用 AI浏览器 API 时，安全问题非常重要，尤其是当任务涉及登录、采集、提交表单或处理用户数据时。

1. 不要泄露 API Key

避免将密钥写入前端代码、公开仓库、日志系统或错误堆栈中。建议使用：

• 环境变量；
• 密钥管理服务；
• CI/CD Secret；
• 后端代理服务。

2. 控制 AI 的操作权限

如果 AI浏览器可以点击按钮、提交表单、删除数据，就必须设置权限边界。例如：

• 对高风险操作增加人工确认；
• 使用只读模式访问敏感页面；
• 限制可访问域名；
• 禁止自动提交支付、删除、发布等动作；
• 对所有操作保留审计日志。

3. 遵守网站规则

在使用 AI浏览器进行网页访问或数据提取时，应遵守目标网站的服务条款、robots 协议以及相关法律法规。不要绕过登录权限、验证码、付费墙或访问控制。

4. 保护用户隐私

如果任务中包含用户姓名、手机号、邮箱、地址、订单信息等个人数据，需要做好脱敏、加密和访问控制。

十三、最佳实践

为了让 AI浏览器 API 在生产环境中稳定运行，建议遵循以下实践。

1. 指令要清晰

不要只写：

帮我看看这个网站。

更好的写法是：

请访问该网站首页，提取页面标题、主要导航栏目、核心产品介绍，并用JSON格式返回。

指令越明确，返回结果越稳定。

2. 尽量使用结构化输出

如果后续程序需要处理结果，建议要求 API 返回 JSON，而不是自然语言大段文本。

例如：

请以JSON格式返回，字段包括：title、summary、links。

3. 限制最大步骤数

AI浏览器自动操作网页时，可能会因为页面复杂、弹窗、加载失败等原因执行过多步骤。设置 max_steps 可以避免任务失控。

4. 对结果进行校验

即使 AI 返回了结构化数据，也建议在代码中进行字段校验。例如：

• 必填字段是否存在；
• URL 是否合法；
• 数字字段是否为数字；
• 日期格式是否正确；
• 结果是否为空。

5. 保存关键日志

建议记录以下信息：

• 请求时间；
• task_id；
• 任务指令；
• 状态变化；
• 错误信息；
• 执行耗时；
• 结果摘要。

但不要记录 API Key、密码、Token 等敏感信息。

十四、完整配置文件参考

最后给出一个更完整的 config.yaml，适合在正式项目中使用：

api:
  base_url: "https://api.aibrowser.example.com/v1"
  timeout: 90
  retry:
    max_attempts: 3
    backoff_seconds: 2

auth:
  api_key_env: "AI_BROWSER_API_KEY"

browser:
  headless: true
  locale: "zh-CN"
  timezone: "Asia/Shanghai"
  viewport:
    width: 1440
    height: 900
  proxy:
    enabled: false
    server: ""
    username: ""
    password: ""

ai:
  model: "browser-agent-v1"
  temperature: 0.2
  max_steps: 25
  max_tokens: 4096

task:
  mode: "agent"
  return_markdown: true
  save_screenshot: true
  allowed_domains:
    - "example.com"
    - "news.example.com"
  blocked_actions:
    - "payment"
    - "delete"
    - "publish"

output:
  format: "json"
  save_to_file: true
  directory: "outputs"

log:
  level: "INFO"
  file: "logs/app.log"
  mask_sensitive: true

这个配置文件将 API、浏览器、AI模型、任务、安全限制、输出和日志分开管理，便于维护和扩展。

十五、总结

AI浏览器 API 的核心价值在于把“浏览器操作”和“AI理解能力”结合起来，让程序可以通过自然语言指令完成复杂网页任务。相比传统爬虫或自动化脚本，它更适合处理页面结构变化频繁、操作步骤复杂、需要理解网页内容的场景。

在实际接入时，建议按照以下流程进行：

1. 获取 API Key；
2. 配置 Base URL 和环境变量；
3. 封装统一请求客户端；
4. 创建浏览器任务；
5. 轮询任务状态；
6. 获取结构化结果；
7. 增加错误处理和重试；
8. 做好安全、权限和日志管理。

如果只是做简单测试，可以直接使用 curl 或 Postman 调用；如果要接入生产系统，建议封装 SDK 层，统一管理配置、鉴权、异常、日志和任务状态。这样不仅代码更清晰，也更方便后续扩展和维护。