API de avatares de marcador de posición
Avatares de marcador de posición gratuitos y sin clave, tanto para desarrollo como para producción. Apunta una etiqueta de imagen a una URL y obtén un SVG limpio y determinista de unos pocos cientos de bytes. No hay que registrarse ni instalar nada.
https://blankpfp.com/api/avatar
Ejemplos en vivo
Todas las imágenes de abajo las sirve en vivo el endpoint descrito en esta página.
Inicio rápido
Coloca la URL directamente en una etiqueta de imagen. Los tamaños van en píxeles y la forma por defecto es un círculo, así que no hace falta estilo adicional.
<img src="https://blankpfp.com/api/avatar/seed/alice/200" alt="Alice" width="200" height="200">O úsalo como fondo de CSS:
.avatar {
width: 96px;
height: 96px;
border-radius: 50%;
background-image: url("https://blankpfp.com/api/avatar/seed/alice/96");
background-size: cover;
}En JavaScript, construye la URL a partir de lo que identifique al usuario:
avatar.src = 'https://blankpfp.com/api/avatar/seed/' + encodeURIComponent(user.email) + '/200';Sintaxis de las URL
Las cuatro formas aceptan una altura opcional. Añade .json a cualquiera de ellas para obtener los metadatos descritos abajo en lugar de la imagen.
| URL | Qué obtienes |
|---|---|
/api/avatar/{width} |
Avatar cuadrado. La misma URL siempre resuelve la misma imagen. |
/api/avatar/{width}/{height} |
Lienzo no cuadrado, útil para banners anchos o avatares de historias. |
/api/avatar/seed/{seed}/{width} |
Avatar determinista derivado de cualquier cadena de semilla. |
/api/avatar/id/{id}/{width} |
Avatar determinista derivado de un identificador numérico, como una fila de base de datos. |
Semillas deterministas
Una semilla se resume en un color de una paleta de 48 tonos, así que la misma semilla siempre devuelve el mismo avatar, sin base de datos y sin guardar nada en disco. Usa un nombre de usuario, un correo electrónico o el id de un registro. Las semillas con espacios o símbolos deben codificarse en porcentaje, y /api/avatar/id/ es una abreviatura para identificadores 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 los parámetros son opcionales y se pueden combinar. Un valor no reconocido devuelve un 400 con una explicación en JSON en lugar de una imagen rota.
| Parámetro | Valores aceptados | Por defecto | Qué obtienes |
|---|---|---|---|
shape |
circle | rounded | square | circle | Contorno del avatar. El círculo es el valor por defecto porque la mayoría de plataformas recortan las fotos de perfil así. |
pattern |
solid | grid | dots | diagonal | checker | solid | Textura superpuesta al fondo. Sirve para distinguir los tipos de marcador a simple vista. |
bg |
#1E3A5F | seed | Color de fondo. Anula el color que habría elegido la semilla. |
fg |
#1E3A5F | auto | Color de las iniciales, las líneas del patrón o la silueta; se elige automáticamente por contraste si se omite. |
initials |
1-2 | - | Hasta dos letras, dígitos o símbolos dibujados en el centro. Un nombre completo se reduce a sus iniciales. |
figure |
1-15 | - | Id de silueta (1-15) o nombre, pintado en fg sobre bg. Tiene prioridad sobre las iniciales; ?figure a secas la quita. |
outline |
0 | 1 | 0 | |
grayscale |
0 | 1 | 0 | Quita todo el color. Útil para estados de interfaz atenuados o desactivados. |
blur |
0-10 | 0 | Radio del desenfoque gaussiano. El desenfoque se queda dentro de la forma, así que los bordes siguen nítidos. |
random |
?random=* | - | Cualquier valor. Devuelve un avatar distinto por valor en lugar de uno estable. |
Los colores hexadecimales pueden escribirse con o sin la almohadilla inicial, y la forma corta como #abc se expande. Sin bg el fondo viene de la semilla; sin fg la tinta se elige automáticamente para que siga siendo legible. Un desenfoque por encima del máximo se recorta en lugar de rechazarse, y las iniciales nunca superan dos caracteres.
Siluetas
Las mismas quince siluetas de busto que el generador, direccionables por id o por nombre. fg pinta la silueta y bg el fondo, así que un mismo id cambia de aspecto según la paleta.
Solid fill
Hollow outline (outline=1)
Pruébalo
Elige cualquier avatar de esta página y luego cambia los parámetros de abajo. La vista previa y el código se actualizan al momento, y lo que copies es exactamente lo que devuelve el endpoint.
Vista previa
URL
Formatos de respuesta
Las imágenes se devuelven como SVG, lo que mantiene un avatar típico entre 200 y 1000 bytes y lo deja nítido a cualquier densidad de píxeles. Añade .json a la misma URL para leer en su lugar los colores resueltos, útil para adaptar la interfaz al 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"
}Las solicitudes no válidas responden con un 400 y un cuerpo JSON:
{
"ok": false,
"error": "invalid_parameters",
"errors": ["pattern: expected one of solid, grid, dots, diagonal, checker"],
"docs": "https://blankpfp.com/docs"
}Caché y límites
Las URL con semilla son una función pura de la dirección, por lo que se sirven con una cabecera de caché inmutable de un año y un ETag. Pon un CDN delante de tu aplicación y las imágenes no te costarán nada tras la primera petición. El ancho y el alto pueden ir de 16 a 2048 píxeles; los valores mayores se recortan en lugar de rechazarse, y el tamaño final aparece en el JSON. Para mostrar una imagen distinta en cada petición, añade ?random= seguido de cualquier valor.
Preguntas frecuentes
¿Necesito una clave de API o una cuenta?
No. No hay registro, ni clave, ni cuota. Todas las URL de esta página funcionan tal cual mientras el sitio esté en línea.
¿La misma URL devolverá siempre el mismo avatar?
Sí. Una URL con semilla es una función pura de la dirección, así que es seguro fijarla en tu marcado, tu base de datos o tus pruebas. Las URL sin semilla también son estables por dirección, y ?random= es la forma explícita de renunciar a eso.
¿Puedo enlazar estas imágenes y usarlas comercialmente?
Sí. Las imágenes se generan en nuestro propio servidor a partir de formas vectoriales, así que no hay fotos de terceros, ni dudas de licencia, ni que atribuir. Enlázalas directamente o descárgalas.
¿Por qué SVG y cuáles son los límites de tamaño?
Un avatar SVG suele pesar unos cientos de bytes, escala a cualquier densidad de pantalla y se puede recolorear con CSS. El ancho y el alto pueden ir de 16 a 2048 píxeles; todo lo que supere eso se recorta a 2048.