Wat dit artikel behandelt

Als je whitelabel-apps levert — of zelfs maar één app met meerdere winkellijsten — heb je waarschijnlijk het screenshot-probleem al ervaren. Apple wil screenshots voor elke apparaatgrootte. Google Play wil zijn eigen set. Drie talen ondersteunen en je hebt je werkdruk verdrievoudigd. Vermenigvuldig dat nu met het aantal merkvaranten dat je onderhoudt.

Het vorige artikel legde uit waarom Screenshots Live bestaat. Dit is de praktische vervolg: hoe de render API is ontworpen, wat het verwacht, en hoe je het in je buildpipeline kunt integreren zodat screenshots geen handmatige taak meer zijn.

Hoe de renderpipeline is ontworpen

Het rendersysteem is geen synchrone "stuur verzoek, ontvang afbeelding" endpoint. Het is een op taken gebaseerde pipeline, wat belangrijk is wanneer je tientallen of honderden screenshots in batch rendert.

Hier is de flow:

Je dient een renderverzoek in met een sjabloon-ID en optionele YAML-overschrijvingen (tekst, screenshots, apparaatframes — alles dat als verwisselbaar is gemarkeerd).
Validatie — het systeem controleert of je sjabloon bestaat, of jij de eigenaar bent, en of elk veld dat je overschrijft daadwerkelijk is toegestaan. URL's worden gevalideerd op privé-IP-bereiken en beperkte protocollen.
Wachtrij — de taak komt in een Redis-ondersteunde BullMQ-wachtrij. Je API-aanroep keert onmiddellijk terug met een jobId en de status Pending. Dit is de sleutel: je wacht niet tot het renderen klaar is.
Renderen — een Rust-gebaseerde worker pakt de taak op, haalt het sjabloon en afbeeldingen op (met LRU-cache voor herhaalde renders), laadt lettertypen, rendert het canvas met Skia en genereert de output.
Verpakking — de gerenderde afbeeldingen worden ingepakt als ZIP en geüpload naar objectopslag.
Download — je pollt het statusendpoint. Wanneer het Completed is, raadpleeg je het downloadendpoint voor een vooraf ondertekende URL (1 uur geldig).

Het asynchrone ontwerp is opzettelijk. Wanneer je 50 sjablonen voor een release moet renderen, schiet je ze allemaal tegelijk af en verzamel je daarna de resultaten. Geen blokkering, geen timeouts.

Authenticatie

Je hebt een Pro-account nodig om toegang te krijgen tot de render API. Maak een API-sleutel aan via je dashboard — die ziet eruit als sa_live_.... Elk verzoek gebruikt het als Bearer-token:

Authorization: Bearer sa_live_your_key_here

Sjablonen: Hoe ze zijn opgebouwd

Alles draait om sjablonen. Een sjabloon is een canvas dat je bouwt in de visuele editor — je plaatst tekstblokken, apparaatframes, afbeeldingen en stelt achtergronden in. Elk element op het canvas is een item met een unieke UUID.

Voor automatisering is het kritieke concept de verwisselbare velden. Niet elke eigenschap van elk item is overschrijfbaar via de API. Een beheerder configureert welke velden kunnen worden verwisseld — tekstinhoud, lettertype, lettergrootte, kleuren, screenshot-URL's, apparaatframe-ID's enzovoort. Dit is een opzettelijke beperking: het voorkomt dat API-gebruikers per ongeluk de lay-out breken door posities of formaten te wijzigen die de ontwerper heeft vergrendeld.

Zie het als een contract tussen je ontwerper en je pipeline: de ontwerper bezit de lay-out, de pipeline bezit de inhoud.

Het YAML-overschrijvingssysteem

Dit is de kern van de API. In plaats van een sjabloon precies zo te renderen als het is opgeslagen, POST je YAML die specifieke velden op specifieke items overschrijft.

Stap 1: Haal de YAML-scaffold op

Elk sjabloon heeft een scaffold-endpoint dat alle verwisselbare velden retourneert als becommentarieerde YAML:

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

Stap 2: Dien de render in

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: "Volg je leveringen"
    color: "#1A73E8"'

Stap 3: Poll de status

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

De status loopt door Pending → Active → Completed (of Failed als er iets mis ging). Voor de meeste sjablonen duurt het renderen een paar seconden.

Stap 4: Download

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

Retourneert een vooraf ondertekende URL. De download is een ZIP met je gerenderde afbeeldingen.

Screenshots direct uploaden

Je hoeft je screenshots niet ergens te hosten alleen om een URL door te geven. Het /render/api/with-pictures-endpoint accepteert multipart-uploads. Je kunt tot 200 bestanden bijvoegen, elk tot 10 MB. Dit maakt de API praktisch voor CI/CD — je pipeline vangt screenshots op en je stuurt ze rechtstreeks naar de render zonder tussenliggende opslag te behoeven.

Apparaatframes wisselen

Apparaatframes zijn de mockup-overlays — iPhone 16 Pro, Pixel 9, iPad Air, Galaxy S24. Ze zijn voorgeladen in je account en worden verwezen door UUID. Hetzelfde sjabloon kan renderen met verschillende apparaatframes door de frameId te overschrijven. Zo handel je de App Store vs Google Play-splitsing af. Dezelfde sjabloonlay-out, dezelfde screenshot, ander frame.

Snelheidsbeperkingen en quota's

Render API: 5 verzoeken per 60 seconden
Status polling: 60 verzoeken per 60 seconden
Dagelijkse renders: 100 per dag op Pro-tier
Afbeeldinguploads: max. 200 bestanden per verzoek, 10 MB elk

YAML-validatie

De YAML-parser is opzettelijk strikt: geen ankers, geen aliassen, geen aangepaste tags, max. 1 MB. Als er iets mis is, vertelt de foutmelding je precies wat — verkeerde veldnaam, niet-verwisselbaar veld, ongeldig UUID-formaat, URL die naar een privé-IP-bereik wijst. Het is ontworpen om snel en duidelijk te falen, wat belangrijk is wanneer je om 23:00 een CI-pipeline debugt.