占位头像 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 会被收敛。