通过一次 API 调用捕获网站屏幕截图

您需要网页的屏幕截图。 也许您正在为聊天应用程序构建链接预览。 也许您正在 CI 中运行视觉回归测试。 也许您正在生成 PDF 报告 嵌入实时仪表板快照。 显而易见的答案是木偶师或剧作家 你的服务器。 明显的问题：无头 Chromium 二进制文件会占用 200-500 MB 内存， 冷启动需要 3-8 秒，需要操作系统级别的依赖关系，并转换您的 Docker 镜像 成 1 GB 工件。 所有这些都是为了以编程方式捕获网站屏幕截图。

有一条更简单的路径。 将 URL 发送到屏幕截图 API，获取图像。 没有浏览器 服务器上的二进制文件，没有内存峰值，跨环境的 Chromium 版本不匹配。

使用一个 POST 请求捕获网站屏幕截图

发送 URL 至 /v1/screenshot/capture 端点并获取屏幕截图 作为 PNG、JPEG 或 WebP。 该 API 在 Cloudflare 的边缘网络上运行完整的 Chromium 实例， 因此所有 JavaScript、CSS 和 Web 字体都能正确呈现。

curl -X POST https://api.botoi.com/v1/screenshot/capture \\
  -H "Content-Type: application/json" \\
  -d '{
    "url": "https://github.com",
    "width": 1280,
    "height": 800,
    "format": "png"
  }'

回复：

{
  "success": true,
  "data": {
    "url": "https://api.botoi.com/screenshots/a1b2c3d4.png",
    "format": "png",
    "width": 1280,
    "height": 800,
    "fullPage": false,
    "size_bytes": 184320
  }
}

该响应为您提供捕获图像的直接 URL 以及格式、尺寸、 和文件大小。 您可以直接在应用程序中下载、缓存或提供该 URL。 否 需要 Base64 解码或文件处理。

控制视口、格式和时间

默认屏幕截图以 PNG 格式捕获 1280x800 视口。 这涵盖了大多数用途 情况下，但您通常需要更多的控制。 以下是您可以设置的参数：

• 宽度/高度： 视口尺寸（以像素为单位）。 桌面使用 1440x900， iPhone 14 为 390x844，iPad 为 768x1024。
• 格式： 输出为 png （无损，更大）， jpeg （有损，较小），或 webp （最适合网络使用的压缩）。
• 完整页面： 设置为 true 捕获整个可滚动页面， 不仅仅是适合视口的内容。 API 滚动页面并拼接 结果变成一张高图像。
• 延迟： 页面加载后捕获之前等待的毫秒数。 将其设置为 对于在安装和渲染客户端上获取数据的 SPA，2000-3000。 没有它，你会 截图加载旋转器。

以下请求捕获 JavaScript 渲染的 SPA 的全页 WebP 屏幕截图 延迟 3 秒：

curl -X POST https://api.botoi.com/v1/screenshot/capture \\
  -H "Content-Type: application/json" \\
  -d '{
    "url": "https://your-spa.vercel.app",
    "width": 1440,
    "height": 900,
    "format": "webp",
    "fullPage": true,
    "delay": 3000
  }'

为您的应用程序生成链接预览

链接预览是捕获网页屏幕截图的最常见原因之一 以编程方式。 当用户将 URL 粘贴到您的聊天应用、CMS 或项目管理中时 工具，您想要显示缩略图。 Open Graph 图像覆盖了一些链接，但也覆盖了很多页面 不要设置它们，以及经常使用通用品牌图像而不是实际页面的那些 内容。

这个 Node.js 服务器公开了一个 /preview 捕获和缓存的端点 缩略图为 1200x630（标准 Open Graph 图像尺寸）：

import express from "express";

const app = express();
app.use(express.json());

const screenshotCache = new Map();

async function captureScreenshot(url) {
  // Return cached version if available
  if (screenshotCache.has(url)) {
    return screenshotCache.get(url);
  }

  const res = await fetch("https://api.botoi.com/v1/screenshot/capture", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      url,
      width: 1200,
      height: 630,
      format: "webp",
    }),
  });

  const { data } = await res.json();
  screenshotCache.set(url, data.url);
  return data.url;
}

app.get("/preview", async (req, res) => {
  const { url } = req.query;

  if (!url) {
    return res.status(400).json({ error: "url parameter required" });
  }

  const thumbnailUrl = await captureScreenshot(url);
  res.json({
    original_url: url,
    thumbnail: thumbnailUrl,
    dimensions: "1200x630",
  });
});

app.listen(3000);

称呼 /preview?url=https://stripe.com/docs 然后你会得到一个 WebP 缩略图 显示实际页面内容的 URL。 内存缓存可防止重复捕获 相同的网址。 在生产中，交换它 Map 用于 Redis 或 CDN 缓存 TTL 为 24-48 小时，因此预览保持新鲜。

CI 中的视觉回归测试

视觉回归测试可以捕获单元测试遗漏的布局破坏。 CSS 改变了 通过所有测试仍然可以将您的定价页面标题推到屏幕外。 传统的 方法需要 Playwright 和在 CI 运行器中运行的无头浏览器。 这增加了 2-3 分钟到您的管道并使用 500+ MB 的磁盘。

此 GitHub Actions 工作流程捕获生产和运行中关键页面的屏幕截图 您的 PR 预览，然后在 PR 摘要中输出比较表：

name: Visual regression check

