Ce que couvre cet article

Si vous livrez des applications whitelabel — ou même une seule application avec plusieurs fiches de store — vous avez probablement rencontré le problème des screenshots. Apple veut des screenshots pour chaque taille d'appareil. Google Play veut son propre set. Supportez trois langues et vous avez triplé votre charge de travail. Multipliez ensuite par le nombre de variantes de marque que vous maintenez.

L'article précédent expliquait pourquoi Screenshots Live existe. Celui-ci est le suivi pratique : comment l'API de rendu est conçue, ce qu'elle attend, et comment l'intégrer dans votre pipeline de build pour que les screenshots ne soient plus une tâche manuelle.

Comment le pipeline de rendu est conçu

Le système de rendu n'est pas un endpoint synchrone du type « envoyer une requête, recevoir une image ». C'est un pipeline basé sur des jobs, ce qui compte dès lors que vous rendez des dizaines ou des centaines de screenshots en lot.

Voici le flux :

Vous soumettez une requête de rendu avec un ID de template et des overrides YAML optionnels (texte, screenshots, cadres d'appareils — tout ce qui est marqué comme modifiable).
Validation — le système vérifie que votre template existe, que vous en êtes propriétaire, et que chaque champ que vous surchargez est bien autorisé. Les URLs sont validées contre les plages IP privées et les protocoles restreints.
File d'attente — le job entre dans une file BullMQ sauvegardée par Redis. Votre appel API retourne immédiatement avec un jobId et le statut Pending. C'est la clé : vous n'attendez pas la fin du rendu.
Rendu — un worker basé sur Rust prend le job, récupère le template et les images (avec un cache LRU pour les rendus répétés), charge les polices, rend le canvas avec Skia, et génère la sortie.
Packaging — les images rendues sont compressées en ZIP et uploadées vers le stockage objet.
Téléchargement — vous interrogez l'endpoint de statut. Quand il est Completed, vous appelez l'endpoint de téléchargement pour obtenir une URL présignée (valide 1 heure).

La conception asynchrone est intentionnelle. Quand vous devez rendre 50 templates pour une release, vous les lancez tous, puis collectez les résultats. Pas de blocage, pas de timeouts.

Authentification

Vous avez besoin d'un compte Pro pour accéder à l'API de rendu. Créez une clé API depuis votre tableau de bord — elle ressemblera à sa_live_.... Chaque requête l'utilise comme Bearer token :

Authorization: Bearer sa_live_your_key_here

Templates : Comment ils sont structurés

Tout tourne autour des templates. Un template est un canvas que vous construisez dans l'éditeur visuel — vous placez des blocs de texte, des cadres d'appareils, des images, et définissez des arrière-plans. Chaque élément sur le canvas est un item avec un UUID unique.

Pour l'automatisation, le concept critique est celui des champs modifiables. Toutes les propriétés de tous les items ne sont pas surchargeables via l'API. Un administrateur configure quels champs peuvent être modifiés — contenu du texte, famille de polices, taille de police, couleurs, URLs de screenshots, IDs de cadres d'appareils, etc. C'est une contrainte délibérée : elle empêche les consommateurs de l'API de casser accidentellement la mise en page en modifiant des positions ou des tailles que le designer a verrouillées.

Considérez-le comme un contrat entre votre designer et votre pipeline : le designer possède la mise en page, le pipeline possède le contenu.

Le système d'override YAML

C'est le cœur de l'API. Au lieu de rendre un template exactement tel qu'il est sauvegardé, vous POST du YAML qui surcharge des champs spécifiques sur des items spécifiques.

Étape 1 : Obtenir le scaffold YAML

Chaque template a un endpoint scaffold qui retourne tous les champs modifiables en YAML commenté :

curl -H "Authorization: Bearer sa_live_your_key_here" \
  https://api.screenshots.live/templates/YOUR_TEMPLATE_ID/yaml

Étape 2 : Soumettre le rendu

curl -X POST https://api.screenshots.live/render/api \
  -H "Authorization: Bearer sa_live_your_key_here" \
  -H "Content-Type: text/yaml" \
  -d 'templateId: "550e8400-e29b-41d4-a716-446655440000"
items:
  - itemId: "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    type: Text
    text: "Suivez vos livraisons"
    color: "#1A73E8"'

Étape 3 : Interroger le statut

curl -H "Authorization: Bearer sa_live_your_key_here" \
  https://api.screenshots.live/render/api/JOB_ID

Le statut progresse de Pending → Active → Completed (ou Failed si quelque chose a mal tourné). Pour la plupart des templates, le rendu prend quelques secondes.

Étape 4 : Télécharger

curl -H "Authorization: Bearer sa_live_your_key_here" \
  https://api.screenshots.live/render/JOB_ID/download

Retourne une URL présignée. Le téléchargement est un ZIP contenant vos images rendues.

Upload direct de screenshots

Vous n'avez pas besoin d'héberger vos screenshots pour passer une URL. L'endpoint /render/api/with-pictures accepte les uploads multipart.

Limites de débit et quotas

API de rendu : 5 requêtes par 60 secondes
Interrogation du statut : 60 requêtes par 60 secondes
Rendus quotidiens : 100 par jour en tier Pro
Upload de fichiers : max 200 fichiers par requête, 10 Mo chacun

Validation YAML

Le parseur YAML est délibérément strict : pas d'ancres, pas d'alias, pas de tags personnalisés, max 1 Mo. En cas d'erreur, le message vous dit exactement quoi — mauvais nom de champ, champ non modifiable, format UUID invalide, URL pointant vers une plage IP privée. Il est conçu pour échouer vite et clairement, ce qui compte quand vous déboguez un pipeline CI à 23h.