API de Capturas de Pantalla de Sitios Web#

El endpoint POST /v1/convert/url-to-screenshot captura una captura de pantalla de página completa de cualquier URL de acceso público como una imagen PNG de alta fidelidad. Gestiona automáticamente banners de cookies, modales, contenido de carga diferida, animaciones activadas por scroll y encabezados fijos (sticky) para producir una captura limpia y precisa. Ejecútalo de forma síncrona para obtener una URL de descarga prefirmada o los bytes PNG en bruto, o usa el modo asíncrono para capturar varias URLs en un lote (batch).

Endpoint#

POST /v1/convert/url-to-screenshot

Content-Type: application/json

Formato de salida: PNG (siempre). El formato de salida no es configurable: todas las capturas se generan como imágenes PNG de página completa.

Autenticación#

Este endpoint admite autenticación tanto con clave privada como con clave pública.

Clave Privada#

Incluye tu clave secreta en el header X-API-Key. Úsala para llamadas servidor a servidor donde la clave nunca se expone al cliente.

X-API-Key: sk_your_private_key

Clave Pública con JWT#

Para uso en el cliente, primero genera un token JWT usando tu clave pública y luego pásalo como token Bearer.

Paso 1 -- Obtén un token:

POST /v1/auth/token
X-API-Key: pk_your_public_key

Paso 2 -- Usa el token:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Parámetros de la Solicitud#

Parámetros de Nivel Superior#

Parámetros de Navegador y Renderizado#

Autenticación y Solicitudes Personalizadas#

Esquema del Objeto Cookie#

Cada elemento del array cookies debe seguir esta estructura:

Respuesta#

Síncrono con Descarga Directa (direct_download=true)#

Clave privada -- devuelve los bytes PNG en bruto:

HTTP 200 OK
Content-Type: image/png
Content-Disposition: inline; filename="example_20260405_123456789.png"
X-Object-Key: env/files/{project_id}/url-to-screenshot/example_20260405_123456789.png
X-File-Size: 456789
X-Conversion-Time: 8.2
X-Filename: example_20260405_123456789.png

(binary PNG data)

Clave pública -- devuelve JSON con una URL prefirmada:

{
    "presigned_url": "https://spaces.example.com/...",
    "object_key": "env/files/{project_id}/url-to-screenshot/example_20260405_123456789.png",
    "filename": "example_20260405_123456789.png",
    "file_size": 456789,
    "conversion_time_seconds": 8.2,
    "job_id": "client-provided-id"
}

Síncrono sin Descarga Directa (direct_download=false)#

Disponible solo con claves privadas.

{
    "presigned_url": "https://spaces.example.com/...",
    "object_key": "env/files/{project_id}/url-to-screenshot/example_20260405_123456789.png",
    "filename": "example_20260405_123456789.png",
    "file_size": 456789,
    "conversion_time_seconds": 8.2
}

Modo Asíncrono#

Devuelve inmediatamente un batch_id para seguimiento.

HTTP 202 Accepted

{
    "status": "processing",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "url_count": 5,
    "output_format": "individual"
}

Cuando output_format=true (agrupación en ZIP):

{
    "status": "processing",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "url_count": 5,
    "output_format": "zip"
}

Sondeo de Estado del Job (Solo Claves Públicas)#

Para recuperación ante timeout con clave pública:

GET /v1/convert/status/{job_id}
Authorization: Bearer <jwt_token>

Sondeo de Estado de Lote (Solo Claves Privadas)#

Para jobs de lote asíncronos, sondea con el batch_id de la respuesta 202:

GET /v1/convert/batch/{batch_id}
X-API-Key: sk_your_private_key

Devuelve el estado agregado, los estados por URL y las URLs de descarga prefirmadas. Consulta Sondeo de Estado de Lote para ver el esquema de respuesta completo.

Payload del Webhook de Callback#

Cuando se proporciona un callback_url, EnConvert envía una solicitud POST a esa URL al finalizar.

Job de una sola URL:

{
    "job_id": "activity_id",
    "status": "success",
    "batch_id": "...",
    "gcs_uri": "object_key",
    "filename": "example_20260405_123456789.png",
    "file_size": 456789
}

