預設頭像 API

適用於開發與正式環境的免費預設頭像，無需金鑰。把圖片網址填進圖片標籤，幾百位元組就能取得乾淨的確定性 SVG。無需註冊，也不必安裝任何東西。

https://blankpfp.com/api/avatar

即時範例

以下所有圖片都由本頁介紹的介面即時回傳。

快速開始

把網址直接寫進圖片標籤即可。尺寸單位為像素，預設形狀為圓形，不需額外樣式。

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

或作為 CSS 背景使用：

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

在 JavaScript 中，用能辨識使用者的資訊組出網址：

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

網址格式

這四種形式都可以省略高度。在任一形式後加上 .json，即可回傳下文介紹的中繼資料而非圖片。

網址	回傳內容
`/api/avatar/{width}`	正方形頭像。同一網址永遠回傳同一張圖片。
`/api/avatar/{width}/{height}`	非正方形畫布，適合寬幅橫幅或限時動態頭像。
`/api/avatar/seed/{seed}/{width}`	由任意種子字串推導出的確定性頭像。
`/api/avatar/id/{id}/{width}`	由數字 ID 推導出的確定性頭像，例如資料庫記錄。

確定性種子

種子會被雜湊為 48 色調色盤中的一種顏色，因此同一個種子永遠回傳同一張頭像，不需資料庫，也不落地儲存。可使用使用者名稱、信箱或記錄 ID。含空格或符號的種子需要百分號編碼，/api/avatar/id/ 則是數字 ID 的簡寫。

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

查詢參數

所有參數都是選用的，可以任意組合。遇到無法辨識的值會回傳 400 並附上 JSON 說明，而不是一張壞圖。

參數	可接受的值	預設值	回傳內容
`shape`	circle \| rounded \| square	circle	頭像外觀。預設為圓形，因為多數平台都會這樣裁切頭像。
`pattern`	solid \| grid \| dots \| diagonal \| checker	solid	疊加在背景上的紋理，方便一眼區分不同類型的預設圖。
`bg`	#1E3A5F	seed	背景顏色。會覆蓋種子原本對應的顏色。
`fg`	#1E3A5F	auto	首字母、紋理線和剪影的顏色；省略時自動挑選以確保對比度。
`initials`	1-2	-	最多兩個字母、數字或符號，置中繪製。填入全名會自動縮寫為首字母。
`figure`	1-15	-	剪影 id(1-15)或名稱，用 fg 的顏色畫在 bg 上。優先於首字母；單獨寫 ?figure 可清除。
`outline`	0 \| 1	0
`grayscale`	0 \| 1	0	移除所有顏色，適合灰階、停用等介面狀態。
`blur`	0-10	0	高斯模糊半徑。模糊限制在圖形內部，邊緣依然清晰。
`random`	?random=*	-	任意值。用於回傳與固定結果不同的頭像。

十六進位顏色可加可不加 # 前綴，#abc 這樣的三位簡寫會自動展開。不填 bg 時背景來自種子；不填 fg 時墨色會自動挑選以確保可讀性。模糊值超過上限時會自動收斂到上限而不是報錯；首字母不會超過兩個。

剪影

與生成器相同的 15 個半身剪影，可依 id 或名稱取用。fg 控制剪影顏色、bg 控制背景顏色，同一個 id 換配色就是另一種效果。

Solid fill

Hollow outline (outline=1)

親自試一下

選取頁面上的任一頭像，然後在下方調整參數。預覽與程式碼會同步更新，複製到的就是端點實際回傳的內容。

預覽

形狀紋理首字母

背景自動

前景自動

模糊 0 Outline 灰階

URL

回傳格式

圖片以 SVG 回傳，一般頭像通常只有 200 到 1000 位元組，在任何像素密度下都清晰。同一網址加上 .json 可改為讀取解析後的顏色，方便讓介面配色與頭像一致。

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

無效請求會回傳 400 與 JSON 內容：

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

快取與限制

帶種子的網址是其本身的純函式，因此會帶上一年期不可變快取標頭與 ETag。在應用程式前放一層 CDN，第一個請求之後圖片就不再消耗流量。寬高可取 16 到 2048 像素；超過上限會被收斂而非報錯，解析後的尺寸會在 JSON 中回傳。若希望每次請求都不同，可在網址後加 ?random= 加任意值。

常見問題

需要 API 金鑰或帳號嗎？

不需要。沒有註冊、沒有金鑰，也沒有呼叫配額。本頁的每個網址都可以直接使用。

同一個網址會一直回傳同一張頭像嗎？

會。帶種子的網址是其本身的純函式，可以放心寫死在程式、資料庫或測試裡。不帶種子的網址在同一網址下也維持穩定，?random= 則是明確關閉此行為的方式。

可以外連這些圖片並商用嗎？

可以。圖片由我們自己的伺服器依向量圖形產生，不涉及第三方照片、沒有版權疑慮，也不需要標示來源。可以直接外連，也可以下載使用。

為什麼用 SVG？尺寸限制是多少？

SVG 頭像通常只有幾百位元組，可任意縮放，還能用 CSS 重新著色。寬高可取 16 到 2048 像素，超過 2048 會被收斂。