API d’avatars de remplacement

Exemples en direct

Toutes les images ci-dessous sont servies en direct par le point d’accès décrit sur cette page.

200roundedsquareBPgriddotsdiagonalcheckerid 237grayblur 4colors

Démarrage rapide

Placez l’URL directement dans une balise image. Les tailles sont en pixels et la forme par défaut est un cercle, donc aucun style supplémentaire n’est nécessaire.

<img src="https://blankpfp.com/api/avatar/seed/alice/200" alt="Alice" width="200" height="200">

Ou utilisez-la comme arrière-plan 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, construisez l’URL à partir de ce qui identifie l’utilisateur :

avatar.src = 'https://blankpfp.com/api/avatar/seed/' + encodeURIComponent(user.email) + '/200';

Syntaxe des URL

Les quatre formes acceptent une hauteur facultative. Ajoutez .json à n’importe laquelle pour obtenir les métadonnées décrites ci-dessous au lieu de l’image.

Graines déterministes

Une graine est hachée en une couleur parmi une palette de 48 teintes : la même graine renvoie donc toujours le même avatar, sans base de données et sans rien stocker sur le disque. Utilisez un nom d’utilisateur, une adresse e-mail ou un identifiant d’enregistrement. Les graines contenant des espaces ou des symboles doivent être encodées en pourcentage, et /api/avatar/id/ est un raccourci pour les identifiants numériques.

<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">

Paramètres de requête

Tous les paramètres sont facultatifs et peuvent être combinés. Une valeur non reconnue renvoie une erreur 400 accompagnée d’une explication JSON plutôt qu’une image cassée.

Les couleurs hexadécimales s’écrivent avec ou sans le dièse initial, et la forme courte comme #abc est développée. Sans bg, le fond vient de la graine ; sans fg, l’encre est choisie automatiquement pour rester lisible. Un flou supérieur au maximum est ramené au maximum au lieu d’être refusé, et les initiales ne dépassent jamais deux caractères.

Silhouettes

Les mêmes quinze silhouettes en buste que le générateur, adressables par identifiant ou par nom. fg peint la silhouette et bg le fond, donc un même identifiant change d’allure selon la palette.

Solid fill

defaultmalefemaleelderchildcartoonheadshotprofileroundheadhoodielonghairbuncapbeaniecurlytallathleticslimbroadpetitelargeshorthairwavyponytailpigtailsbaldrecedingafromohawksidepartbobfedoratophatberetcrownglasses_roundglasses_squareglasses_aviatorheadphonesbeard_fullbeard_goateemustachecollaredturtleneckscarftieprofile_leftprofile_righthipstersurfernerdexecutiveartist

Hollow outline (outline=1)

defaultmalefemaleelderchildcartoonheadshotprofileroundheadhoodielonghairbuncapbeaniecurlytallathleticslimbroadpetitelargeshorthairwavyponytailpigtailsbaldrecedingafromohawksidepartbobfedoratophatberetcrownglasses_roundglasses_squareglasses_aviatorheadphonesbeard_fullbeard_goateemustachecollaredturtleneckscarftieprofile_leftprofile_righthipstersurfernerdexecutiveartist

Essayez

Choisissez un avatar sur cette page, puis modifiez les paramètres ci-dessous. L’aperçu et le code se mettent à jour, et ce que vous copiez est exactement ce que le point de terminaison renvoie.

Aperçu

Forme circle rounded square Motif solid grid dots diagonal checker Initiales

Arrière-plan auto

Premier plan auto

Flou

0

Outline Niveaux de gris

Réinitialiser

URL

Formats de réponse

Les images sont renvoyées en SVG, ce qui maintient un avatar typique entre 200 et 1000 octets et le net à toute densité de pixels. Ajoutez .json à la même URL pour lire à la place les couleurs résolues, pratique pour accorder l’interface autour à l’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"
}

Les requêtes invalides répondent par un 400 et un corps JSON :

{
  "ok": false,
  "error": "invalid_parameters",
  "errors": ["pattern: expected one of solid, grid, dots, diagonal, checker"],
  "docs": "https://blankpfp.com/docs"
}

Cache et limites

Les URL avec graine sont une fonction pure de l’adresse : elles sont donc servies avec un en-tête de cache immuable d’un an et un ETag. Placez un CDN devant votre application et les images ne vous coûteront plus rien après la première requête. La largeur et la hauteur peuvent aller de 16 à 2048 pixels ; les valeurs plus grandes sont ramenées à la limite plutôt que rejetées, et la taille retenue figure dans le JSON. Pour afficher une image différente à chaque requête, ajoutez ?random= suivi de n’importe quelle valeur.

FAQ

Outils associés