O que este artigo aborda

Se você está entregando apps whitelabel — ou mesmo apenas um app com múltiplas listagens de loja — você provavelmente já encontrou o problema dos screenshots. A Apple quer screenshots para cada tamanho de dispositivo. O Google Play quer seu próprio conjunto. Suporte a três idiomas e você triplicou sua carga de trabalho. Agora multiplique isso pelo número de variantes de marca que você mantém.

O artigo anterior explicou por que o Screenshots Live existe. Este é o acompanhamento prático: como a API de renderização foi projetada, o que ela espera, e como integrá-la ao seu pipeline de build para que os screenshots deixem de ser uma tarefa manual.

Como o pipeline de renderização foi projetado

O sistema de renderização não é um endpoint síncrono do tipo "enviar requisição, receber imagem". É um pipeline baseado em jobs, o que importa quando você está renderizando dezenas ou centenas de screenshots em lote.

Aqui está o fluxo:

Você envia uma requisição de renderização com um ID de template e overrides YAML opcionais (texto, screenshots, molduras de dispositivo — qualquer coisa marcada como substituível).
Validação — o sistema verifica se seu template existe, se você é o proprietário, e se cada campo que você está sobrescrevendo é realmente permitido. URLs são validadas contra faixas de IP privadas e protocolos restritos.
Enfileiramento — o job entra em uma fila BullMQ com backup em Redis. Sua chamada de API retorna imediatamente com um jobId e o status Pending. Esta é a chave: você não espera a renderização terminar.
Renderização — um worker baseado em Rust pega o job, busca o template e as imagens (com cache LRU para renderizações repetidas), carrega fontes, renderiza o canvas usando Skia e gera a saída.
Empacotamento — as imagens renderizadas são compactadas em ZIP e enviadas para o armazenamento de objetos.
Download — você consulta o endpoint de status. Quando está Completed, você acessa o endpoint de download para obter uma URL pré-assinada (válida por 1 hora).

O design assíncrono é intencional. Quando você precisa renderizar 50 templates para um release, você os dispara todos, depois coleta os resultados. Sem bloqueio, sem timeouts.

Autenticação

Você precisa de uma conta Pro para acessar a API de renderização. Crie uma chave de API no seu painel — ela se parecerá com sa_live_.... Cada requisição a usa como Bearer token:

Authorization: Bearer sa_live_your_key_here

Templates: Como são estruturados

Tudo gira em torno dos templates. Um template é um canvas que você constrói no editor visual — você posiciona blocos de texto, molduras de dispositivo, imagens e define fundos. Cada elemento no canvas é um item com um UUID único.

Para automação, o conceito crítico são os campos substituíveis. Nem toda propriedade de todo item é sobrescrevível via API. Um administrador configura quais campos podem ser trocados — conteúdo do texto, família de fonte, tamanho de fonte, cores, URLs de screenshots, IDs de molduras de dispositivo e assim por diante. Esta é uma restrição deliberada: ela impede que consumidores da API quebrem acidentalmente o layout ao mudar posições ou tamanhos que o designer bloqueou.

Pense nisso como um contrato entre seu designer e seu pipeline: o designer é dono do layout, o pipeline é dono do conteúdo.

O sistema de override YAML

Este é o núcleo da API. Em vez de renderizar um template exatamente como foi salvo, você envia um POST com YAML que sobrescreve campos específicos em itens específicos.

Passo 1: Obter o scaffold YAML

Cada template tem um endpoint de scaffold que retorna todos os campos substituíveis como YAML comentado:

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

Passo 2: Enviar a renderização

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: "Rastreie suas entregas"
    color: "#1A73E8"'

Passo 3: Consultar o status

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

O status progride de Pending → Active → Completed (ou Failed se algo deu errado). Para a maioria dos templates, a renderização leva alguns segundos.

Passo 4: Baixar

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

Retorna uma URL pré-assinada. O download é um ZIP contendo suas imagens renderizadas.

Upload direto de screenshots

Você não precisa hospedar seus screenshots em algum lugar só para passar uma URL. O endpoint /render/api/with-pictures aceita uploads multipart. Você pode anexar até 200 arquivos, cada um com até 10MB. Isso é o que torna a API prática para CI/CD — seu pipeline captura screenshots e você os envia diretamente para renderização sem precisar de armazenamento intermediário.

Exemplo real: Pipeline whitelabel

Aqui está um cenário concreto. Você mantém 5 marcas whitelabel, cada uma precisando de screenshots da App Store em 3 idiomas em 5 telas principais. São 75 imagens renderizadas por release. Seu designer criou um template por tela no editor, com o texto do título e a moldura do dispositivo marcados como substituíveis. Seu pipeline CI captura screenshots brutos por marca e localidade usando o snapshot/screengrab do Fastlane. O design assíncrono ajuda — os envios são rápidos, a renderização real acontece em segundo plano.

Troca de molduras de dispositivo

Molduras de dispositivo são os overlays de mockup — iPhone 16 Pro, Pixel 9, iPad Air, Galaxy S24. Eles são pré-carregados em sua conta e referenciados por UUID. O mesmo template pode renderizar com molduras de dispositivo diferentes sobrescrevendo o frameId. É assim que você lida com a divisão App Store vs Google Play. Mesmo layout de template, mesmo screenshot, moldura diferente.

Limites de taxa e cotas

API de renderização: 5 requisições por 60 segundos
Consulta de status: 60 requisições por 60 segundos
Renderizações diárias: 100 por dia no tier Pro
Uploads de imagens: máx. 200 arquivos por requisição, 10MB cada

Validação YAML

O parser YAML é deliberadamente rigoroso: sem âncoras, sem aliases, sem tags customizadas, máx. 1MB. Se algo estiver errado, a mensagem de erro diz exatamente o quê — nome de campo errado, campo não substituível, formato UUID inválido, URL apontando para uma faixa de IP privada. É projetado para falhar rápido e claramente, o que importa quando você está depurando um pipeline CI às 23h.