1 回の API 呼び出しで Web サイトのスクリーンショットをキャプチャ

Webページのスクリーンショットが必要です。 おそらく、チャット アプリのリンク プレビューを構築していると思います。 CI でビジュアル回帰テストを実行しているかもしれません。 PDF レポートを生成している可能性があります ライブダッシュボードスナップショットが埋め込まれています。 明白な答えは、人形遣いか劇作家です。 あなたのサーバー。 明らかな問題: ヘッドレス Chromium バイナリは 200 ～ 500 MB のメモリを消費します。 コールド スタートには 3 ～ 8 秒かかります。OS レベルの依存関係が必要で、Docker イメージが変わります。 1 GB のアーティファクトに分割されます。 これらはすべて、Web サイトのスクリーンショットをプログラムでキャプチャするためのものです。

もっと簡単な道があります。 URLをスクリーンショットAPIに送信し、画像を取得します。 ブラウザなし サーバー上にバイナリが存在し、メモリのスパイクや、環境間での Chromium バージョンの不一致はありません。

1 つの POST リクエストで Web サイトのスクリーンショットをキャプチャする

に 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 デコードまたはファイル処理が必要です。

ビューポート、フォーマット、タイミングを制御する

デフォルトのスクリーンショットは、1280x800 のビューポートを PNG 形式でキャプチャします。 ほとんどの用途をカバーします 場合もありますが、多くの場合、より詳細な制御が必要になります。 設定できるパラメータは次のとおりです。

• 幅/高さ: ビューポートの寸法 (ピクセル単位)。 デスクトップには 1440x900 を使用し、 iPhone 14 の場合は 390x844、iPad の場合は 768x1024。
• 形式： として出力 png (ロスレス、より大きい)、 jpeg (損失があり、小さい)、または webp (Web での使用に最適な圧縮)。
• フルページ: に設定します true スクロール可能なページ全体をキャプチャするには、 ビューポートに収まるものだけではありません。 API はページをスクロールし、 1 つの縦長の画像になります。
• 遅れ： ページの読み込み後、キャプチャするまで待機するミリ秒数。 これを次のように設定します マウント時にデータをフェッチしてクライアント側でレンダリングする 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
  }'

アプリのリンク プレビューを生成する

リンクのプレビューは、Web ページのスクリーンショットをキャプチャする最も一般的な理由の 1 つです プログラム的に。 ユーザーがチャット アプリ、CMS、またはプロジェクト管理に URL を貼り付けるとき ツールでサムネイルを表示したいとします。 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。 メモリ内キャッシュにより、重複したキャプチャが防止されます。 同じ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 から 4 つのページをキャプチャします。 スクリーンショット URL は、比較表として GitHub ステップの概要に記録されるため、レビュー担当者は 各ページを視覚的に確認できます。 CI にはブラウザーバイナリ、Playwright セットアップ、Docker はありません レイヤーのキャッシュ。

ピクセルレベルの差分を自動化するには、スクリーンショットの URL を次のような比較ツールにパイプします。 pixelmatch または resemblejs 差分が異なる場合、ワークフローは失敗します。 閾値を超えています。

比較: スクリーンショット API と自己ホスト型 Puppeteer

独自のヘッドレス ブラウザを実行すると完全な制御が可能になりますが、その制御には次の機能が付属しています 運用コスト。 2 つのアプローチをまとめると次のようになります。

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 を実行します)。 ほとんどのスクリーンショットの場合 ユースケース; リンクのプレビュー、ビジュアル テスト、レポートのサムネイル、ソーシャル カード。 API このアプローチは、インフラストラクチャのオーバーヘッドなしで必要なものをカバーします。

重要なポイント

- 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

1 分あたり 5 リクエストの無料枠は、開発、プロトタイピング、低トラフィックに機能します。 リンクプレビュー。 より高いスループットを必要とする CI パイプラインと運用アプリの場合は、 API キー Authorization: Bearer ヘッダ。 チェックしてください APIドキュメント 完全なパラメーター参照と応答スキーマについては、