Job de lote:

{
    "job_id": "activity_id",
    "status": "success",
    "batch_id": "...",
    "total_tasks": 10,
    "successful_tasks": 8,
    "failed_tasks": 2,
    "tasks": [
        {"url": "https://example.com/page1", "status": "success", "filename": "page1.png"},
        {"url": "https://example.com/page2", "status": "failed", "filename": null}
    ]
}

Funcionalidades#

Captura de Página Completa#

Cada captura incluye todo el contenido de la página, no solo el viewport visible. El conversor:

1. Renderiza la página con los valores especificados de viewport_width y viewport_height
2. Recorre la página con scroll para activar todo el contenido de carga diferida
3. Calcula el alto real del contenido usando un recorrido del árbol DOM que mide la posición inferior máxima de todos los elementos visibles
4. Redimensiona el viewport para abarcar todo el alto del contenido
5. Captura la pantalla con full_page=true

El resultado es una única imagen PNG alargada de la página completa.

Modo de Captura Limpia#

EnConvert gestiona automáticamente los obstáculos habituales de las páginas web para producir capturas limpias:

• Banners de consentimiento de cookies -- Cierra automáticamente banners de OneTrust, Cookiebot, Didomi, Usercentrics e implementaciones genéricas. Funciona en la página principal y en iframes.
• Cierre de modales y popups -- Cierra overlays usando varias estrategias: tecla Escape, botones de cierre ARIA, botones de cierre basados en clase ("Close", "Not now", "No thanks", "Skip") y botones de diálogo basados en role. Elimina los efectos residuales de blur, backdrop e inert tras el cierre.
• Revelado de animaciones por scroll -- Fuerza la visibilidad de elementos ocultos por librerías de animación activadas por scroll, incluyendo WOW.js, AOS, ScrollReveal, GSAP ScrollTrigger y clases de animación genéricas (.fadeIn, .slideIn, etc.). También revela todos los slides de Swiper.
• Limpieza de dropdowns -- Cierra todos los dropdowns abiertos, convierte los elementos button de navegación en enlaces anchor reales para que se mantengan visualmente limpios, oculta los elementos role="menu" y reposiciona los encabezados fijos a posición static.

Normalización de Unidades de Viewport#

Las capturas requieren un manejo especial de las unidades de viewport de CSS (vh, svh, lvh, dvh) porque el viewport se redimensiona al alto completo de la página. Sin normalización, los elementos dimensionados con unidades de viewport se estirarían a tamaños enormes. El conversor:

• Convierte todas las unidades relativas al viewport en valores de píxeles fijos basados en el alto de viewport original
• Limita las imágenes y videos anormalmente altos a 1.5 veces el alto de viewport original
• Gestiona particularidades de altura específicas de Elementor (contenedores flex, efectos de movimiento, contenedores de fondo)
• Preserva las dimensiones de video durante el proceso de normalización

HTTP Basic Auth#

Pasa auth con username y password para capturar páginas protegidas con HTTP Basic Authentication.

{
    "url": "https://staging.example.com/dashboard",
    "auth": {
        "username": "admin",
        "password": "secret"
    }
}

Inyección de Cookies#

Inyecta hasta 50 cookies antes de que cargue la página. Útil para capturar páginas que requieren una sesión activa.

{
    "url": "https://example.com/dashboard",
    "cookies": [
        {"name": "session_id", "value": "abc123", "domain": "example.com"},
        {"name": "locale", "value": "en-US", "domain": "example.com"}
    ]
}

Headers Personalizados#

Envía hasta 20 headers HTTP personalizados en cada solicitud a la página de destino.

{
    "url": "https://example.com/report",
    "headers": {
        "X-Custom-Token": "my-token-value",
        "Accept-Language": "en-US"
    }
}

Carga Diferida de Imágenes#

Cuando load_media y enable_scroll están habilitados (ambos por defecto en true), el conversor recorre la página lentamente con scroll (120px cada 90ms) para activar los loaders diferidos y luego espera a que todas las imágenes terminen de cargar, con un periodo de estabilización de layout de 500ms.

