AdsCrawl 设置：从 API 密钥到首次浏览器请求

AdsCrawl 将真实的浏览器操作转化为统一的 API。您无需自行管理无头 Chrome、代理和重试逻辑，只需发送请求即可获得截图、提取的 HTML、Markdown 或实时 Chrome DevTools 协议（CDP）会话。本指南将带您完成完整的设置路径：创建账户、生成 API 密钥、发出首次经过身份验证的请求、配置浏览器行为，并通过远程 CDP 控制进入生产环境。

设置过程有意保持简短。如果您严格遵循请求格式，从注册到完成可用的截图请求不到十分钟。

开始前需要准备什么

AdsCrawl 是一个 HTTP API，因此要求极简：

• 一个具有有效 API 密钥的 AdsCrawl 账户
• 一个可以发送 HTTP 请求的工具：cURL、Postman、Node.js 或 Python
• 一个可访问的 HTTP(S) URL 用于测试
• 对 JSON 请求体的基本熟悉

无需安装浏览器、WebDriver 二进制文件或本地 Chrome 实例。平台在服务端管理浏览器会话、代理和 User-Agent 轮换。

第 1 步：创建账户和 API 密钥

AdsCrawl 设置：从 API 密钥到首次浏览器请求 - 第 1 步：创建账户和 API 密钥。

第一个设置任务是创建账户。注册后，打开仪表盘并导航到密钥管理部分。仪表盘也是您跟踪信用使用情况、查看失败任务和调试请求负载的地方。

创建一个完整的 API 密钥并将其存储在安全的地方。该密钥在每次请求中作为 x-api-key 标头发送。请像对待密码一样对待它：不要将其提交到公共仓库，如果泄露请轮换。

如果您已有账户但无法访问仪表盘，AdsCrawl 登录指南 涵盖了登录步骤、密钥管理和常见的身份验证故障排除。

第 2 步：理解请求契约

每个浏览器任务都使用相同的信封：

• 方法： POST
• 基础 URL： https://api.adscrawl.net
• 标头： x-api-key 和 content-type: application/json
• 请求体： 包含必填 url 字段以及可选浏览器配置的 JSON

每次调用都必须包含 x-api-key 标头。缺失或无效的密钥返回 401。请求体必须是有效的 JSON；格式错误的负载返回 400。

必填和常见字段

选择合适的 waitUntil 值

waitUntil 控制浏览器何时认为导航完成：

• domcontentloaded 等待 HTML 解析完成，不等待次要资源。当不需要图片和样式表时，用于快速 HTML 提取。
• load 等待窗口加载事件，包括依赖资源。这是默认值，也是一个不错的通用选择。
• networkidle 等待至少 500 毫秒内没有网络连接。用于 JavaScript 密集型页面，但请注意，长轮询、分析或延迟加载的内容可能导致超时。

第 3 步：发出首次截图请求

从一个简单的 cURL 调用开始，以验证身份验证和连接性：

curl -sS -X POST "https://api.adscrawl.net/screenshot" \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "url": "https://example.com",
    "viewport": {"width": 1440, "height": 900},
    "fullPage": true,
    "waitUntil": "load",
    "countryCode": "GLOBAL",
    "userAgentMode": "random",
    "userAgentOs": "windows"
  }' \
  --output page.png

成功的响应返回 200 状态，带有 Content-Type: image/png 标头和二进制 PNG 流。打开 page.png 以确认捕获成功。

常见首次请求错误

第 4 步：提取 HTML 和 Markdown

截图捕获只是一个端点。对于数据提取，当您需要快速解析内容时，使用带有 waitUntil: "domcontentloaded" 的 HTML 端点：

curl -sS -X POST "https://api.adscrawl.net/html" \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "url": "https://example.com",
    "waitUntil": "domcontentloaded"
  }'

对于在客户端渲染内容的单页应用程序，切换到 networkidle 并添加充足的 timeoutMs。如果您只需要特定部分，传递 selector 以捕获第一个匹配的元素，而不是整个文档。

第 5 步：配置代理、区域设置和指纹

生产环境中的抓取通常需要区域出口点和一致的浏览器身份。AdsCrawl 支持多个配置层：

• countryCode：使用两个字母的区域代码以优先选择该区域的受信任代理，或使用 GLOBAL 从 15 个热门区域动态出口。省略该字段以使用随机受信任代理。
• locale 和 timezoneId：设置浏览器区域设置（如 en-US）和 IANA 时区（如 Asia/Shanghai）以匹配目标网站的期望。
• geolocation：当网站检查位置时，提供纬度和经度坐标。
• fingerprint：省略时，每个信号默认为随机，同时保持操作系统、GPU、CPU、内存、字体和设备信号的一致性。这减少了明显的自动化指纹。
• cookies：在导航前注入 Cookie 列表以跨请求维护会话状态。

自定义代理也通过 proxy 字段支持，但不能与 countryCode 结合使用。

第 6 步：迁移到远程 CDP 进行交互式控制

截图和 HTML 端点是同步计量请求。对于交互式工作流，远程 CDP 让您直接控制实时浏览器会话：

