プレースホルダーアバター API

開発にも本番にも使える、キー不要の無料プレースホルダーアバター。img タグに URL を指定するだけで、数百バイトのきれいな決定的な SVG が返ります。登録もインストールも不要です。

https://blankpfp.com/api/avatar

ライブサンプル

以下の画像はすべて、このページで介绍的エンドポイントがリアルタイムで配信しています。

クイックスタート

URL をそのまま img タグに入れてください。サイズはピクセル単位で、既定の形状は円なので追加のスタイルは不要です。

<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 ではユーザーを識別する値から URL を組み立てます:

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

URL の形式

4 つの形式すべてで高さは省略できます。末尾に .json を付けると、画像の代わりに以下で説明するメタデータが返ります。

URL	取得できるもの
`/api/avatar/{width}`	正方形のアバター。同じ URL は常に同じ画像を返します。
`/api/avatar/{width}/{height}`	正方形以外のキャンバス。ワイドなバナーやストーリーのアバターに向きます。
`/api/avatar/seed/{seed}/{width}`	任意のシード文字列から決定されるアバター。
`/api/avatar/id/{id}/{width}`	数値 ID（データベースの行など）から決定されるアバター。

決定的なシード

シードは 48 色のパレットから 1 色にハッシュされるため、同じシードは常に同じアバターを返します。データベースもディスク保存も不要です。ユーザー名、メールアドレス、レコード 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">

クエリパラメーター

すべてのパラメーターは任意で、組み合わせ可能です。認識されない値を渡すと、壊れた画像の代わりに JSON 付きの 400 が返ります。

パラメーター	指定できる値	既定値	取得できるもの
`shape`	circle \| rounded \| square	circle	アバターの外形。ほとんどのサービスがプロフィール画像を丸く切り抜くため、既定は円になっています。
`pattern`	solid \| grid \| dots \| diagonal \| checker	solid	背景の上に重ねるテクスチャ。種類ごとのプレースホルダーを一目で区別できます。
`bg`	#1E3A5F	seed	背景色。シードが選ぶ色より優先されます。
`fg`	#1E3A5F	auto	イニシャル、テクスチャ線、剪影の色。省略時はコントラストを満たすように自動選択されます。
`initials`	1-2	-	最大 2 文字の英数字または記号を中央に描画します。フルネームを渡すとイニシャルに短縮されます。
`figure`	1-15	-	剪影の id(1〜15)または名前。fg の色で bg の上に描画します。イニシャルより優先され、?figure 単体で消去できます。
`outline`	0 \| 1	0
`grayscale`	0 \| 1	0	すべての色を除去します。減光や無効状態の UI に便利です。
`blur`	0-10	0	ガウスぼかしの半径。ぼかしは図形の内側に留まるため、輪郭はシャープなままです。
`random`	?random=*	-	任意の値。固定ではなく、値ごとに異なるアバターを返します。

16 進色は先頭の # を省略して書いてもよく、#abc のような 3 桁表記も展開されます。bg を省略すると背景はシードから、fg を省略すると可読性を保つため文字色は自動選択されます。ぼかしの値が上限を超える場合はエラーではなく上限に丸められ、イニシャルは常に 2 文字までになります。

剪影

生成器と同じ 15 種類の半身剪影で、id でも名前でも指定できます。fg が剪影の色、bg が背景の色なので、同じ id でも配色を変えれば印象が変わります。

Solid fill

Hollow outline (outline=1)

試してみる

このページの任意の頭像を選び、下のパラメータを調整してください。プレビューとコードが同時に更新され、コピーしたものがそのままエンドポイントから返される内容になります。

プレビュー

形状テクスチャイニシャル

背景自動

前景自動

ぼかし 0 Outline グレースケール

URL

レスポンス形式

画像は SVG で返るため、通常のアバターは 200〜1000 バイトに収まり、どのピクセル密度でも鮮明です。同じ URL に .json を付けると解決済みの色を読み取れるので、UI の配色をアバターに合わせられます。

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

キャッシュと制限

シード付き URL はアドレスの純粋関数なので、1 年の不変キャッシュヘッダーと ETag 付きで配信されます。アプリの前段に CDN を置けば、初回リクエスト以降は画像のコストがゼロになります。幅と高さは 16〜2048 ピクセルまでで、それより大きい値は拒否せず上限に丸められ、解決後のサイズは JSON に含まれます。要求ごとに違う画像を出したい場合は、?random= に任意の値を付けます。

よくある質問

API キーやアカウントは必要ですか?

不要です。登録もキーもクォータもありません。このページの URL はすべて、サイトが稼働している限りそのまま使えます。

同じ URL はいつも同じアバターを返しますか?

はい。シード付き URL はアドレスの純粋関数なので、マークアップ、データベース、テストにハードコードしても安全です。シードなしの URL もアドレスごとに安定しており、?random= がその挙動を明示的に解除する手段です。

これらの画像を外部リンクして商用利用できますか?

できます。画像はベクター図形から自社サーバーで生成しているため、第三者の写真は含まれ、ライセンス上の懸念はなく、出典を記載する必要もありません。直接外部リンクするか、ダウンロードしてお使いください。

なぜ SVG ですか。サイズの上限は?

SVG のアバターは通常数百バイトで、どの画面密度にも拡大でき、CSS で色も変えられます。幅と高さは 16〜2048 ピクセルまでで、それを超える場合は 2048 に丸められます。