on:
  pull_request:
    branches: [main]

jobs:
  screenshot-diff:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Capture baseline screenshots
        run: |
          PAGES=("/" "/pricing" "/docs" "/blog")
          BASE_URL="https://your-app.com"
          mkdir -p screenshots/baseline

          for PAGE in "\${PAGES[@]}"; do
            FILENAME=\$(echo "\$PAGE" | tr '/' '-' | sed 's/^-//')
            [ -z "\$FILENAME" ] && FILENAME="home"

            curl -s -X POST https://api.botoi.com/v1/screenshot/capture \\
              -H "Content-Type: application/json" \\
              -H "Authorization: Bearer \${{ secrets.BOTOI_API_KEY }}" \\
              -d "{
                \\"url\\": \\"\$BASE_URL\$PAGE\\",
                \\"width\\": 1280,
                \\"height\\": 800,
                \\"format\\": \\"png\\",
                \\"fullPage\\": true
              }" | jq -r '.data.url' > "screenshots/baseline/\$FILENAME.url"

            echo "Captured baseline: \$PAGE"
          done

      - name: Capture PR preview screenshots
        run: |
          PAGES=("/" "/pricing" "/docs" "/blog")
          PREVIEW_URL="\${{ github.event.pull_request.head.repo.html_url }}"
          mkdir -p screenshots/preview

          for PAGE in "\${PAGES[@]}"; do
            FILENAME=\$(echo "\$PAGE" | tr '/' '-' | sed 's/^-//')
            [ -z "\$FILENAME" ] && FILENAME="home"

            curl -s -X POST https://api.botoi.com/v1/screenshot/capture \\
              -H "Content-Type: application/json" \\
              -H "Authorization: Bearer \${{ secrets.BOTOI_API_KEY }}" \\
              -d "{
                \\"url\\": \\"\$PREVIEW_URL\$PAGE\\",
                \\"width\\": 1280,
                \\"height\\": 800,
                \\"format\\": \\"png\\",
                \\"fullPage\\": true
              }" | jq -r '.data.url' > "screenshots/preview/\$FILENAME.url"

            echo "Captured preview: \$PAGE"
          done

      - name: Compare screenshots
        run: |
          echo "## Visual regression report" >> \$GITHUB_STEP_SUMMARY
          echo "" >> \$GITHUB_STEP_SUMMARY

          for BASELINE in screenshots/baseline/*.url; do
            NAME=\$(basename "\$BASELINE" .url)
            BASELINE_URL=\$(cat "\$BASELINE")
            PREVIEW_URL=\$(cat "screenshots/preview/\$NAME.url")
            echo "| \$NAME | [baseline](\$BASELINE_URL) | [preview](\$PREVIEW_URL) |" >> \$GITHUB_STEP_SUMMARY
          done

该工作流程从您的生产站点和 PR 预览 URL 捕获四个页面。 屏幕截图 URL 将作为比较表记录到 GitHub 步骤摘要中，以便审阅者 可以目视检查每一页。 CI 中没有浏览器二进制文件，没有 Playwright 设置，没有 Docker 层缓存。

对于自动像素级比较，请将屏幕截图 URL 通过管道传输到比较工具中，例如 pixelmatch 或者 resemblejs 如果存在差异，则工作流程失败 超过阈值。

比较：截图 API 与自托管 Puppeteer

运行你自己的无头浏览器可以让你完全控制，但这种控制是附带的 运营成本。 以下是这两种方法的叠加方式：

Feature                  | Screenshot API             | Self-hosted Puppeteer
─────────────────────────|────────────────────────────|──────────────────────────
Setup time               | 0 min (one HTTP call)      | 30-60 min (Docker, deps)
Browser binary           | Managed by API             | You maintain Chromium
Memory usage             | 0 MB on your server        | 200-500 MB per instance
Cold start               | None (edge network)        | 3-8 sec (browser launch)
Scaling                  | Handled automatically      | Manual (container pool)
Maintenance              | None                       | OS patches, Chrome updates
Cost (low volume)        | Free (5 req/min)           | Server cost + your time
Cost (high volume)       | API plan (~\$20/mo)         | \$50-200/mo (server + ops)
Full-page capture        | Built-in parameter         | Custom scroll logic
Format options           | PNG, JPEG, WebP            | Depends on your code
JavaScript rendering     | Built-in delay param       | Custom waitForSelector

API 在设置速度和维护方面获胜。 自托管 Puppeteer 在您需要时获胜 细粒度的浏览器控制（拦截网络请求、注入cookie 已验证的页面，或在捕获之前运行自定义 JavaScript）。 对于大多数截图 用例； 链接预览、视觉测试、报告缩略图、社交卡； 应用程序接口 方法可以满足您的需求，而无需基础设施开销。

要点

- One POST request captures any public URL as PNG, JPEG, or WebP
- Viewport width, height, full-page mode, and JS delay are all configurable
- No Puppeteer, Chromium, or headless browser setup on your side
- Free tier: 5 screenshots per minute, no API key needed
- Use cases: link previews, visual regression testing, PDF reports, social cards
- The API runs Chromium on the edge, so JS-heavy SPAs render correctly

每分钟 5 个请求的免费套餐适用于开发、原型设计和低流量 链接预览。 对于需要更高吞吐量的 CI 管道和生产应用程序，请添加您的 API 密钥位于 Authorization: Bearer 标头。 检查 API文档 获取完整的参数参考和响应模式。