Capture capturas de tela do site com uma chamada de API

Você precisa de uma captura de tela de uma página da web. Talvez você esteja criando visualizações de links para um aplicativo de bate-papo. Talvez você esteja executando testes de regressão visual em CI. Talvez você esteja gerando relatórios em PDF que incorporam um instantâneo do painel ao vivo. A resposta óbvia é Titereiro ou Dramaturgo em seu servidor. O problema óbvio: um binário Chromium sem cabeça consome 200-500 MB de memória, leva de 3 a 8 segundos para iniciar a frio, precisa de dependências no nível do sistema operacional e transforma sua imagem Docker em um artefato de 1 GB. Tudo isso para capturar capturas de tela do site de forma programática.

Existe um caminho mais simples. Envie o URL para uma API de captura de tela e receba uma imagem. Sem navegador binário em seu servidor, sem picos de memória, sem incompatibilidades de versão do Chromium entre ambientes.

Capture uma captura de tela do site com uma solicitação POST

Envie uma URL para o /v1/screenshot/capture endpoint e receba uma captura de tela como PNG, JPEG ou WebP. A API executa uma instância completa do Chromium na rede de borda da Cloudflare, para que todas as fontes JavaScript, CSS e web sejam renderizadas corretamente.

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"
  }'

Resposta:

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

A resposta fornece um URL direto para a imagem capturada junto com o formato, dimensões, e tamanho do arquivo. Você pode baixar, armazenar em cache ou fornecer esse URL diretamente em seu aplicativo. Não É necessária decodificação base64 ou manipulação de arquivos.

Controlar viewport, formato e tempo

A captura de tela padrão captura uma janela de visualização de 1280x800 no formato PNG. Isso cobre a maior parte do uso casos, mas muitas vezes você precisará de mais controle. Aqui estão os parâmetros que você pode definir:

• largura/altura: Dimensões da janela de visualização em pixels. Use 1440x900 para desktop, 390x844 para iPhone 14 ou 768x1024 para iPad.
• formatar: Saída como png (sem perdas, maior), jpeg (com perdas, menor) ou webp (melhor compactação para uso na web).
• página completa: Definir como true para capturar toda a página rolável, não apenas o que cabe na janela de visualização. A API rola pela página e costura o resultar em uma imagem alta.
• atraso: Milissegundos de espera após o carregamento da página antes da captura. Defina isso como 2000-3000 para SPAs que buscam dados na montagem e renderizam no lado do cliente. Sem isso, você captura de tela de um botão giratório de carregamento.

Aqui está uma solicitação que captura uma captura de tela WebP de página inteira de um SPA renderizado em JavaScript com um atraso de 3 segundos:

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
  }'

Gere visualizações de links para seu aplicativo

As visualizações de links são um dos motivos mais comuns para capturar capturas de tela de páginas da web programaticamente. Quando um usuário cola um URL em seu aplicativo de bate-papo, CMS ou gerenciamento de projetos ferramenta, você deseja mostrar uma miniatura. As imagens do Open Graph cobrem alguns links, mas muitas páginas não os defina, e aqueles que o fazem geralmente usam imagens de marca genéricas em vez da página real conteúdo.

Este servidor Node.js expõe um /preview endpoint que captura e armazena em cache miniaturas em 1200x630 (o tamanho de imagem padrão do 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);

Chamar /preview?url=https://stripe.com/docs e você recebe de volta uma miniatura WebP URL mostrando o conteúdo real da página. O cache na memória evita capturas duplicadas para o mesmo URL. Na produção, troque isso Map para Redis ou um cache CDN com um TTL de 24 a 48 horas para que as visualizações permaneçam atualizadas.

Teste de regressão visual em CI

O teste de regressão visual detecta quebras de layout que os testes de unidade não percebem. Uma mudança de CSS que passar em todos os testes ainda pode empurrar o título da sua página de preços para fora da tela. O tradicional abordagem precisa do Playwright e de um navegador headless em execução no seu executor de CI. Isso adiciona 2-3 minutos para seu pipeline e usa mais de 500 MB de disco.

Este fluxo de trabalho do GitHub Actions captura capturas de tela das principais páginas de produção e sua visualização de PR e, em seguida, gera uma tabela de comparação no resumo de 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

O fluxo de trabalho captura quatro páginas do seu site de produção e o URL de visualização do PR. URLs de captura de tela são registrados no resumo da etapa do GitHub como uma tabela de comparação para que os revisores pode verificar visualmente cada página. Sem binários de navegador no CI, sem configuração do Playwright, sem Docker cache de camada.

Para comparação automatizada em nível de pixel, canalize os URLs de captura de tela para uma ferramenta de comparação como pixelmatch ou resemblejs e falha no fluxo de trabalho se a diferença excede um limite.

Comparação: API de captura de tela vs Puppeteer auto-hospedado

Executar seu próprio navegador sem cabeça oferece controle total, mas esse controle vem com custo operacional. Veja como as duas abordagens se comparam:

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

A API ganha em velocidade de configuração e manutenção. O Puppeteer auto-hospedado vence quando você precisa controle refinado do navegador (interceptando solicitações de rede, injetando cookies para páginas autenticadas ou executando JavaScript personalizado antes da captura). Para a maioria das capturas de tela casos de uso; visualizações de links, testes visuais, miniaturas de relatórios, cartões sociais; a API abordagem cobre o que você precisa sem a sobrecarga de infraestrutura.

Pontos-chave

- 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

O nível gratuito de 5 solicitações por minuto funciona para desenvolvimento, prototipagem e baixo tráfego visualizações de links. Para pipelines de CI e aplicativos de produção que precisam de maior rendimento, adicione seu Chave de API no Authorization: Bearer cabeçalho. Verifique o Documentos da API para obter a referência completa do parâmetro e o esquema de resposta.