Guide d’intégration de l’API de rendu web WebExtrator

POST https://api.acedata.cloud/webextrator/render L’API de rendu web WebExtrator est un service de rendu de pages web basé sur Chromium sans interface graphique. Fournissez une URL, et elle renvoie le HTML entièrement rendu (y compris le contenu injecté par JS), le texte brut, le titre de la page et l’URL finale. Render est l’interface la plus bas niveau de WebExtrator. Si vous avez besoin de résultats d’extraction structurés (corps d’article, prix de produits, ingrédients de recettes …), utilisez /webextrator/extract —— il exécute une chaîne complète d’extraction typée sur la même base de rendu.

Processus de demande

Pour utiliser la page de service WebExtrator, rendez-vous d’abord sur la console Ace Data Cloud pour obtenir votre API Token, et conservez-le pour une utilisation ultérieure.

Si vous n’êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion pour vous inviter à vous inscrire et à vous connecter ; une fois terminé, vous reviendrez automatiquement à la page actuelle. Un seul API Token permet d’appeler tous les services de la plateforme, il n’est pas nécessaire d’en demander un séparément pour chaque service. La première demande offre un quota gratuit, vous permettant d’essayer gratuitement ; lorsque le quota est insuffisant, vous pouvez recharger votre solde commun dans la console.

📘 Documentation complète : Page de service WebExtrator →

Authentification

Toutes les interfaces WebExtrator utilisent l’authentification standard Bearer Token :

Authorization: Bearer YOUR_API_KEY
Content-Type:  application/json

Paramètres de requête

Champ	Type	Requis	Par défaut	Description
`url`	string	✅	—	L’URL de la page à rendre, doit être en `http(s)://`.
`user_agent`	string	❌	Rotation du pool UA intégré	User-Agent personnalisé.
`timeout`	integer	❌	`30`	Délai d’expiration d’une navigation unique (secondes entières positives).
`wait_until`	enum	❌	`load`	Événement de fin de chargement : `load` / `domcontentloaded` / `networkidle` / `commit`.
`delay`	integer	❌	`0`	Secondes d’attente supplémentaires après le déclenchement de `wait_until` (entier non négatif) (pour le rendu secondaire SPA).
`wait_for_selector`	string	❌	—	Attend l’apparition de ce sélecteur CSS, plus stable que `networkidle`.
`block_resources`	string[]	❌	`["image","font","media"]`	Types de ressources bloquées, options : `image` / `font` / `media` / `stylesheet` / `xhr` / `fetch`.
`headers`	object	❌	—	En-têtes de requête HTTP supplémentaires (par exemple `{"Accept-Language": "en-US"}`).
`cookies`	array	❌	—	Cookies injectés avant la navigation, voir la structure ci-dessous.
`callback_url`	string	❌	—	Adresse de rappel en mode asynchrone, la plateforme effectue un `POST` du résultat complet à cette adresse lorsque la tâche est terminée.
`bypass_cache`	boolean	❌	`false`	Ignore la lecture du cache Redis (mais écrit tout de même ce résultat dans le cache).
`cache_ttl_seconds`	integer	❌	`3600`	TTL de cache personnalisé pour cette écriture, transmettez `0` pour ne pas mettre en cache cette réponse.
`async`	boolean	❌	`false`	Définissez sur `true` pour renvoyer immédiatement `task_id`, récupérez le résultat via `callback_url` ou l’API Tasks.

Le contrat de la plateforme utilise uniformément snake_case. Le service de rendu interne prend en charge camelCase, mais les appels externes utilisent systématiquement snake_case.

Structure des cookies

{
  "name":      "string",
  "value":     "string",
  "domain":    "string",
  "path":      "/",
  "expires":   1735689600,
  "httpOnly":  false,
  "secure":    true,
  "sameSite":  "Lax"
}

Réponse synchrone

{
  "success": true,
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "trace_id": "550e8400-e29b-41d4-a716-446655440001",
  "started_at": 1777717800.123,
  "finished_at": 1777717801.234,
  "elapsed": 1.111,
  "data": {
    "kind": "render",
    "url": "https://example.com",
    "finalUrl": "https://example.com/",
    "title": "Example Domain",
    "status": 200,
    "html": "<!DOCTYPE html><html>...</html>",
    "text": "Example Domain\nThis domain is for use in illustrative examples...",
    "userAgent": "Mozilla/5.0 ...",
    "elapsedMs": 1108
  }
}

Champ	Type	Description
`data.kind`	string	Fixé à `"render"`.
`data.url`	string	L’URL que vous avez soumise.
`data.finalUrl`	string	L’URL finale après avoir suivi les redirections.
`data.title`	string	Le `document.title` après le rendu.
`data.status`	number \| null	Le code d’état HTTP de la navigation principale.
`data.html`	string	Le HTML complet après le rendu.
`data.text`	string	Instantané de `document.body.innerText` (utilisez Extract pour un corps de texte plus propre).
`data.userAgent`	string	L’UA réellement utilisé.
`data.elapsedMs`	number	Temps de rendu du navigateur uniquement.
`data.cached`	boolean?	`true` lorsqu’il y a un accès au cache.
`data.cacheStoredAt`	number?	Horodatage Unix en millisecondes de la première écriture de l’entrée de cache.

Réponse asynchrone

