API de Capture d'Écran de Site Web#

Le point de terminaison POST /v1/convert/website-to-screenshot découvre chaque page d'un site web (via l'analyse du sitemap ou un crawl complet en largeur d'abord), prend une capture d'écran PNG pleine page de chaque page, et regroupe les résultats dans une seule archive ZIP. Les jobs s'exécutent toujours de manière asynchrone : l'API renvoie immédiatement un HTTP 202 avec un batch_id, la fin du job est signalée par l'interrogation du statut du batch, un callback webhook, ou une notification par email, et la réponse de statut du batch inclut une URL de téléchargement présignée pour le ZIP terminé. Nécessite un plan payant et une clé API privée.

Point de terminaison#

POST /v1/convert/website-to-screenshot

Content-Type: application/json

Format de sortie : archive ZIP contenant une capture d'écran PNG par page découverte.

Mode : Toujours asynchrone. Renvoie HTTP 202 immédiatement.

Authentification#

Ce point de terminaison nécessite une clé API privée. Les clés publiques ne sont pas prises en charge pour la capture de site web.

X-API-Key: sk_your_private_key

Paramètres de la requête#

Paramètres de découverte du site web#

Paramètres de notification#

Paramètres de navigateur et de rendu#

Ces paramètres s'appliquent à la capture de chaque page individuelle du site web.

Authentification et requêtes personnalisées#

Modes de crawl#

"auto" (par défaut)#

Utilise le mode de crawl le plus élevé autorisé par votre plan. Si votre plan prend en charge le crawl complet, il exécute un crawl complet. Si votre plan ne prend en charge que le sitemap, il exécute une découverte par sitemap.

"sitemap"#

Découvre les pages en analysant le sitemap.xml du site web :

1. Récupère {base_url}/sitemap.xml (délai d'expiration de 30 secondes)
2. Si l'élément racine est <sitemapindex>, récupère récursivement chaque sitemap enfant
3. Extrait toutes les entrées <url><loc> des éléments <urlset>
4. Renvoie la liste complète des URL découvertes

Renvoie une erreur si le sitemap est absent, renvoie un statut différent de 200, contient un XML invalide, ou ne contient aucune URL.

"full"#

Effectue un crawl complet en deux phases :

Phase 1 -- Découverte des URL de départ :

1. Analyse robots.txt pour les directives de sitemap et les règles de crawl
2. Vérifie les chemins de sitemap standards (/sitemap.xml, /wp-sitemap.xml, /sitemap_index.xml, etc.)
3. Découvre les flux RSS/Atom à partir des balises <link> et des chemins de flux courants
4. Extrait les URL de départ de toutes les sources découvertes

Phase 2 -- Crawl de liens en largeur d'abord :

1. Démarre à partir de l'URL de base et de toutes les URL de départ
2. Visite chaque page et met en file d'attente les liens du même domaine
3. Applique include_patterns et exclude_patterns pour filtrer les liens
4. Respecte les règles de robots.txt
5. Détecte et évite les pièges à URL infinis (pages de calendrier, filtres à facettes, etc.)
6. Déduplique les URL en normalisant le schéma, l'hôte, les paramètres de requête, et en supprimant les paramètres de suivi (utm_*, fbclid, gclid, etc.)

Motifs d'exclusion par défaut (lorsque exclude_patterns n'est pas fourni) :

• Ressources statiques : *.pdf, *.zip, *.jpg, *.png, *.gif, *.svg, *.css, *.js, *.xml, *.json, *.mp4, *.webm, *.woff, *.woff2
• Chemins protégés : /login, /admin, /cart, /checkout
• Pagination profonde : URL avec des paramètres page= dépassant 3 chiffres

Réponse#

202 Accepted (immédiat)#

{
    "status": "processing",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "url_count": 42,
    "total_discovered": 42,
    "discovery_method": "sitemap",
    "output_format": "zip"
}

Interrogation du statut du batch#

Interrogez avec le batch_id de la réponse 202 :

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

Renvoie le statut global, les statuts par URL, et une URL de téléchargement présignée pour le ZIP une fois terminé. Voir Interrogation du statut du batch pour le schéma complet de la réponse.

Charge utile du callback webhook#

Lorsque callback_url est fourni, EnConvert envoie une requête POST à la fin du job :

{
    "job_id": "batch-uuid",
    "status": "success",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "gcs_uri": "env/files/{project_id}/url-to-screenshot/website_20260405_123456789.zip",
    "filename": "website_20260405_123456789.zip",
    "file_size": 12345678,
    "total_tasks": 42,
    "successful_tasks": 40,
    "failed_tasks": 2,
    "tasks": [
        {"url": "https://example.com/", "status": "success", "filename": "example_20260405_001.png"},
        {"url": "https://example.com/about", "status": "success", "filename": "example_20260405_002.png"},
        {"url": "https://example.com/broken", "status": "failed", "error": "Timeout"}
    ]
}

Notification par email#

