Skill for unavatar-api

# 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:

| Input    | Pattern                      | Example                                         |
| -------- | ---------------------------- | ----------------------------------------------- |
| email    | `/provider/[email protected]` | `https://unavatar.io/gravatar/[email protected]` |
| username | `/provider/username`         | `https://unavatar.io/github/kikobeats`          |
| domain   | `/domain.com`                | `https://unavatar.io/microlink.io`              |
| phone    | `/provider/phonenumber`      | `https://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 tier  | Tokens |  Cost  |
| ----------- | :----: | :----: |
| Origin      |   1    | $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)

```
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.

| Provider   | email | username | domain | phone |
| ---------- | :---: | :------: | :----: | :---: |
| 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](providers.md).