API de avatares de espaço reservado
Avatares de espaço reservado gratuitos e sem chave, tanto para desenvolvimento quanto para produção. Aponte uma tag de imagem para uma URL e receba um SVG limpo e determinístico com apenas algumas centenas de bytes. Nada para cadastrar, nada para instalar.
https://blankpfp.com/api/avatar
Exemplos ao vivo
Todas as imagens abaixo são servidas ao vivo pelo endpoint documentado nesta página.
Início rápido
Coloque a URL diretamente em uma tag de imagem. Os tamanhos são em pixels e o formato padrão é um círculo, então nenhum estilo extra é necessário.
<img src="https://blankpfp.com/api/avatar/seed/alice/200" alt="Alice" width="200" height="200">Ou use como fundo de CSS:
.avatar {
width: 96px;
height: 96px;
border-radius: 50%;
background-image: url("https://blankpfp.com/api/avatar/seed/alice/96");
background-size: cover;
}Em JavaScript, monte a URL a partir do que identificar o usuário:
avatar.src = 'https://blankpfp.com/api/avatar/seed/' + encodeURIComponent(user.email) + '/200';Sintaxe das URLs
Todas as quatro formas aceitam uma altura opcional. Acrescente .json a qualquer uma delas para obter os metadados descritos abaixo em vez da imagem.
| URL | O que você obtém |
|---|---|
/api/avatar/{width} |
Avatar quadrado. A mesma URL sempre resolve a mesma imagem. |
/api/avatar/{width}/{height} |
Tela não quadrada, útil para banners largos ou avatares de story. |
/api/avatar/seed/{seed}/{width} |
Avatar determinístico derivado de qualquer string de semente. |
/api/avatar/id/{id}/{width} |
Avatar determinístico derivado de um id numérico, como uma linha de banco de dados. |
Sementes determinísticas
Uma semente é transformada em hash em uma cor de uma paleta de 48 tons, então a mesma semente sempre devolve o mesmo avatar, sem banco de dados e sem nada gravado em disco. Use um nome de usuário, um e-mail ou o id de um registro. Sementes com espaços ou símbolos precisam ser codificadas em porcentagem, e /api/avatar/id/ é um atalho para ids numéricos.
<img src="https://blankpfp.com/api/avatar/seed/alice/200" alt="alice">\n<img src="https://blankpfp.com/api/avatar/seed/bob/200" alt="bob">\n<img src="https://blankpfp.com/api/avatar/id/237/200" alt="record 237">Parâmetros de consulta
Todos os parâmetros são opcionais e podem ser combinados. Um valor não reconhecido retorna 400 com uma explicação em JSON em vez de uma imagem quebrada.
| Parâmetro | Valores aceitos | Padrão | O que você obtém |
|---|---|---|---|
shape |
circle | rounded | square | circle | Contorno do avatar. O círculo é o padrão porque a maioria das plataformas recorta fotos de perfil assim. |
pattern |
solid | grid | dots | diagonal | checker | solid | Textura aplicada sobre o fundo. Útil para distinguir os tipos de espaço reservado de relance. |
bg |
#1E3A5F | seed | Cor de fundo. Substitui a cor que a semente teria escolhido. |
fg |
#1E3A5F | auto | Cor das iniciais, das linhas do padrão ou da silhueta; escolhida automaticamente por contraste quando omitida. |
initials |
1-2 | - | Até duas letras, dígitos ou símbolos desenhados no centro. Um nome completo é reduzido às iniciais. |
figure |
1-15 | - | Id da silhueta (1-15) ou nome, desenhado em fg sobre bg. Tem prioridade sobre as iniciais; ?figure sozinho a remove. |
outline |
0 | 1 | 0 | |
grayscale |
0 | 1 | 0 | Remove todas as cores. Útil para estados de interface esmaecidos ou desativados. |
blur |
0-10 | 0 | Raio do desfoque gaussiano. O desfoque fica dentro da forma, então as bordas continuam nítidas. |
random |
?random=* | - | Qualquer valor. Devolve um avatar diferente por valor em vez de um avatar estável. |
Cores hexadecimais podem ser escritas com ou sem o cerquinha inicial, e a forma curta como #abc é expandida. Sem bg o fundo vem da semente; sem fg a tinta é escolhida automaticamente para continuar legível. Um desfoque acima do máximo é limitado em vez de rejeitado, e as iniciais nunca ultrapassam dois caracteres.
Silhuetas
As mesmas quinze silhuetas de busto do gerador, acessíveis por id ou por nome. fg pinta a silhueta e bg o fundo, então o mesmo id fica com outro visual em cada paleta.
Solid fill
Hollow outline (outline=1)
Experimente
Escolha qualquer avatar desta página e depois altere os parâmetros abaixo. A pré-visualização e o código são atualizados na hora, e o que você copia é exatamente o que o endpoint devolve.
Pré-visualização
URL
Formatos de resposta
As imagens são devolvidas em SVG, o que mantém um avatar típico entre 200 e 1000 bytes e nítido em qualquer densidade de pixels. Acrescente .json à mesma URL para ler em vez disso as cores resolvidas, prático para combinar a interface ao redor com o avatar.
{
"ok": true,
"mode": "seed",
"seed": "alice",
"width": 200,
"height": 200,
"shape": "circle",
"pattern": "solid",
"figure": null,
"background": "#9CA3AF",
"foreground": "#111827",
"initials": null,
"outline": false,
"grayscale": false,
"blur": 0,
"format": "svg",
"bytes": 266,
"url": "https://blankpfp.com/api/avatar/seed/alice/200/200.svg",
"info": "https://blankpfp.com/api/avatar/seed/alice/200/200.json"
}Requisições inválidas respondem com 400 e um corpo JSON:
{
"ok": false,
"error": "invalid_parameters",
"errors": ["pattern: expected one of solid, grid, dots, diagonal, checker"],
"docs": "https://blankpfp.com/docs"
}Cache e limites
URLs com semente são uma função pura do endereço, por isso são servidas com um cabeçalho de cache imutável de um ano e um ETag. Coloque um CDN na frente da sua aplicação e as imagens não custam mais nada após a primeira requisição. Largura e altura podem ir de 16 a 2048 pixels; valores maiores são limitados em vez de rejeitados, e o tamanho final volta no JSON. Para mostrar uma imagem diferente a cada requisição, acrescente ?random= seguido de qualquer valor.
Perguntas frequentes
Preciso de uma chave de API ou de uma conta?
Não. Não há cadastro, chave nem cota. Todas as URLs desta página funcionam como estão enquanto o site estiver no ar.
A mesma URL sempre devolve o mesmo avatar?
Sim. Uma URL com semente é uma função pura do endereço, então é seguro fixá-la no seu markup, no banco de dados ou nos testes. URLs sem semente também são estáveis por endereço, e ?random= é a forma explícita de desistir disso.
Posso incorporar estas imagens e usá-las comercialmente?
Sim. As imagens são geradas no nosso próprio servidor a partir de formas vetoriais, então não há fotos de terceiros, nem questões de licenciamento, nem exigência de atribuição. Incorpore diretamente ou baixe.
Por que SVG e quais são os limites de tamanho?
Um avatar SVG costuma pesar algumas centenas de bytes, escala para qualquer densidade de tela e pode ser recolorido com CSS. Largura e altura podem ir de 16 a 2048 pixels; acima disso o valor é limitado a 2048.