Un email de fin de job est envoyé à notification_email (ou à l'email du propriétaire du projet par défaut) lorsque le job se termine, que ce soit un succès ou un échec.

Limitation par plan d'abonnement#

Exemples de code#

Python (clé privée)#

import requests
import time

# Start the website capture
response = requests.post(
    "https://api.enconvert.com/v1/convert/website-to-screenshot",
    headers={"X-API-Key": "sk_your_private_key"},
    json={
        "url": "https://example.com",
        "crawl_mode": "sitemap",
        "output_filename": "example-screenshots",
        "viewport_width": 1440,
        "viewport_height": 900
    }
)

data = response.json()
print(f"Batch ID: {data['batch_id']}")
print(f"Pages found: {data['url_count']}")

# Poll for completion
batch_id = data["batch_id"]
while True:
    status = requests.get(
        f"https://api.enconvert.com/v1/convert/batch/{batch_id}",
        headers={"X-API-Key": "sk_your_private_key"}
    ).json()

    print(f"Status: {status['status']} ({status['completed']}/{status['total']})")

    if status["status"] in ("completed", "partial", "failed"):
        if status.get("zip_download_url"):
            print(f"Download: {status['zip_download_url']}")
        break

    time.sleep(5)

PHP (clé privée)#

$ch = curl_init("https://api.enconvert.com/v1/convert/website-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",
        "crawl_mode" => "sitemap",
        "output_filename" => "example-screenshots",
        "viewport_width" => 1440,
        "viewport_height" => 900
    ])
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo "Batch ID: " . $response["batch_id"] . "\n";
echo "Pages found: " . $response["url_count"] . "\n";

Node.js (clé privée)#

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

const data = await response.json();
console.log(`Batch ID: ${data.batch_id}`);
console.log(`Pages found: ${data.url_count}`);

// Poll for completion
const poll = async () => {
    const status = await fetch(
        `https://api.enconvert.com/v1/convert/batch/${data.batch_id}`,
        { headers: { "X-API-Key": "sk_your_private_key" } }
    ).then(r => r.json());

    console.log(`Status: ${status.status} (${status.completed}/${status.total})`);

    if (["completed", "partial", "failed"].includes(status.status)) {
        if (status.zip_download_url) console.log(`Download: ${status.zip_download_url}`);
        return;
    }
    setTimeout(poll, 5000);
};
poll();

Go (clé privée)#

package main

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

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

    req, _ := http.NewRequest("POST", "https://api.enconvert.com/v1/convert/website-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))
}

Avec callback webhook#

{
    "url": "https://example.com",
    "crawl_mode": "full",
    "callback_url": "https://your-server.com/webhook/enconvert",
    "output_filename": "example-full-site-screenshots",
    "include_patterns": [".*\\/blog\\/.*", ".*\\/docs\\/.*"]
}

Avec authentification (site protégé par mot de passe)#

{
    "url": "https://staging.example.com",
    "crawl_mode": "sitemap",
    "auth": {
        "username": "admin",
        "password": "staging-password"
    },
    "cookies": [
        {"name": "session_token", "value": "abc123", "domain": "staging.example.com"}
    ]
}

Réponses d'erreur#

Limites#

Questions fréquentes#

Comment capturer chaque page d'un site web avec une API ?#

Envoyez une requête POST à /v1/convert/website-to-screenshot avec l'url de base du site et votre clé privée dans l'en-tête X-API-Key. L'API découvre chaque page (sitemap ou crawl complet), capture un PNG pleine page de chacune, les regroupe dans une archive ZIP, et renvoie HTTP 202 avec un batch_id que vous pouvez interroger pour obtenir le lien de téléchargement.

Puis-je contrôler la taille ou le format des captures d'écran ?#

La largeur de la capture d'écran correspond à viewport_width (par défaut 1920), et viewport_height est utilisé comme référence de rendu. Chaque page est toujours capturée sous la forme d'un seul PNG pleine page. Les paramètres single_page et pdf_options ne s'appliquent pas aux captures d'écran.

Comment télécharger les captures d'écran une fois le job terminé ?#

Interrogez GET /v1/convert/batch/{batch_id} avec votre clé privée pour obtenir le statut global, les statuts par URL, et une URL de téléchargement ZIP présignée, ou transmettez un callback_url pour recevoir un POST webhook à la fin du job. Un email de fin de job est également envoyé à notification_email (ou au propriétaire du projet par défaut).

Puis-je capturer un site protégé par mot de passe ou en staging ?#

Oui, sur les plans avec accès basic auth : transmettez auth avec username et password pour l'HTTP Basic Auth appliquée à chaque page, injectez jusqu'à 50 cookies de session, ou envoyez jusqu'à 20 headers personnalisés.

Pourquoi le point de terminaison de capture d'écran de site web renvoie-t-il 403 Forbidden ?#

Les causes les plus courantes : la capture de site web n'est pas disponible sur le plan Founding, crawl_mode: "full" nécessite Studio ou supérieur, le nombre de pages découvertes dépasse la limite de taille de batch de votre plan, ou une fonctionnalité demandée (webhook, basic auth) n'est pas incluse dans votre plan.