1. 使用您的 x-api-key 创建 CDP 会话。
2. 响应包含一个 cdpBaseUrl，其中嵌入了保护发现和 CDP WebSockets 的数据令牌。
3. 实时控制使用有效期为 30 秒的一次性 controlToken。
4. 将您首选的 CDP 客户端连接到 WebSocket 端点并直接驱动浏览器。

这对于需要实时点击、输入、滚动和观察页面状态的 AI 代理非常有用。会话管理端点还支持列出和删除活动会话。

第 7 步：使用 Python 或 Node.js 集成

大多数团队很快会超越 cURL。相同的请求契约适用于任何 HTTP 客户端。

Python 示例

import requests

API_KEY = "YOUR_API_KEY"

response = requests.post(
    "https://api.adscrawl.net/screenshot",
    headers={
        "content-type": "application/json",
        "x-api-key": API_KEY,
    },
    json={
        "url": "https://example.com",
        "viewport": {"width": 1440, "height": 900},
        "fullPage": True,
        "waitUntil": "load",
    },
)

if response.status_code == 200:
    with open("page.png", "wb") as f:
        f.write(response.content)
else:
    print(response.status_code, response.text)

Node.js 示例

const response = await fetch("https://api.adscrawl.net/html", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-api-key": process.env.ADSCRAWL_API_KEY,
  },
  body: JSON.stringify({
    url: "https://example.com",
    waitUntil: "domcontentloaded",
  }),
});

const html = await response.text();
console.log(html);

要更广泛地比较 AdsCrawl 与其他浏览器自动化方法的优劣，请参阅 AdsCrawl 与 axiom.ai 与 Playwright 对比。

第 8 步：在生产环境中验证您的设置

在扩展之前，运行一个简短的验证清单：

1. 身份验证有效：您的密钥在已知良好的 URL 上返回 200。
2. 错误处理到位：您的代码处理 401、402、429 和 5xx 响应，并带有重试或警报。
3. 超时策略经过深思熟虑：您根据页面类型选择 waitUntil 值，而不仅仅依赖默认值。
4. 信用受到监控：仪表盘显示使用情况和剩余余额。
5. 密钥受到保护：API 密钥存储在环境变量或密钥管理器中。

AdsCrawl 设置与自托管浏览器自动化对比

如果您正在决定使用 AdsCrawl 还是运行自己的浏览器集群，设置权衡是明确的：

当您想要 API 背后的浏览器功能而无需拥有基础设施时，AdsCrawl 是合理的。自托管框架提供更多控制，但需要持续维护。要更深入地了解每种方法何时胜出，Selenium 评论 涵盖了自托管框架的视角。

相关阅读

• AdsCrawl 下载：浏览器自动化 API 设置指南 - 了解如何下载、安装并开始使用 AdsCrawl 进行浏览器自动化、HTML 提取、截图和 CDP 控制。包含代码示例的设置指南。
• AdsCrawl 评论：针对 AI 代理测试的浏览器自动化 API - 动手实践 AdsCrawl 评论，涵盖浏览器自动化 API、截图、HTML 提取、CDP 控制、定价以及 AI 代理的真实性能。

来源和进一步阅读

• 关于浏览器自动化、采集工程和 AI 工作流的笔记 - 该博客分享产品实践、技术分解和现场笔记，面向使用真实浏览器构建数据工作流的团队。
• ‎闹钟 - 唤醒音乐应用 - 计划您的 24/7 日常时间

常见问题解答

如何获取我的 AdsCrawl API 密钥？

注册账户，打开仪表盘，在密钥管理部分创建一个完整的 API 密钥。在每次请求中使用该密钥作为 x-api-key 标头。

AdsCrawl API 请求的基础 URL 是什么？

基础 URL 是 https://api.adscrawl.net。端点如 /screenshot 和 /html 附加在此基础之上。

402 INSUFFICIENT_CREDITS 错误是什么意思？

您的账户余额不足以支付请求的任务。响应包含您当前的余额和所需信用。添加信用或升级您的计划以继续。

我可以将自定义代理与 countryCode 结合使用吗？

不可以。proxy 字段和 countryCode 字段互斥。每个请求选择一种路由方法。

CDP 控制令牌的有效期是多久？

用于实时 CDP 控制的一次性 controlToken 有效期为 30 秒。如果过期，请创建新会话或令牌。

请求体的最大大小是多少？

请求体限制为 1 MiB。更大的负载将被拒绝为无效 JSON，并返回 400 响应。

结论

AdsCrawl 设置遵循一个简单的模式：创建 API 密钥，发送包含目标 URL 和浏览器选项的 JSON 请求，并处理响应。主要决策是选择合适的 waitUntil 策略，为您的目标网站配置代理和指纹设置，以及决定何时从同步提取迁移到交互式 CDP 会话。

从一个截图请求开始以验证身份验证。然后随着工作流的成熟，添加 HTML 提取、区域路由和错误处理。有关更详细的端点文档和浏览器自动化的现场笔记，请参阅 AdsCrawl 文档 和 AdsCrawl 博客。