API Documentação

1. Registe-se gratuitamente e crie uma API Key na página «API Key» da consola.
2. Inclua a API Key no cabeçalho X-Access-Key e faça um pedido ao endpoint de captura:

curl "https://glanceshot.com/v1/screenshot?url=https://example.com&full_page=true" \
  -H "X-Access-Key: $GLANCESHOT_KEY" \
  -o screenshot.png

Todos os pedidos exigem uma API Key, que pode ser enviada de uma das seguintes formas:

• Cabeçalho X-Access-Key: gls_… (recomendado para pedidos a partir do servidor)
• Parâmetro de consulta access_key=gls_… (apenas para chamadas do lado do servidor; não o inclua em páginas web)
• URL assinado (para incluir o endereço numa página web, sem expor a API Key nem o segredo)

A API Key só é apresentada em texto simples uma vez, no momento da criação. Guarde-a em segurança. Se for exposta, pode desativá-la na consola.

Parâmetros exclusivos das capturas de ecrã:

Parâmetros comuns às capturas de ecrã e aos PDF:

Capturar aplicações de página única (React, Vue, etc.):A página é capturada num navegador real, após a execução do JavaScript. A opção predefinida networkidle espera que a página termine de obter os dados. Se o conteúdo só for renderizado depois, através de temporizadores ou animações, use wait_for_selector para indicar um elemento que sinalize que o conteúdo está pronto. Se não houver um elemento adequado, use delay para esperar mais um pouco.

Cada PDF consome 2 unidades da quota. Antes da impressão, a página é percorrida para ativar o carregamento diferido. Além dos parâmetros comuns, são suportados:

curl -X POST "https://glanceshot.com/v1/pdf" \
  -H "X-Access-Key: $GLANCESHOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Relatório trimestral</h1><p>Corpo do texto…</p>", "paper": "a4"}' \
  -o report.pdf

Por predefinição (response_type=binary), o ficheiro é devolvido diretamente, com Content-Type correspondente ao formato. Cabeçalhos de resposta:

• X-Request-Id: ID do pedido, a indicar ao comunicar um problema
• X-Glanceshot-Cache: HIT ou MISS
• X-Glanceshot-Truncated: true: a página inteira foi cortada por exceder 20,000 píxeis
• X-Glanceshot-Format-Changed: webp: PNG convertido automaticamente em WebP por exceder 5 MB (não há conversão se format=png for especificado explicitamente)

Com response_type=json, são devolvidos o endereço do ficheiro e os metadados:

curl -X POST "https://glanceshot.com/v1/screenshot" \
  -H "X-Access-Key: $GLANCESHOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "response_type": "json"}'

# Devolve
{
  "url": "https://glanceshot.com/i/3f/3f9c….png",
  "cache_hit": false,
  "duration_ms": 1284,
  "format": "png",
  "width": 1280,
  "height": 800,
  "request_id": "req_01j…"
}

Quer incluir o endereço da captura de ecrã diretamente em <img src> sem expor a API Key? O URL assinado contém apenas o identificador público key_id, nunca a API Key. A assinatura é calculada no seu servidor com o segredo associado à chave. Pode consultar o ID da chave e o segredo na página API Key da consola:

canonical = Ordene todos os parâmetros, exceto signature, por ordem lexicográfica dos nomes,
            formate cada entrada como k=urlencode(v) (RFC 3986, com os espaços codificados como %20) e una-as com &
signature = hex(HMAC-SHA256(secret, canonical))

Uma assinatura válida autentica o pedido. Os pedidos sem assinatura ou com uma assinatura inválida são rejeitados. Qualquer alteração aos parâmetros (por exemplo, mudar url) invalida a assinatura. O parâmetro opcional expires (tempo Unix em segundos) é incluído no cálculo da assinatura; após a expiração, é devolvido signature_expired. Para atualizar a cache, basta alterar um parâmetro sem efeito (como v=2) e gerar uma nova assinatura. Os URL assinados só permitem chamadas GET aos endpoints de captura de ecrã e PDF e não aceitam parâmetros de proxy.

key_id é público e, por si só, não permite chamar a API. Não inclua a API Key (access_key) num URL assinado: se o fizer, será devolvido invalid_params. Se já incluiu a API Key numa página web, desative essa chave na consola e crie uma nova.

import crypto from "node:crypto";

