Documentation de l'API

Une seule route, des paramètres explicites. Authentification par clé d'API (token).

Point d'entrée

GET https://webshotninja.com/api

Authentification

Ajoutez votre clé d'API au paramètre token. Vous la trouverez dans votre tableau de bord.

https://webshotninja.com/api?token=YOUR_API_KEY&url=https://example.com

Paramètres

Paramètre	Défaut	Description
`token`	—	Votre clé d'API (obligatoire).
`url`	—	L'URL de la page à capturer, encodée (obligatoire).
`width`	1600	Largeur du navigateur en pixels (100–3840).
`height`	1200	Hauteur du navigateur en pixels (100–4320).
`full`	0	1 = capture de toute la hauteur de la page.
`format`	webp	png, jpeg ou webp.
`quality`	80	Qualité jpeg/webp (1–100).
`delay`	0	Attente en millisecondes après le chargement (max 10000). Utile pour les sites avec animations d'intro.
`nocookies`	1	1 = fermer/masquer les bannières cookies (défaut). 0 = capturer la page telle quelle.
`scroll`	auto	1 = forcer l'auto-scroll lazy-loading, 0 = désactiver. Par défaut : automatique si full=1.
`nocache`	0	1 = forcer une capture fraîche (ignorer le cache 30 jours).
`selector`	—	Sélecteur CSS pour capturer un élément précis (ex : #hero, .pricing-table). L'élément est attendu jusqu'à 10s. Renvoie 404 s'il est introuvable. Prioritaire sur full si les deux sont passés.
`noads`	0	1 = bloquer les publicités et trackers (basé sur EasyList). Compatible avec nocookies.
`css`	—	CSS personnalisé injecté dans la page avant la capture (max 10 Ko). Réservé à l'API, indisponible sur la démo.
`js`	—	JavaScript personnalisé exécuté dans le contexte de la page avant la capture (max 10 Ko). Réservé à l'API. Si le script échoue, la capture est quand même réalisée et l'erreur est renvoyée dans le header X-WSN-JS-Error.
`dark`	0	1 = activer le mode sombre (prefers-color-scheme: dark). Ne fonctionne que si le site cible supporte nativement le dark mode.
`device`	—	Preset d'appareil : iphone14, iphone14pro, pixel7, ipad, galaxys23. Définit le viewport, le user-agent et l'émulation tactile. Les paramètres width/height explicites surchargent le viewport du preset.
`scale`	1	Facteur d'échelle (1, 2 ou 3). scale=2 produit une image retina (résolution 2x, fichier plus lourd).

Exemples de code

curl

curl "https://webshotninja.com/api?token=YOUR_API_KEY&url=https%3A%2F%2Fexample.com&full=1&format=webp" -o shot.webp

PHP

$params = http_build_query([
    'token'  => 'YOUR_API_KEY',
    'url'    => 'https://example.com',
    'full'   => 1,
    'format' => 'webp',
]);
file_put_contents('shot.webp', file_get_contents('https://webshotninja.com/api?' . $params));

JavaScript (Node.js)

const params = new URLSearchParams({
  token: 'YOUR_API_KEY',
  url: 'https://example.com',
  full: '1',
  format: 'webp',
});
const res = await fetch('https://webshotninja.com/api?' + params);
require('fs').writeFileSync('shot.webp', Buffer.from(await res.arrayBuffer()));

Python

import requests

r = requests.get('https://webshotninja.com/api', params={
    'token': 'YOUR_API_KEY',
    'url': 'https://example.com',
    'full': 1,
    'format': 'webp',
})
open('shot.webp', 'wb').write(r.content)

URLs signées

Intégrez des URLs de capture dans votre frontend (ex : img src) sans exposer votre clé API. Signez la query string triée (tous les paramètres sauf sig) avec HMAC-SHA256 en utilisant votre secret de signature. Ajoutez user (votre ID), expires (timestamp Unix) et sig (la signature hex). La capture est servie et décomptée de votre quota. Votre secret est dans votre tableau de bord.

GET https://webshotninja.com/api?url=https://example.com&user=USER_ID&expires=TIMESTAMP&sig=HMAC_SHA256_HEX

Node.js

const crypto = require('crypto');
const params = new URLSearchParams({
  url: 'https://example.com',
  user: 'YOUR_USER_ID',
  expires: String(Math.floor(Date.now()/1000) + 3600), // 1h
});
const sorted = [...params].sort((a,b) => a[0].localeCompare(b[0]))
  .map(([k,v]) => encodeURIComponent(k)+'='+encodeURIComponent(v)).join('&');
const sig = crypto.createHmac('sha256', 'YOUR_SIGNING_SECRET')
  .update(sorted).digest('hex');
const url = 'https://webshotninja.com/api?' + sorted + '&sig=' + sig;

PHP

$params = ['url' => 'https://example.com', 'user' => 'YOUR_USER_ID',
           'expires' => (string)(time() + 3600)];
ksort($params);
$qs = implode('&', array_map(fn($k,$v) => rawurlencode($k).'='.rawurlencode($v),
      array_keys($params), $params));
$sig = hash_hmac('sha256', $qs, 'YOUR_SIGNING_SECRET');
$url = 'https://webshotninja.com/api?' . $qs . '&sig=' . $sig;

Rendu HTML

POST /api/render — transformer du HTML brut en image. Envoyez un body JSON avec un champ html (max 2 Mo) et votre token. Tous les paramètres de capture (width, height, format, css, js, selector, dark, device, scale…) sont acceptés. Idéal pour générer des images Open Graph / social cards. Réservé à l'API, décompté du quota.

POST https://webshotninja.com/api/render

curl -X POST https://webshotninja.com/api/render \
  -H "Content-Type: application/json" \
  -d '{"token":"YOUR_API_KEY","html":"<h1>Hello</h1><p>Social card</p>","width":1200,"height":630,"format":"png"}' \
  -o card.png

Réponse

L'image brute (Content-Type image/png, image/jpeg ou image/webp). En cas d'erreur, un objet JSON avec un champ error. L'en-tête X-Cache indique HIT (cache) ou MISS (capture fraîche).