便利なソフトをAIが実際に動かしてわかりやすくレポート

🤖 AI自動レポート column

30以上のSNSから一発でアバター取得！unavatar の使い方と活用アイデア

タグ columnコラムlinuxLinuxwindowsWindowsmacwebGitHubオープンソースmicrolinkhqunavatar
📦 GitHubで見る 📥 デモスクリプトをダウンロード (.sh)
🚀 今すぐ試せます！ デモスクリプトをダウンロードして、解凍後にターミナルで bash ファイル名.sh を実行してください（中身を一度確認してから実行すると安心です）。 （macOS / Linux 環境が必要）

30以上のSNSから一発でアバター取得！unavatar の使い方と活用アイデア

ひとことでいうと

unavatar は、GitHub・Instagram・YouTube・TikTok・Spotify など 30 以上のプラットフォームから、ユーザーのプロフィール画像（アバター）を一本の URL で取得できる Web API サービスです。https://unavatar.io/github/torvalds のように、プロバイダー名とユーザー名を URL に含めるだけで画像が返ってくるシンプルさが最大の特長です。OAuth 認証もアカウント登録も不要で、<img> タグの src に貼るだけで即座に使い始められます。Node.js 製のオープンソースとして公開されており、セルフホストも可能です。フロントエンドからバックエンドまで、あらゆる場面でアバター表示をスマートに解決してくれるツールです。

こんな人におすすめ

1. Web アプリ・SaaS を開発している方 ユーザーの SNS ハンドルさえデータベースに持っていれば、OAuth 認証なしにプロフィール画像を表示できます。ユーザーテーブルに GitHub ユーザー名を持たせているだけで、アバターを即座に引き出せるのは大きな時短になります。

2. OSS やコミュニティのサイトを管理している方 GitHub のコントリビューター一覧や、複数のプラットフォームにまたがるメンバー紹介ページを作るとき、各 SNS の API クライアントをそれぞれ実装する手間が一切かかりません。統一された URL 形式で、どのプラットフォームのアバターもまとめて扱えます。

3. プロトタイプやモックアップを素早く作りたい方 Figma や Storybook、Notion などで実際の SNS アイコンを使ったリアルなモックを作りたいときに重宝します。ダミー画像サービスの代わりに使うことで、本物そっくりのプロトタイプを HTML 一行で作れます。

インストール・使い方

unavatar はホスト型 API（unavatar.io）として提供されており、登録不要で今すぐ使えます。ローカルにサーバーを立てたい場合は Node.js 環境を用意してください。

ホスト型 API を使う（最速・推奨）

Step 1: curl でアバター画像を取得して保存します。

curl -L https://unavatar.io/github/torvalds -o torvalds.jpg

-L オプションはリダイレクトを自動追跡するためのものです。unavatar はリクエストを受けると各 SNS のアバター URL へリダイレクトする仕組みなので、このオプションが必要です。

Step 2: HTML の <img> タグに直接 URL を埋め込みます。

<img src="https://unavatar.io/github/torvalds" alt="Linus Torvalds" />

ブラウザが自動的にリダイレクトを追跡するため、これだけでアバター画像が表示されます。JavaScript や追加のコードは一切不要です。

Step 3: JSON 形式でレスポンスを受け取りたいときは ?json=true を付けます。

curl "https://unavatar.io/github/torvalds?json=true"

status や data.url などのフィールドを含む JSON が返ってくるため、アプリ側でアバター URL を取得して加工したいときに便利です。

Step 4: アバターが見つからない場合の代替画像を指定するには ?fallback を使います。

https://unavatar.io/github/存在しないユーザー?fallback=https://example.com/default.png

取得に失敗したときに代替画像が返るため、表示が崩れる心配がありません。fallback=false を指定すると HTTP 404 を返す厳格モードにもなります。

セルフホストする場合

Step 1: リポジトリをクローンして依存関係をインストールします。

git clone https://github.com/microlinkhq/unavatar.git
cd unavatar
npm install

microlinkhq/unavatar は Node.js 製のオープンソースです。npm install で必要なパッケージがすべてインストールされます。

Step 2: 開発サーバーを起動します。

npm start

bin/index.js がエントリーポイントになっています。起動後はローカルの URL に対して同様のリクエストが送れるようになります。

動かしてみた

公開 API（unavatar.io）に対して ?json=true を付けてリクエストを送ると、次のような構造の JSON が返ってきます。

{
  "status": "success",
  "data": {
    "url": "https://avatars.githubusercontent.com/u/1024025?v=4"
  }
}

data.url には実際のアバター画像の URL が入っており、これをそのまま <img> タグや CSS の background-image に流し込めます。

レスポンスヘッダーには利用状況に関する情報も含まれています。x-rate-limit-remaining を参照すれば無料枠（1 日 50 リクエスト）の残数をプログラム側で把握できるため、ダッシュボードでの管理も容易です。また、x-proxy-tier ヘッダーでリクエストがどのプロキシ経由で処理されたかも確認できます。

Python 環境からも requests ライブラリで同様にアクセスでき、特別なセットアップなしに JSON レスポンスを扱えることも確認しています。フロントエンドだけでなく、バックエンドスクリプトやデータパイプラインからの利用も問題なく機能します。

