AgentSkillsCN

unavatar-api

通过 unavatar.io 从 20 多个平台（如 GitHub、X/Twitter、Instagram、Gravatar 等）获取用户头像。当用户提到 unavatar、头像获取、个人资料图片、用户头像，或需要根据邮箱、用户名、域名或电话号码解析头像时，可使用此功能。

SKILL.md
--- frontmatter
name: unavatar-api
description: Retrieve user avatars from 20+ platforms (GitHub, X/Twitter, Instagram, Gravatar, etc.) via unavatar.io. Use when the user mentions unavatar, avatar retrieval, profile pictures, user avatars, or needs to resolve avatars by email, username, domain, or phone number.

unavatar API

unavatar.io resolves user avatars from 20+ platforms via a single endpoint. Supports lookup by email, username, domain, or phone number.

Endpoint

https://unavatar.io

Quick Start

Resolve avatars by input type:

InputPatternExample
email/provider/user@example.comhttps://unavatar.io/gravatar/user@example.com
username/provider/usernamehttps://unavatar.io/github/kikobeats
domain/domain.comhttps://unavatar.io/microlink.io
phone/provider/phonenumberhttps://unavatar.io/whatsapp/34688638289

Without a provider prefix, unavatar auto-resolves using all matching providers and returns the fastest successful result.

Authentication

  • •Free: No auth required, 50 requests/day per IP
  • •Pro: Pass x-api-key header, usage-based billing at $0.001/token
bash
curl -H "x-api-key: YOUR_API_KEY" https://unavatar.io/instagram/kikobeats

Proxy Tiers & Token Cost

Proxy tierTokensCost
Origin1$0.001
Datacenter+2$0.003
Residential+4$0.007

Response headers: x-proxy-tier, x-unavatar-cost, x-pricing-tier.

Key Management

  • •Usage: curl -H "x-api-key: KEY" https://unavatar.io/key/usage
  • •Rotate: curl -H "x-api-key: KEY" https://unavatar.io/key/rotate

Query Parameters

ttl

  • •Type: number | string
  • •Default: '24h'
  • •Range: '1h' to '28d'

Cache duration for the resolved avatar. The avatar is considered fresh until TTL expiration, then recomputed on next request.

e.g., https://unavatar.io/kikobeats?ttl=1h

fallback

  • •Type: string | boolean

Custom fallback image when avatar can't be resolved. Accepts:

  • •URL to external avatar service (boringavatars.com, avatar.vercel.sh)
  • •URL to static image
  • •Base64 encoded image (e.g., transparent 1x1 pixel GIF)
  • •false to disable fallback (returns 404 instead)
code
https://unavatar.io/github/37t?fallback=https://avatar.vercel.sh/37t?size=400
https://unavatar.io/github/37t?fallback=false
https://unavatar.io/github/37t?fallback=data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==

json

  • •Type: boolean

Returns JSON payload instead of image content.

e.g., https://unavatar.io/kikobeats?json

Rate Limiting

Response headers:

  • •x-rate-limit-limit: Max requests per window
  • •x-rate-limit-remaining: Remaining requests
  • •x-rate-limit-reset: Reset time (UTC epoch seconds)

HTTP 429 when limit exceeded.

Providers

Providers are grouped by input type. When no specific provider is given, all matching providers race and the fastest successful result wins.

Provideremailusernamedomainphone
Bluesky✓
DeviantArt✓
Dribbble✓
DuckDuckGo✓
GitHub✓
GitLab✓
Google✓
Gravatar✓
Instagram✓
Microlink✓
OnlyFans✓
Reddit✓
SoundCloud✓
Spotify✓
Substack✓
Telegram✓
TikTok✓
Twitch✓
Vimeo✓
WhatsApp✓
X/Twitter✓
YouTube✓

URI Format Providers

Spotify supports type:id format (default type: user):

  • •user: /spotify/kikobeats
  • •artist: /spotify/artist:6sFIWsNpZYqbRiDnNOkZCA
  • •playlist: /spotify/playlist:37i9dQZF1DXcBWIGoYBM5M
  • •album: /spotify/album:4aawyAB9vmqN3uQ7FjRGTy
  • •show: /spotify/show:6UCtBYL29hRg064d4i5W2i
  • •episode: /spotify/episode:512ojhOuo1ktJprKbVcKyQ
  • •track: /spotify/track:11dFghVXANMlKmJXsNCbNl

WhatsApp supports type:id format (default type: phone):

  • •phone: /whatsapp/34612345678
  • •channel: /whatsapp/channel:0029VaABC1234abcDEF56789
  • •chat: /whatsapp/chat:ABC1234DEFghi
  • •group: /whatsapp/group:ABC1234DEFghi

For individual provider examples, see providers.md.