API di avatar segnaposto

Esempi dal vivo

Tutte le immagini qui sotto sono servite dal vivo dall’endpoint documentato in questa pagina.

200roundedsquareBPgriddotsdiagonalcheckerid 237grayblur 4colors

Guida rapida

Inserisci l’URL direttamente in un tag img. Le dimensioni sono in pixel e la forma predefinita è un cerchio, quindi non serve altro stile.

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

Oppure usalo come sfondo CSS:

.avatar {
  width: 96px;
  height: 96px;
  border-radius: 50%;
  background-image: url("https://blankpfp.com/api/avatar/seed/alice/96");
  background-size: cover;
}

In JavaScript, costruisci l’URL da ciò che identifica l’utente:

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

Sintassi degli URL

Tutte e quattro le forme accettano un’altezza opzionale. Aggiungi .json a una qualsiasi di esse per ottenere i metadati descritti sotto invece dell’immagine.

Seed deterministici

Un seed viene trasformato in hash in uno dei colori di una tavolozza da 48 tonalità, quindi lo stesso seed restituisce sempre lo stesso avatar, senza database e senza nulla salvato su disco. Usa un nome utente, un indirizzo email o l’id di un record. I seed contenenti spazi o simboli vanno codificati in percentuale e /api/avatar/id/ è la scorciatoia per gli id numerici.

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

Parametri di query

Tutti i parametri sono opzionali e combinabili. Un valore non riconosciuto restituisce un 400 con una spiegazione JSON invece di un’immagine rotta.

I colori esadecimali si possono scrivere con o senza il cancelletto iniziale, e la forma breve come #abc viene espansa. Senza bg lo sfondo proviene dal seed; senza fg l’inchiostro viene scelto automaticamente per restare leggibile. Una sfocatura oltre il massimo viene limitata invece di essere rifiutata, e le iniziali non superano mai due caratteri.

Sagome

Le stesse quindici sagome a busto del generatore, richiamabili per id o per nome. fg colora la sagoma e bg lo sfondo, quindi lo stesso id ha un aspetto diverso su ogni palette.

Solid fill

defaultmalefemaleelderchildcartoonheadshotprofileroundheadhoodielonghairbuncapbeaniecurlytallathleticslimbroadpetitelargeshorthairwavyponytailpigtailsbaldrecedingafromohawksidepartbobfedoratophatberetcrownglasses_roundglasses_squareglasses_aviatorheadphonesbeard_fullbeard_goateemustachecollaredturtleneckscarftieprofile_leftprofile_righthipstersurfernerdexecutiveartist

Hollow outline (outline=1)

defaultmalefemaleelderchildcartoonheadshotprofileroundheadhoodielonghairbuncapbeaniecurlytallathleticslimbroadpetitelargeshorthairwavyponytailpigtailsbaldrecedingafromohawksidepartbobfedoratophatberetcrownglasses_roundglasses_squareglasses_aviatorheadphonesbeard_fullbeard_goateemustachecollaredturtleneckscarftieprofile_leftprofile_righthipstersurfernerdexecutiveartist

Provalo

Scegli un avatar qualsiasi in questa pagina, poi modifica i parametri qui sotto. Anteprima e codice si aggiornano subito, e ciò che copi è esattamente quello che restituisce l’endpoint.

Anteprima

Forma circle rounded square Motivo solid grid dots diagonal checker Iniziali

Sfondo auto

Primo piano auto

Sfocatura

0

Outline Scala di grigi

Ripristina

URL

Formati di risposta

Le immagini sono restituite come SVG, il che mantiene un avatar tipico tra 200 e 1000 byte e lo mantiene nitido a qualsiasi densità di pixel. Aggiungi .json allo stesso URL per leggere invece i colori risolti, comodo per abbinare l’interfaccia circostante all’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"
}

Le richieste non valide rispondono con un 400 e un corpo JSON:

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

Cache e limiti

Gli URL con seed sono una funzione pura dell’indirizzo, quindi vengono serviti con un’intestazione di cache immutabile di un anno e un ETag. Metti un CDN davanti alla tua app e dopo la prima richiesta le immagini non ti costano più nulla. Larghezza e altezza possono andare da 16 a 2048 pixel; i valori maggiori vengono ridotti anziché rifiutati, e la dimensione risultante torna nel JSON. Per mostrare un’immagine diversa a ogni richiesta, aggiungi ?random= seguito da un valore qualsiasi.

FAQ

Strumenti correlati