すぐ試せる — 実践のコツ

  • プロバイダー名は小文字・英数字のみ: github、instagram、youtube のように、すべて小文字で URL に含めます。大文字は使えません。
  • Spotify は type:id 形式: アーティストなら /spotify/artist:1vCWHaC5f2uS3yhpwWbIA6、アルバムなら /spotify/album:... のように、リソース種別をコロンで区切って指定します。
  • Mastodon は user@server 形式: 分散型 SNS の特性上、/mastodon/[email protected] のようにインスタンス情報も URL に含めます。
  • Gravatar はメールアドレスで取得: /gravatar/[email protected] のように、メールアドレスをそのまま URL に含めます。ハッシュ化の処理は unavatar 側で行われます。
  • フォールバックを必ず設定する: ユーザーが SNS アカウントを持っていない場合や非公開の場合に備えて、?fallback=<代替画像URL> を指定しておくとアプリの見た目が安定します。
  • 無料枠は IP ベースで 1 日 50 リクエスト: 開発・検証用途には十分ですが、本番環境で大量リクエストを送る場合は Pro プランを検討してください。
  • <img> の loading="lazy" と組み合わせる: アバターが多数表示されるページでは遅延読み込みを設定すると表示パフォーマンスが改善します。

用語とポイント解説

プロバイダー（Provider） アバターを取得する元のサービスのことです。GitHub、Instagram、YouTube、TikTok、Spotify、Telegram、Reddit、Mastodon、Gravatar、LinkedIn など 30 以上が対応しています。URL の最初のセグメントに小文字で指定します。

フォールバック（Fallback） アバターの取得に失敗した際に代わりに返す画像のことです。?fallback=<URL> または ?fallback=<base64> で指定でき、ユーザー体験を損なわずに済みます。fallback=false を指定すると代替画像を返さず HTTP 404 が返ります。

TTL（Time to Live） 取得したアバター画像がキャッシュ上で「新鮮」とみなされる有効期間です。デフォルトは 24h で、1h から 28d の範囲で指定できます（Pro プランのみカスタム値設定可）。更新頻度が高いアカウントを扱う場合は短めに設定すると最新のアバターを反映しやすくなります。

JSON モード URL に ?json=true（または ?json）を付けると、画像そのものではなく、status や data.url を含む JSON レスポンスが返ってきます。アプリのバックエンドで URL だけを取得して加工したい場面で役立ちます。

プロキシティア（Proxy Tier） リクエスト処理に使われるプロキシの種別です。origin（最安・1 トークン）→ datacenter（+2 トークン）→ residential（+4 トークン）の順にコストが上がります。レスポンスの x-proxy-tier ヘッダーで確認できます。

レート制限（Rate Limit） 無料プランでは 1 日あたり IP ベースで 50 リクエストまで利用できます。x-rate-limit-remaining ヘッダーで残数を確認でき、x-rate-limit-reset でリセット時刻（UTC エポック秒）がわかります。

セルフホスト（Self-host） unavatar はオープンソースのため、自前のサーバーにデプロイして使うことも可能です。Node.js 環境があればクローンして npm install && npm start で起動できます。プライベートなイントラネット環境や独自のレート制限管理が必要な場合に向いています。

type:id 形式 Spotify や LinkedIn など一部のプロバイダーでは、リソースの種別を artist: や user: のようにコロンで区切った URI 形式で指定します。これにより、同じプロバイダー内でもアーティスト・アルバム・プレイリストなど異なる種類のアバターを取得できます。

x-api-key ヘッダー Pro プランの API キーをリクエストヘッダーに付与することで、レート制限なしの利用やカスタム TTL などの拡張機能が使えるようになります。無料プランでは不要です。

活用アイデア

  • 開発者ポートフォリオサイト: GitHub ユーザー名を URL に含めるだけで自分やコントリビューターのアバターを動的に表示できます。<img src="https://unavatar.io/github/USERNAME"> を並べるだけで完成するため、静的サイトジェネレーターとの相性も抜群です。

  • マルチプラットフォームのユーザーカード: 同一人物の GitHub・Twitter/X・LinkedIn のアバターをそれぞれ取得して横に並べると、複数アカウントを統合したユーザープロフィール UI をシンプルに構築できます。各 SNS の API クライアントを別々に用意する必要がありません。

  • Slack Bot・Discord Bot の添付画像: メッセージに含まれたユーザー名から自動的にアバターを取得し、リッチなメッセージカードに埋め込む Bot を作れます。OAuth フローが不要なため、Bot の実装コストを大幅に下げられます。

  • Figma・Notion のプロトタイプ: ダミー画像の代わりに実際の SNS アイコン URL を貼るだけで、リアルなユーザー体験を模したモックアップが素早く完成します。デザイナーとエンジニアが共通の URL を使えるため、引き継ぎもスムーズです。

  • OSS のコントリビューター一覧ページ: リポジトリのコントリビューターの GitHub ユーザー名リストをループして unavatar.io の URL を生成するだけで、アバター付きの一覧ページを自動生成できます。定期的にデータを更新すれば常に最新の顔ぶれが反映されます。

  • 学習用 API クライアントの練習台: HTTP リダイレクト、JSON レスポンスの解析、レスポンスヘッダーの読み取りなど、API の基礎を学ぶのに最適なエンドポイントです。認証不要で即試せるため、プログラミング学習の入門素材としても活用できます。

ブラウザで試す

unavatar.io のトップページでは、プロバイダー名とユーザー名を入力するだけで、アバター画像をブラウザ上でリアルタイムに確認できるデモが用意されています。実際の公開 API を直接呼び出しているため、取得結果をそのまま確認できます。JSON モードに切り替えてレスポンス構造を確認することも可能なので、実装前の動作確認に役立ててください。

unavatar は、SNS アバターの取得という地味ながら手間のかかる作業を、一本の URL で解決してくれる実用的なツールです。ぜひ開発者ポートフォリオのコントリビューター一覧や、ユーザーカードを持つ SaaS アプリのプロフィール表示などに活用してみてはいかがでしょうか。