API de Website Screenshot

Descripción generalLink to Descripción general

La Screenshot API de Piloterr renderiza una página web como un navegador real y devuelve una captura (PNG/JPEG/WebP) o un PDF.
Está diseñada para flujos de trabajo en los que necesitas una salida visual fiable para previews, reporting, QA, monitorización y archivado, sin construir tu propia infraestructura de navegador headless.

Casos de uso típicosLink to Casos de uso típicos

• Previews y miniaturas de sitios web: genera previews consistentes para enlaces en dashboards, directorios o herramientas SEO.
• QA y regresión visual: captura páginas entre releases (desktop/móvil) para detectar cambios de UI.
• Reporting y entregables para clientes: exporta capturas de página completa o PDFs para auditorías y documentación.
• Monitorización y compliance: guarda evidencia visual del estado de una página en un momento dado (páginas de precios, páginas legales, anuncios).
• Captura de producto / página: obtén screenshots limpios de productos eliminando banners de cookies/anuncios/popups.
• Captura de componentes: captura un elemento específico (card, widget, gráfico) en lugar de toda la página.

Inicio rápidoLink to Inicio rápido

Envía una solicitud con url y tu x-api-key. El cuerpo de la respuesta es el archivo generado (binario).

Ejemplo de solicitud:

curl -L "https://api.piloterr.com/v2/capture?x-api-key=YOUR_KEY&url=https://example.com" --output capture.png

Variantes comunes:

Página completa

curl -L "https://api.piloterr.com/v2/capture?x-api-key=YOUR_KEY&url=https://example.com&full_page=true" --output full.png

Preview móvil

curl -L "https://api.piloterr.com/v2/capture?x-api-key=YOUR_KEY&url=https://example.com&device=iphone_14_pro" --output mobile.png

Exportación a PDF

curl -L "https://api.piloterr.com/v2/capture?x-api-key=YOUR_KEY&url=https://example.com&format=pdf&full_page=true" --output page.pdf

ParámetrosLink to Parámetros

RequeridosLink to Requeridos

• url (string): URL de la página web a renderizar y capturar.

• x-api-key (string): Clave de API (se puede proporcionar como query param, en el header x-api-key o en el cuerpo de la solicitud).

SalidaLink to Salida

• format (opcional): Tipo de archivo de salida (png por defecto; también soporta webp, jpeg/jpg, pdf).
• viewport_width / viewport_height (opcional): Controla el tamaño del viewport de escritorio.
• scale_factor (opcional): Aumenta la densidad de píxeles para una salida más nítida.
• image_quality (opcional): Calidad de compresión para webp / jpeg.

Pruebas móviles / responsiveLink to Pruebas móviles / responsive

• device (opcional): Emula un perfil predefinido de dispositivo móvil/tablet.

Captura de página completaLink to Captura de página completa

• full_page (opcional): Captura toda la altura de la página.
• full_page_scroll / full_page_scroll_duration (opcional): Hace scroll para activar contenido lazy-loaded durante la captura de página completa.

Timing (páginas con mucho JS)Link to Timing (páginas con mucho JS)

• wait_for_selector (opcional): Espera hasta que exista un selector CSS antes de capturar (ideal para SPAs).
• wait_until (opcional): Elige el evento de “listo” de la página.
• delay (opcional): Tiempo de espera fijo antes de la captura.

Limpieza (eliminar overlays)Link to Limpieza (eliminar overlays)

• remove_cookie_banners (opcional): Intenta eliminar banners de cookies.
• remove_ads (opcional): Intenta eliminar anuncios.
• remove_selectors (opcional): Elimina elementos específicos mediante selectores CSS.
• selector (opcional): Captura solo un elemento específico.

Rendimiento / routingLink to Rendimiento / routing

• block_urls (opcional): Bloquea patrones de URL coincidentes (trackers, analytics).
• block_resources (opcional): Bloquea tipos de recursos (imágenes, fuentes, etc.).
• proxy (opcional): Enruta a través de un proxy (casos geo / restringidos / anti-bot).

CachéLink to Caché

• cache (opcional): Cachea resultados para solicitudes repetidas.
• cache_ttl (opcional): TTL de caché en segundos.

Almacenamiento (opcional)Link to Almacenamiento (opcional)

• Subida a S3: s3_url + campos de bucket/credenciales para subir directamente a S3 o almacenamiento compatible con S3.

Notas / límitesLink to Notas / límites

• Variabilidad de la página: las páginas dinámicas pueden cambiar entre capturas; guarda timestamps con tus outputs.
• Las SPAs necesitan esperas deterministas: prioriza wait_for_selector para resultados consistentes en sitios con mucho JS.
• Página completa + scroll infinito: páginas con contenido interminable pueden producir renders de página completa impredecibles.
• La limpieza no es universal: banners de cookies/anuncios varían según el sitio; remove_selectors es el fallback más fiable.
• Trade-offs de rendimiento: un scale_factor alto y las capturas de página completa aumentan el tamaño del output y el tiempo de renderizado.
• Manejo de respuesta binaria: trata las respuestas como binario (Blob/ArrayBuffer) en tu playground/cliente.