// Codificação RFC 3986 (espaços como %20), de acordo com as regras do servidor
const enc = (v) =>
  encodeURIComponent(v).replace(/[!'()*]/g, (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase());

function signedUrl(params, keyId, secret) {
  const all = { ...params, key_id: keyId };
  const canonical = Object.keys(all).sort().map((k) => `${k}=${enc(String(all[k]))}`).join("&");
  const signature = crypto.createHmac("sha256", secret).update(canonical).digest("hex");
  return `https://glanceshot.com/v1/screenshot?${canonical}&signature=${signature}`;
}

const src = signedUrl({ url: "https://example.com", viewport_width: 1200 }, KEY_ID, SECRET);
// <img src={src} alt="Pré-visualização da página web" />

Se precisar de aceder a uma página a partir de um país ou região específicos (por exemplo, para ver o idioma, o conteúdo e os preços locais), pode incluir no pedido um proxy contratado por si, cujos custos ficam a seu cargo. A página e todas as imagens, scripts e chamadas a API nela incluídas serão carregados através desse proxy. São suportados proxies socks5:// e http://, com nome de utilizador e palavra-passe opcionais.

curl -X POST "https://glanceshot.com/v1/screenshot" \
  -H "X-Access-Key: $GLANCESHOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "proxy": "socks5://user:pass@203.0.113.10:1080"}' \
  -o screenshot.png

• proxy só pode ser incluído no corpo de um pedido POST: não é permitido em pedidos GET, URL assinados ou tarefas em lote, para evitar que as credenciais do proxy fiquem expostas no URL, no histórico do navegador ou em páginas web.
• Se o nome de utilizador ou a palavra-passe contiverem caracteres especiais como @ ou :, aplique primeiro a codificação de URL (por exemplo, substitua @ por %40).
• Os pedidos com proxy têm uma cache separada e não partilham resultados com pedidos sem proxy ou com outros proxies.
• Se não for possível ligar ao proxy, se a autenticação falhar ou se o site de destino estiver inacessível, é devolvido proxy_failed e o pedido não é cobrado. O campo message indica o motivo específico.
• O proxy tem de ter um endereço público. Aplicam-se ao URL de destino as mesmas restrições dos pedidos sem proxy: não é permitido aceder a endereços de redes privadas.
• Ao aceder a sites através de um proxy, respeite os termos de utilização do site de destino e a legislação local.

Para capturar páginas que exigem autenticação, pode enviar o estado de sessão da sua própria conta. Há duas opções: enviar cookies, headers, local_storage e session_storage diretamente no pedido, ou usar a extensão Glanceshot para guardar o estado de sessão num «perfil de sessão» e enviar apenas login_profile no pedido.

curl -X POST "https://glanceshot.com/v1/screenshot"   -H "X-Access-Key: $GLANCESHOT_KEY"   -H "Content-Type: application/json"   -d '{
    "url": "https://app.example.com/dashboard",
    "cookies": "sid=YOUR_SESSION; theme=dark",
    "local_storage": {"token": "YOUR_TOKEN"}
  }' -o screenshot.png

• A extensão consegue ler credenciais de sessão às quais os scripts da página não têm acesso (incluindo cookies HttpOnly), bem como localStorage e IndexedDB, e é adequada para a maioria dos sites. Instale e ligue a extensão na página «Perfis de sessão» da consola.
• O estado de sessão só pode ser enviado no corpo de um pedido POST (GET e URLs assinados são rejeitados) e não é guardado nos logs nem no histórico de chamadas. Os pedidos com estado de sessão têm uma cache separada, específica desse estado, que não é partilhada com outros utilizadores.
• Se enviar um estado de sessão, mas a página redirecionar para o início de sessão, é devolvido login_expired e o pedido não é cobrado (a sessão expirou; volte a sincronizá-la com a extensão).
• Nos sites cuja sessão está associada ao dispositivo ou ao IP e não pode ser reproduzida na nuvem (como os de banca online), use a opção «Capturar página atual» da extensão para tirar a captura no seu próprio navegador e enviá-la.

Os pedidos com parâmetros idênticos usam a cache (omitir um parâmetro equivale a enviar explicitamente o valor predefinido; os parâmetros de autenticação e de cache não entram na comparação). Quando há um resultado em cache, o modo binário devolve um redirecionamento 302 para o endereço do ficheiro, com Cache-Control; o navegador segue o redirecionamento e guarda o ficheiro em cache automaticamente. O modo JSON devolve cache_hit: true.

Os resultados obtidos da cache não são faturados.Pedidos simultâneos com os mesmos parâmetros geram apenas uma renderização.

• Só são faturados os pedidos bem-sucedidos (2xx) que não usem a cache: 1 unidade por captura de ecrã e 2 por PDF.
• Os pedidos com tempo limite excedido, falhas de renderização, erros ou bloqueios de acesso no site de destino, parâmetros inválidos ou falhas de autenticação não consomem quota.
• A quota é reposta no início de cada mês (UTC). O plano gratuito inclui 100 unidades por mês; após esgotá-las, é devolvido quota_exceeded.
• Exceder o limite de pedidos por segundo ou de pedidos simultâneos devolve 429. O cabeçalho de resposta Retry-After indica o tempo de espera recomendado em segundos.
• Tempo máximo de renderização: 30 segundos; volume máximo de transferência por página: 50 MB; tamanho máximo do ficheiro gerado: 50 MB.

Consulte os limites de cada plano: Preços.

Todas as respostas de erro usam JSON:

{
  "error": {
    "code": "render_failed",
    "message": "target responded with an error status",
    "upstream_status": 404,
    "request_id": "req_01j…"
  }
}

Envie 1–100 URL de uma só vez. O endpoint devolve imediatamente um ID de tarefa (HTTP 202) e as capturas são processadas uma a uma em segundo plano. Ideal para capturas em lote sem manter a ligação aberta. Pode consultar periodicamente o estado ou definir webhook_url para receber uma notificação quando tudo estiver concluído. A autenticação é igual à do endpoint síncrono (apenas por cabeçalho ou pelo parâmetro access_key; não suporta URL assinados).

curl -X POST "https://glanceshot.com/v1/batch" \
  -H "X-Access-Key: $GLANCESHOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "screenshot",
    "urls": ["https://example.com", "https://example.org"],
    "options": { "full_page": true, "format": "webp" },
    "webhook_url": "https://your-app.com/hooks/glanceshot"
  }'

