Ferramentas · API
EasyPlaceholder
Avatares e placeholders sob medida, por URL.
API de avatar por semente e de placeholder em SVG: /avatar/<texto>.svg e /placeholder/600x400.svg, com cores, fonte, forma e mais pela query string.
Sobre o projeto
O que é o EasyPlaceholder
O EasyPlaceholder entrega imagens falsas na hora, por endereço: um avatar para cada nome (/avatar/Ana%20Souza.svg) e um placeholder de qualquer tamanho (/placeholder/600x400.svg). Serve para protótipos, telas de teste, documentação e listas de usuários que ainda não têm foto. Não precisa de chave nem de cadastro.
O avatar vem de uma semente: o mesmo texto gera sempre o mesmo avatar, em quatro estilos (iniciais, identicon, formas e rosto). A semente pode ser um nome, um e-mail ou um id. Tudo se ajusta pela query string: cor de fundo e degradê, cor do texto, fonte, peso e tamanho da letra, forma, borda, padrão de fundo e mais. O modo estrito (strict=1) troca o "ignorar o que está errado" por um erro com a lista, para serviços que querem saber quando erraram.
A API é o produto e o laboratório é o jeito fácil de montar a URL: os dois têm exatamente os mesmos parâmetros, que saem de um esquema só. O mesmo arquivo valida a API no servidor, monta os controles no navegador e gera a descrição OpenAPI, e um teste confere que a imagem do laboratório é igual à da API, byte a byte. O laboratório entrega trechos prontos de URL, HTML, Markdown, CSS, fetch, curl e Python, além de SVG e PNG.
Por baixo são SVGs gerados no servidor, sem guardar nada e sem dependência nova. Como quem usa uma URL não pode ver o avatar mudar de um dia para o outro, a saída de cada URL é congelada por teste: um visual novo entra como um estilo novo. Há limite de pedidos por IP, com cabeçalhos que dizem quanto ainda cabe, e números abertos (quantas imagens, pela API e pelo laboratório, o estilo e a opção mais usados), que são só contagens.
Recursos
O que o EasyPlaceholder faz
Avatar por semente
O mesmo texto gera sempre o mesmo avatar, em quatro estilos: iniciais, identicon, formas e rosto. A semente pode ser um nome, um e-mail ou um id.
Placeholder de qualquer tamanho
De 8 a 4096 pixels por lado, com as dimensões escritas no meio, diagonais opcionais e as mesmas cores, formas e padrões do avatar.
Tudo pela query string
Fundo e degradê, cor, fonte, peso e tamanho do texto, caixa, espaçamento, forma, borda e padrão de fundo. Valor inválido é ignorado e listado no cabeçalho X-Ignorados.
API e laboratório iguais
Um esquema só descreve os parâmetros: o laboratório monta um controle para cada um e a API valida com ele. A imagem do laboratório é a da API, byte a byte.
Duas formas de chamar
/avatar/Ana.svg ou /avatar?seed=Ana (e /placeholder/600x400.svg ou /placeholder?width=600&height=400): a segunda serve para texto com caracteres que atrapalham o caminho.
Modo estrito
Com strict=1, qualquer problema vira um erro 400 em JSON, com o nome do parâmetro, o motivo e o valor recebido. Sem ele, a API se comporta como uma imagem deve: nunca quebra a <img>.
Contraste automático
Sem cor de texto, a API escolhe branco ou azul-noite, o que tiver mais contraste com o fundo. As paletas dos avatares passam de 4,5:1 nas duas pontas do degradê.
Limites que avisam
Pedidos por IP por minuto e por hora, com RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset. Passou: 429 com Retry-After e uma imagem que explica o motivo.
Laboratório ao vivo
Um controle para cada parâmetro, prévia na hora, galeria de sementes, comparação dos estilos e exemplos prontos para carregar.
URL pronta para copiar
Copie a URL ou um trecho de HTML, Markdown, CSS, fetch, curl ou Python. O estado do laboratório vira o endereço da página, então o link da página compartilha o ajuste.
SVG e PNG
A API entrega SVG, que cabe em qualquer tamanho. O PNG é gerado no seu navegador, na resolução que você escolher.
Números abertos
A tela do laboratório mostra quantas imagens a API gerou, pela API e pelo laboratório, o estilo e a opção mais usados e quantos pedidos foram barrados. Só contagens.
Tecnologias
Por dentro do EasyPlaceholder
Funções puras
A semente e as opções entram e o texto do SVG sai: sem estado, sem banco e sem biblioteca de imagem. Dá para testar tudo no Node, e o servidor não guarda nada.
Um esquema para tudo
Um módulo ES puro descreve cada parâmetro (tipo, faixa, padrão e explicação). O servidor o importa para validar, o navegador o importa para montar os controles e validar o que se digita com as mesmas funções, e dele saem a tabela de documentação, o params.json e o OpenAPI 3.1.
Semente congelada
O texto vira um número com FNV-1a e acabamento do murmur3, e um gerador com semente (mulberry32) sorteia tudo. A ordem do sorteio e as paletas são fixas, e saídas congeladas nos testes avisam qualquer mudança.
SVG seguro
Todo texto é normalizado, sem caracteres de controle nem os que invertem o sentido da leitura, e escapado. Cor só em hex ou nome da lista, fonte só da lista ou com um nome curto, e a resposta leva uma CSP que impede qualquer execução.
Limites por IP medidos
Gerar uma imagem custa de 20 a 120 microssegundos de processador (medido), então os tetos são folgados: 600 por minuto e 6000 por hora. A contagem é uma janela deslizante em memória, e o erro 429 vira um SVG que explica, para a <img> de quem foi barrado mostrar o motivo.
Contadores em memória
Cada pedido só soma em memória; os números vão ao banco juntos, uma vez por minuto. Nenhum conteúdo vira contador: os nomes (estilo, opção, pela API ou pelo laboratório) vêm de uma lista fechada, e o Referer da página do laboratório separa as duas origens.
Contraste conferido
As paletas são testadas contra o texto automático nas duas pontas do degradê, e as cores dos desenhos descartam as que somem contra o fundo.
Cache e CORS
ETag e Cache-Control público de um dia com revalidação, CORS aberto e Cross-Origin-Resource-Policy liberada, para o SVG servir em qualquer página.
API
Endpoints
Sem chave e sem cadastro. Os parâmetros vão na query string; o que não for válido é ignorado e listado no cabeçalho X-Ignorados (ou vira erro 400 com strict=1).
/avatar/<texto>.svg
Avatar da semente. Ex.: /avatar/Ana%20Souza.svg?style=rosto&bg=fde68a
/avatar?seed=<texto>
A mesma imagem, com a semente na query (para texto que atrapalha o caminho).
/placeholder/<largura>x<altura>.svg
Placeholder. Ex.: /placeholder/600x400.svg?cross=1&bg=111827&color=fff
/placeholder?width=<n>&height=<n>
A mesma imagem, com as dimensões na query. Só um dos lados faz um quadrado.
/placeholder/<lado>.svg
Placeholder quadrado. Ex.: /placeholder/200.svg?shape=circle
/projetos/easyplaceholder/api/openapi.json
Descrição OpenAPI 3.1 da API, gerada do esquema.
/projetos/easyplaceholder/params.json
Todos os parâmetros, em JSON.
FAQ
Perguntas frequentes
Preciso de chave ou de conta?
Não. É só montar o endereço e usar. Há um limite de pedidos por IP (600 por minuto e 6000 por hora), com cabeçalhos que dizem quanto ainda cabe.
O mesmo nome gera sempre o mesmo avatar?
Gera. A semente é o texto do endereço depois de normalizado (sem controles, até 200 caracteres). A saída de uma URL existente é protegida por testes: um visual novo entra com um nome de estilo novo, e os avatares de hoje não mudam.
Dá para pedir PNG ou JPG?
A API entrega só SVG: sem fontes embutidas não dá para rasterizar texto de forma confiável no servidor. No laboratório há o botão de PNG, que converte no seu navegador, no tamanho que você escolher.
A fonte que escolhi não aparece. Por quê?
Dentro de uma <img> o SVG não carrega fontes da internet: vale a fonte instalada no aparelho de quem vê a página. As famílias sans, serif, mono, rounded, cursive e system usam listas de fontes comuns.
E se eu errar um valor?
Nada quebra. O valor inválido é ignorado e o nome do parâmetro vai no cabeçalho X-Ignorados; um número fora da faixa é ajustado ao limite mais próximo. Quem prefere saber do erro usa strict=1 e recebe um 400 em JSON com a lista.
O que acontece se eu passar do limite de pedidos?
A resposta é 429 com Retry-After. O corpo é um SVG pequeno que explica o motivo (assim a <img> mostra a mensagem em vez de um ícone quebrado); com strict=1 ou Accept: application/json, é JSON com o código rate_limited.
Quais são os limites de tamanho?
O placeholder vai de 8 a 4096 pixels por lado e o avatar, de 16 a 2048. A semente tem até 200 caracteres, o texto do avatar até 8 e o do placeholder até 120, em no máximo 4 linhas. O endereço inteiro vai até 4096 caracteres.
Como sei todos os parâmetros?
Pela tabela no laboratório, pelo params.json ou pelo openapi.json, que saem da mesma lista usada para validar a API.
O que acontece com o texto que eu mando?
Ele só serve para desenhar a imagem: a API não grava nada em banco nem em arquivo, e os números abertos guardam só contagens. Como em qualquer servidor, o endereço pode aparecer nos registros de acesso, então não use dados sensíveis como semente.
Como os números abertos são contados?
Cada imagem entregue soma um no estilo, no tipo e em "pela API" ou "pelo laboratório" (pelo Referer da página do laboratório). Imagens servidas pelo cache do navegador ou de uma CDN não chegam ao servidor e não entram na conta. Os avisos de copiar e baixar do laboratório respeitam o "Não rastrear".
Posso usar em outro site?
Pode: a resposta libera CORS e uso entre origens, então funciona em <img>, em CSS e em fetch.
Gostou do EasyPlaceholder? Dá para apoiar o trabalho: Me pague um café
Continue explorando
Veja também
Mercado Helper
Listas de compras para usar no celular: marque o que foi para o carrinho, veja o total e consulte o histórico.
Ver projeto No arShareSoFast
Compartilhe um arquivo de até 25 MB por um link curto, com senha e uma carta opcional. Depois de 1 dia, tudo é apagado de verdade.
Ver projeto No arRec2Link
Grave a tela, o áudio, os dois ou só a webcam direto no navegador. O arquivo é comprimido aí mesmo, ganha um link curto e é apagado sozinho em 24 horas.
Ver projeto