Scrnr
Toma capturas de pantalla de sitios web con Scrnr.io
Documentación
Documentación
rev. 2026-05-19
Todo lo que necesitas para empezar a tomar capturas de pantalla.
Autenticación
Pasa tu clave API en el encabezado X-Api-Key en cada solicitud.
shell
Copiar
curl https://api.scrnr.io/v1/screenshot
-H "X-Api-Key: sk_live_xxxx"
Endpoints
POST/v1/screenshot
Toma una captura de pantalla de cualquier URL pública.
Cuerpo de la solicitud
{
"url": "https://example.com", // required
"delivery": "inline" | "url", // default: inline
"options": {
"width": 1280, // default: 1280, max varies by plan
"height": 800, // default: 800, max varies by plan
"fullPage": false, // default: false
"format": "png" | "jpeg" | "webp", // default: png
"waitFor": "load" | "networkidle", // default: load
"delay": 0, // ms, max varies by plan
"blockCookieBanners": false, // default: false
"headers": {"X-Custom": "value"}, // Pro plan only
"retentionHours": 168 // Pro plan only, 1–720
}
}
POST/v1/upload
Sube un archivo de imagen existente (PNG, JPEG o WebP) a tu almacenamiento de scrnr. El archivo se aloja en storage.scrnr.io junto a las capturas de pantalla, cuenta como 1 crédito de captura contra tu cuota mensual y obedece las mismas reglas de retención y almacenamiento del plan. Útil para enviar capturas del lado del cliente (extensiones de navegador, canvas.toBlob, etc.) al mismo espacio de nombres de URL que las capturas generadas por scrnr.
Solicitud
multipart/form-data con un único campo file. El formato se detecta a partir de los bytes del archivo — el Content-Type proporcionado por el cliente se ignora.
shell
Copiar
curl https://api.scrnr.io/v1/upload
-H "X-Api-Key: sk_live_xxxx"
-F "file=@./screenshot.png"
Respuesta
201 Created, misma forma que /v1/screenshot con delivery: "url":
{ "url": "https://storage.scrnr.io/screenshots/...", "expiresAt": "2026-05-20T12:00:00.000Z" // null if covered by storage allowance }
Límites: 25 MB por subida; formatos permitidos png, jpeg, webp. Los archivos más grandes que el límite devuelven 413; los bytes que no son imágenes o formatos no compatibles devuelven 400.
GET/v1/usage
Devuelve el uso del mes actual y la cuota restante para la clave API autenticada.
Omisión de banners de cookies
Establece options.blockCookieBanners: true para suprimir las superposiciones de consentimiento/GDPR antes de que se capture la captura de pantalla.
Copiar
{ "url": "https://example.com", "options": { "blockCookieBanners": true } }
Ninguna técnica cubre el 100% de los sitios. Para mejores resultados, combínalo con waitFor: "networkidle" y un pequeño delay.
Encabezados de solicitud personalizados Pro
Pasa encabezados HTTP adicionales a la página de destino — útil para capturar páginas autenticadas, variantes de pruebas A/B o contenido específico por geolocalización. Disponible en el plan Pro.
Copiar
{ "url": "https://example.com/dashboard", "options": { "headers": { "X-Tenant-Id": "acme", "Referer": "https://app.example.com" } } }
Límites:
- Hasta 20 encabezados por solicitud
- 1 KB por valor, 4 KB en total entre todos los encabezados
- Los siguientes encabezados están bloqueados:
Host,Cookie,Authorization,Content-Length, encabezados hop-by-hop (Connection,Transfer-Encoding, etc.), y cualquier encabezado que comience conProxy-
Retención de archivos personalizada Pro
Anula cuánto tiempo se retiene el archivo capturado para una sola solicitud. Útil para vistas previas efímeras (establecer más bajo) o archivo a corto plazo (establecer más alto). Disponible en el plan Pro; se ignora cuando delivery: "inline".
Copiar
{ "url": "https://example.com", "delivery": "url", "options": { "retentionHours": 1 // file deleted after 1 hour } }
Rango: 1–720 horas (hasta 30 días). Establecer retentionHours siempre gana — incluso en capturas que de otro modo se conservarían indefinidamente bajo el almacenamiento incluido de tu plan. Para retención indefinida sin anulación por solicitud, el plan Pro incluye 5 GB de almacenamiento permanente; el complemento de almacenamiento +25 GB se acumula encima.
Entrega por webhook Pro
Establece delivery: "webhook" para que la URL del archivo capturado se envíe a tu servidor después de que se complete la captura de pantalla. Configura un endpoint HTTPS por cuenta en /dashboard/webhooks — se activa para cada captura de tu cuenta, ya sea mediante clave API o OAuth. Mostraremos el secreto HMAC una vez al crearlo; guárdalo.
La respuesta HTTP regresa inmediatamente con 202 Accepted y el ID de la captura; el webhook se dispara asincrónicamente desde el trabajador. Los POST fallidos se reintentan con retroceso exponencial a los 30s, 5m, 30m, 2h, 12h (5 reintentos, ~14.5 horas). Después de los intentos máximos o cualquier 4xx no reintentable, la entrega se marca como DEAD y se muestra para reproducción manual en el panel.
Carga útil
{ "id": "clx9z2...", // event id; matches X-Scrnr-Event-Id header "type": "screenshot.completed", "createdAt": "2026-04-28T12:00:00.000Z", "data": { "id": "clx9z2...", // request id "url": "https://example.com", "fileUrl": "https://storage.scrnr.io/...", "expiresAt": "2026-05-05T12:00:00.000Z", "format": "png", "fileSizeBytes": 123456, "durationMs": 1234 } }
Verificación de la firma
Cada solicitud incluye un encabezado X-Scrnr-Signature en el formato t=<ts>,v1=<hex>. Recalcula el HMAC-SHA256 de <ts>.<raw-body> usando tu secreto de endpoint y compáralo con v1 usando una verificación de tiempo constante. Rechaza solicitudes donde la marca de tiempo esté desviada más de 5 minutos.
Copiar
import crypto from "node:crypto";
function verify(secret, signatureHeader, timestamp, rawBody) {
const expected = crypto
.createHmac("sha256", secret)
.update(${timestamp}.${rawBody})
.digest("hex");
const provided = signatureHeader.match(/v1=([^,]+)/)?.[1] ?? "";
return (
expected.length === provided.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(provided)) &&
Math.abs(Date.now() / 1000 - Number(timestamp)) < 300
);
}
Encabezados
X-Scrnr-Event-Id— estable entre reintentos; úsalo como tu clave de idempotenciaX-Scrnr-Signature—t=<unix-seconds>,v1=<hex-hmac>User-Agent—scrnr-webhooks/1.0
Responde con 2xx para confirmar. Cualquier otra cosa se trata como un fallo (4xx son terminales excepto 408 / 425 / 429; 5xx y errores de red se reintentan según el programa).
Errores
Todos los errores devuelven JSON con un campo error. Los fallos de validación además incluyen un objeto details de Zod.
| Estado | Significado |
|---|---|
| 400 | Cuerpo de solicitud no válido, viewport/retardo por encima del límite del plan, o una opción solo Pro (encabezados personalizados, retención de archivos personalizada) usada en un plan no Pro. |
| 401 | Clave API / token OAuth faltante, no válido o revocado. |
| 403 | URL bloqueada — apunta a una IP privada, dominio bloqueado, o falla las comprobaciones de seguridad SSRF. |
| 404 | ID de captura no encontrado (solo en DELETE /v1/screenshot/:id). |
| 410 | La captura ya fue eliminada. |
| 413 | El archivo subido excede el límite de tamaño por solicitud (25 MB). Solo aplica a POST /v1/upload. |
| 429 | Cuota mensual alcanzada. La respuesta incluye el límite y la marca de tiempo resetAt. |
| 500 | La canalización de captura falló (tiempo de espera del sitio de destino, fallo del navegador, etc.). La solicitud se registra y se cuenta como FALLIDA, no contra tu cuota. |
Las capturas individuales fallidas (5xx) no cuentan para tu cuota mensual. Los contadores de cuota solo se incrementan en capturas exitosas.
Integración MCP
Añade scrnr como servidor MCP para usar take_screenshot y get_usage directamente dentro de tu herramienta de IA.
Inicia sesión con tu cuenta de scrnr
Los clientes MCP que admiten OAuth (Claude Desktop, conectores de Claude.ai, Cursor, Windsurf, etc.) pueden conectarse sin clave API — abrirán un navegador para que inicies sesión y soliciten acceso. Solo pega la URL a continuación; nosotros haremos el resto. Si tu cliente aún no admite OAuth, los ejemplos con clave API más abajo siguen funcionando.
Claude Desktop / Claude.ai — OAuth, recomendado
Configuración → Conectores → Añadir conector personalizado
Copiar
Cursor / Windsurf — OAuth, recomendado
~/.cursor/mcp.json · ~/.codeium/windsurf/mcp_config.json
Copiar
{ "mcpServers": { "scrnr": { "url": "https://mcp.scrnr.io/mcp" } } }
O usa una clave API
Claude Desktop — mediante mcp-remote (puente stdio)
~/Library/Application Support/Claude/claude_desktop_config.json
Copiar
{ "mcpServers": { "scrnr": { "command": "npx", "args": [ "mcp-remote", "https://mcp.scrnr.io/mcp", "--header", "Authorization: Bearer sk_live_xxxx" ] } } }
Cursor / Windsurf — transporte HTTP nativo
Copiar
{ "mcpServers": { "scrnr": { "url": "https://mcp.scrnr.io/mcp", "headers": { "Authorization": "Bearer sk_live_xxxx" } } } }
Límites
Los límites se aplican por solicitud y por mes calendario según tu plan.
| Límite | Free | Basic | Pro |
|---|---|---|---|
| Capturas / mes | 100 | 3,000 | 15,000 |
| Viewport máximo | 1920 × 1080 | 2560 × 1440 | 3840 × 2160 |
| Claves API por cuenta | 2 | 5 | 25 |
| Retardo máximo | 5s | 15s | 30s |
| Tiempo de espera de solicitud | 30s | 45s | 60s |
| Retención de archivos | 1 día | 3 días | 7 días |
| Almacenamiento incluido | — | — | 5 GB permanentes |
Límites más altos están disponibles en planes de pago. Gestiona tu suscripción y el complemento opcional de +25 GB de almacenamiento desde /dashboard/billing. Los archivos capturados mientras una asignación de almacenamiento está activa se conservan indefinidamente en lugar de expirar en la ventana de retención del plan.
Inicio rápido
Obtén una captura de pantalla en menos de un minuto:
- 1Inicia sesión — Ve a /dashboard e inicia sesión con tu correo.
- 2Crea una clave API — Haz clic en “Nueva clave API” — cópiala inmediatamente, se muestra solo una vez.
- 3Haz tu primera solicitud — Usa el endpoint POST /v1/screenshot con tu clave en el encabezado X-Api-Key.