Establece load_media=false para una captura más rápida: el conversor usa scroll rápido (300px cada 30ms) con una estabilización más corta de 100ms, pero los medios pueden aparecer como placeholders.

Manejo de Encabezados Sticky#

Cuando está habilitado (por defecto true), el conversor detecta elementos con posición fixed y sticky que parecen ser encabezados, los reposiciona a posición static para una captura limpia, y hace scroll hasta arriba de la página antes de capturar.

Funcionalidades Adicionales de Renderizado#

• Emulación de medio screen -- La página se renderiza usando el medio CSS screen (no print), de modo que la captura coincide con lo que los usuarios ven en su navegador.
• Modo stealth -- Usa enmascaramiento de fingerprint del navegador para evitar la detección de bots en páginas protegidas.
• Intercepción de popups -- Cierra automáticamente cualquier pestaña nueva del navegador o popup activado por la página.
• Bypass de CSP -- Gestiona las restricciones de Content Security Policy y Trusted Types que de otro modo bloquearían la manipulación de la página.
• Preservación de sombras -- Los elementos con box-shadow y text-shadow se etiquetan para garantizar que las sombras se rendericen correctamente en la captura de salida.

Restricciones por Plan de Suscripción#

Modo Asíncrono#

El modo asíncrono es útil para capturas de larga duración o al capturar varias URLs.

Cómo Funciona#

1. Envía una solicitud con async_mode=true (o pasa varias URLs, lo que habilita el modo asíncrono automáticamente).
2. La API devuelve HTTP 202 inmediatamente con un batch_id y un url_count.
3. Cada URL se captura en segundo plano, se sube al almacenamiento y se rastrea individualmente.
4. Supervisa la finalización mediante sondeo de estado de lote, notificación por email o callback de webhook.

Notificación por Email#

Por defecto, se envía un email de finalización a la dirección de correo del propietario del proyecto. Puedes anularlo con notification_email:

{
    "url": ["https://example.com/page1", "https://example.com/page2"],
    "async_mode": true,
    "notification_email": "[email protected]"
}

Callback de Webhook#

Proporciona un callback_url para recibir una notificación POST automática al finalizar:

{
    "url": ["https://example.com/page1", "https://example.com/page2"],
    "async_mode": true,
    "callback_url": "https://your-server.com/webhook/enconvert"
}

Procesamiento por Lotes y en Volumen#

Captura varias URLs en una sola solicitud. Requiere modo asíncrono y una clave privada.

Salida Individual (predeterminado)#

Cada URL genera un archivo PNG separado:

{
    "url": [
        "https://example.com/page1",
        "https://example.com/page2",
        "https://example.com/page3"
    ],
    "async_mode": true
}

Salida en Paquete ZIP#

Agrupa todas las capturas en un único archivo ZIP:

{
    "url": [
        "https://example.com/page1",
        "https://example.com/page2",
        "https://example.com/page3"
    ],
    "async_mode": true,
    "output_format": true,
    "output_filename": "monthly-screenshots"
}

Ejemplos de Código#

Python (Clave Privada)#

import requests

response = requests.post(
    "https://api.enconvert.com/v1/convert/url-to-screenshot",
    headers={"X-API-Key": "sk_your_private_key"},
    json={
        "url": "https://example.com",
        "viewport_width": 1440,
        "viewport_height": 900
    }
)

data = response.json()
print(data["presigned_url"])

PHP (Clave Privada)#

$ch = curl_init("https://api.enconvert.com/v1/convert/url-to-screenshot");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "X-API-Key: sk_your_private_key"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "url" => "https://example.com",
        "viewport_width" => 1440,
        "viewport_height" => 900
    ])
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo $data["presigned_url"];

Node.js (Clave Privada)#

const response = await fetch("https://api.enconvert.com/v1/convert/url-to-screenshot", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "sk_your_private_key"
    },
    body: JSON.stringify({
        url: "https://example.com",
        viewport_width: 1440,
        viewport_height: 900
    })
});

const data = await response.json();
console.log(data.presigned_url);