# Devolve 202
{
  "id": "bat_01j…",
  "type": "screenshot",
  "status": "queued",
  "total": 2, "succeeded": 0, "failed": 0,
  "created_at": "2026-10-18T09:30:00Z", "completed_at": null,
  "webhook": { "url": "https://your-app.com/hooks/glanceshot", "status": "none", "attempts": 0 },
  "items": [
    { "index": 0, "url": "https://example.com", "status": "pending", "result": null, "error": null },
    { "index": 1, "url": "https://example.org", "status": "pending", "result": null, "error": null }
  ]
}

Consultar o progresso: o estado da tarefa, status, passa por queued (em fila), running (em processamento) e completed (tudo concluído, com ou sem sucesso). O estado de cada URL é pending, running, succeeded ou failed. Em caso de sucesso, result contém o endereço do ficheiro; em caso de falha, error contém o código de erro (igual ao do endpoint síncrono).

curl "https://glanceshot.com/v1/batch/bat_01j…" -H "X-Access-Key: $GLANCESHOT_KEY"

{
  "id": "bat_01j…",
  "status": "completed",
  "total": 2, "succeeded": 1, "failed": 1,
  "completed_at": "2026-10-18T09:30:12Z",
  "items": [
    {
      "index": 0, "url": "https://example.com", "status": "succeeded", "duration_ms": 1830,
      "result": { "url": "https://glanceshot.com/i/3f/3f9c….webp", "mime": "image/webp", "width": 1280, "height": 2410, "cache_hit": false },
      "error": null
    },
    {
      "index": 1, "url": "https://example.org", "status": "failed", "duration_ms": 640,
      "result": null,
      "error": { "code": "render_failed", "message": "target responded with an error status" }
    }
  ]
}

• Aplicam-se as mesmas regras de faturação do endpoint síncrono: cada URL processado com sucesso consome 1 unidade por captura de ecrã ou 2 por PDF. Os resultados da cache e as falhas não consomem quota.
• Se a quota já estiver esgotada ao submeter o pedido, é devolvido quota_exceeded de imediato. Se se esgotar durante o processamento, os URL restantes falham com quota_exceeded.
• Cada conta pode ter até 5 tarefas em lote por concluir em simultâneo. Acima desse limite, é devolvido too_many_batches.
• A validade dos ficheiros gerados é definida por options.cache_ttl (por predefinição, 1 dia). Transfira-os e guarde-os antes de expirarem.
• Nos resultados da consulta e nas notificações, webhook.url é apresentado apenas até ao caminho, sem a cadeia de consulta.

Se definir webhook_url, enviaremos um pedido POST para esse endereço quando a tarefa estiver totalmente concluída. O corpo do pedido é JSON: { "event": "batch.completed", "batch": { … } }, em que batch é exatamente igual à resposta do endpoint de consulta. Cabeçalhos do pedido:

• X-Glanceshot-Signature: t=1760779812,v1=5d3f…: t é a hora de envio (segundos Unix) e v1 é a assinatura
• X-Glanceshot-Event: batch.completed, X-Glanceshot-Delivery-Attempt: 1 (número da tentativa de entrega)

v1 = hex(HMAC-SHA256(secret, t + "." + Corpo original do pedido))
secret é o segredo de assinatura associado à API Key usada para submeter a tarefa (disponível na página API Key da consola).

• Devolva uma resposta 2xx no prazo de 10 segundos; caso contrário, a entrega será considerada falhada. Em caso de falha, serão feitas novas tentativas após 10 segundos, 1 minuto e 5 minutos (até 4 tentativas no total).
• Em casos muito raros, pode receber notificações duplicadas para a mesma tarefa. Use batch.id para eliminar duplicados.
• Para verificar a assinatura, faça o cálculo com os bytes originais recebidos e confirme que a diferença entre t e a hora atual não excede alguns minutos, para evitar ataques de repetição.
• O URL de callback deve ser um endereço http(s) acessível publicamente e não pode apontar para uma rede interna.

import crypto from "node:crypto";

// rawBody tem de conter os bytes originais recebidos, sem aplicar JSON.parse e voltar a serializar
function verifyGlanceshotWebhook(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false; // Proteção contra ataques de repetição
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const got = Buffer.from(parts.v1 ?? "");
  return got.length === expected.length && crypto.timingSafeEqual(Buffer.from(expected), got);
}

// verifyGlanceshotWebhook(req.rawBody, req.headers["x-glanceshot-signature"], GLANCESHOT_SECRET)

Não requer autenticação. Devolve o estado do nó e do conjunto de navegadores (total, ocupados e disponíveis).