Lorsque async=true (ou callback_url est fourni), renvoie immédiatement (HTTP 200) :

{
  "success": true,
  "task_id": "550e8400-...",
  "trace_id": "6ba7b810-...",
  "started_at": 1777717800.123
}

Le résultat sera envoyé via POST à callback_url (s’il est configuré), ou pourra être interrogé activement via /webextrator/tasks.

Structure du rappel

La plateforme effectue un POST de l’enveloppe exactement identique au mode synchrone vers callback_url, avec Content-Type: application/json. Tout retour 2xx est considéré comme confirmé ; les 5xx seront réessayés avec une temporisation exponentielle pendant environ 5 minutes.

Réponse d’erreur

HTTP	`error.code`	Signification
400	`bad_request`	Le corps de la requête n’a pas passé la validation Zod (absence de `url`, type incorrect …).
401	`unauthorized`	`Authorization: Bearer …` absent ou invalide.
402	(x402)	Solde de la plateforme insuffisant, renvoie une enveloppe d’exigence de paiement x402.
408	`timeout`	La navigation dépasse `timeout`.
429	`queue_busy`	La file synchrone est encombrée, veuillez réessayer ou utiliser `async=true`.
500	`internal_error`	Exception non gérée côté serveur (plantage du navigateur, etc.), le Worker réessaie automatiquement une fois.

Structure d’erreur :

{
  "success": false,
  "task_id": "...",
  "trace_id": "...",
  "started_at": 1777717800.123,
  "finished_at": 1777717800.135,
  "elapsed": 0.012,
  "error": { "code": "bad_request", "message": "url: Invalid url" }
}

Exemples

cURL

curl -X POST https://api.acedata.cloud/webextrator/render \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "wait_until": "networkidle",
    "block_resources": ["image", "media", "font"]
  }'

Python (requests)

import os, requests

API_KEY = os.environ["ACEDATA_API_KEY"]

resp = requests.post(
    "https://api.acedata.cloud/webextrator/render",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://example.com",
        "wait_until": "networkidle",
        "block_resources": ["image", "media", "font"],
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()["data"]
print(data["title"], data["status"], len(data["html"]))

Node.js (fetch)

const apiKey = process.env.ACEDATA_API_KEY;

const res = await fetch('https://api.acedata.cloud/webextrator/render', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com',
    wait_until: 'networkidle',
    block_resources: ['image', 'media', 'font'],
  }),
});
const { data } = await res.json();
console.log(data.title, data.status, data.html.length);

Asynchrone + rappel

curl -X POST https://api.acedata.cloud/webextrator/render \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "async": true,
    "callback_url": "https://your-app.example.com/hooks/webextrator"
  }'

Renvoie immédiatement { "success": true, "task_id": "...", "trace_id": "...", "started_at": 1777717800.123 } ; lorsque la tâche est terminée, la plateforme envoie le résultat complet par POST à votre callback_url.

Forcer le contournement du cache

curl -X POST https://api.acedata.cloud/webextrator/render \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "bypass_cache": true
  }'

Conseils et pièges

Il est très important de bien choisir wait_until. networkidle est le plus fiable mais le plus lent ; domcontentloaded est rapide mais peut manquer du contenu injecté de manière asynchrone ; load convient aux pages statiques traditionnelles.
La clé de cache ignore async. Les requêtes synchrones et asynchrones pour la même URL atteignent la même entrée de cache, les basculer librement ne l’invalide pas.
La clé de cache ignore bypass_cache et cache_ttl_seconds. Ces deux éléments sont des commutateurs d’opération, ils n’affectent pas le contenu de la réponse.
cookies et headers segmentent le cache. Personnaliser ces deux éléments fera échouer le premier accès pour la même combinaison.
Les SPA lourdes dépassent souvent les 30 secondes par défaut. Il est recommandé d’utiliser timeout: 60, wait_until: "domcontentloaded", delay: 4, puis de combiner avec wait_for_selector pour attendre les éléments qui vous intéressent réellement.
block_resources est le moyen le plus rapide de réduire la latence. Les images / polices / médias sont déjà bloqués par défaut ; si votre extraction ne dépend pas de la mise en page CSS, ajouter stylesheet peut encore accélérer.

Démarrage

Chat IA

Image IA

Vidéo IA

Audio IA

Web & Données

CAPTCHA

Identité

Coding

Autres guides

Guide d’intégration de l’API de rendu web WebExtrator

Processus de demande

Authentification

Paramètres de requête

Structure des cookies

Réponse synchrone

Réponse asynchrone

Structure du rappel

Réponse d’erreur

Exemples

cURL

Python (requests)

Node.js (fetch)

Asynchrone + rappel

Forcer le contournement du cache

Conseils et pièges

​Processus de demande

​Authentification

​Paramètres de requête

​Structure des cookies

​Réponse synchrone

​Réponse asynchrone

​Structure du rappel

​Réponse d’erreur

​Exemples

​cURL

​Python (requests)

​Node.js (fetch)

​Asynchrone + rappel

​Forcer le contournement du cache

​Conseils et pièges

Processus de demande

Authentification

Paramètres de requête

Structure des cookies

Réponse synchrone

Réponse asynchrone

Structure du rappel

Réponse d’erreur

Exemples

cURL

Python (requests)

Node.js (fetch)

Asynchrone + rappel

Forcer le contournement du cache

Conseils et pièges