Go (Clave Privada)#

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    body, _ := json.Marshal(map[string]interface{}{
        "url":             "https://example.com",
        "viewport_width":  1440,
        "viewport_height": 900,
    })

    req, _ := http.NewRequest("POST", "https://api.enconvert.com/v1/convert/url-to-screenshot", bytes.NewBuffer(body))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", "sk_your_private_key")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    respBody, _ := io.ReadAll(resp.Body)
    fmt.Println(string(respBody))
}

JavaScript -- Navegador (Clave Pública)#

// Step 1: Get a JWT token
const tokenRes = await fetch("https://api.enconvert.com/v1/auth/token", {
    method: "POST",
    headers: { "X-API-Key": "pk_your_public_key" }
});
const { token } = await tokenRes.json();

// Step 2: Capture screenshot
const convertRes = await fetch("https://api.enconvert.com/v1/convert/url-to-screenshot", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${token}`
    },
    body: JSON.stringify({
        url: "https://example.com"
    })
});

const data = await convertRes.json();
// Display the screenshot
const img = document.createElement("img");
img.src = data.presigned_url;
document.body.appendChild(img);

React (Clave Pública)#

import { useState } from "react";

function UrlToScreenshot() {
    const [loading, setLoading] = useState(false);
    const [imageUrl, setImageUrl] = useState(null);

    async function captureScreenshot() {
        setLoading(true);
        try {
            // Get JWT token
            const tokenRes = await fetch("https://api.enconvert.com/v1/auth/token", {
                method: "POST",
                headers: { "X-API-Key": "pk_your_public_key" }
            });
            const { token } = await tokenRes.json();

            // Capture screenshot
            const convertRes = await fetch("https://api.enconvert.com/v1/convert/url-to-screenshot", {
                method: "POST",
                headers: {
                    "Content-Type": "application/json",
                    "Authorization": `Bearer ${token}`
                },
                body: JSON.stringify({ url: "https://example.com" })
            });

            const data = await convertRes.json();
            setImageUrl(data.presigned_url);
        } finally {
            setLoading(false);
        }
    }

    return (
        <div>
            <button onClick={captureScreenshot} disabled={loading}>
                {loading ? "Capturing..." : "Take Screenshot"}
            </button>
            {imageUrl && <img src={imageUrl} alt="Screenshot" style={{ maxWidth: "100%" }} />}
        </div>
    );
}

export default UrlToScreenshot;

Respuestas de Error#

Límites#

Preguntas frecuentes#

¿Cómo tomo una captura de pantalla de página completa de un sitio web con una API?#

Envía una solicitud POST a /v1/convert/url-to-screenshot con un cuerpo JSON que contenga url, autenticándote con tu clave privada en el header X-API-Key (o un token Bearer JWT de una clave pública). Cada captura incluye todo el contenido de la página, no solo el viewport visible: el conversor redimensiona el viewport al alto completo del contenido y captura con full_page=true.

¿Puedo cambiar el formato de salida de la captura a JPEG o WebP?#

No. El formato de salida no es configurable: todas las capturas se generan como imágenes PNG de página completa.

¿Cómo controlo el ancho y el tamaño de la captura?#

Establece viewport_width (por defecto 1920): el ancho de la captura coincide con este valor. El alto de la captura lo determina el alto completo del contenido de la página, usando viewport_height (por defecto 1080) como referencia para el renderizado y el cálculo de unidades de viewport.

¿Puedo capturar una página protegida por login?#

Sí. Usa el parámetro auth para HTTP Basic Auth, inyecta hasta 50 cookies de sesión con cookies, o envía hasta 20 headers HTTP personalizados con headers. Estas opciones requieren acceso a basic auth en tu plan.

¿Cómo elimina la API los banners de cookies y popups de las capturas?#

Con handle_cookies habilitado (por defecto true), el conversor cierra automáticamente los banners de consentimiento de OneTrust, Cookiebot, Didomi, Usercentrics e implementaciones genéricas, funcionando tanto en la página principal como en iframes. Los modales y popups se cierran usando la tecla Escape, botones de cierre ARIA, botones de cierre basados en clase y botones de diálogo basados en role, eliminando los efectos residuales de blur y backdrop.