DOCSEARCHbyAlgolia
Submit Docs

unavatar

repository·master·Indexed 23 days ago

https://github.com/microlinkhq/unavatar

A service and library for retrieving unified user avatars from over 72 platforms, including GitHub, X/Twitter, and Instagram. It provides a unified URL structure, a Node.js library (@unavatar/core), a CLI, and a self-hosted HTTP server option. Features include support for email and domain resolution, customizable TTL, fallback images, and multiple authentication methods via secret and publishable keys.

Tokens
8.4K
Snippets
24
Records
48
Agent score
80%

What's inside unavatar

  1. Unavatar Usage Guides Overview

    master

    Unavatar provides three primary ways to integrate its avatar fetching capabilities into your projects:

    1. Library usage: For direct integration into your application code (Node.js or browser).
    2. Server usage: For setting up a dedicated server to handle avatar requests.
    3. CLI usage: For interacting with unavatar via the command line interface.

    Refer to the specific guides for detailed implementation instructions.

  2. Understand Unavatar pricing and billing

    master

    Unavatar uses a tiered pricing model based on authentication and the proxy tier required to resolve an avatar.

    Usage Tiers

    • Anonymous (no API key): 25 free requests per day per IP.
    • Authenticated origin requests (x-api-key): 50 free origin requests per day, followed by metered monthly billing.
    • Proxy requests (datacenter, residential): Always metered; no free quota.

    Proxy Tier Costs

    Every request has a cost in tokens ($0.010 per token) based on the proxy tier used:

    • Origin: 1 token ($0.010)
    • Datacenter: +2 tokens ($0.030 total)
    • Residential: +4 tokens ($0.050 total)

    To upgrade to the PRO plan (which includes the 50 free daily origin requests and custom TTL), visit unavatar.io/checkout.

    $curl -I -H "x-api-key: sk_YOUR_SECRET_KEY" "https://unavatar.io/instagram/kikobeats"

x-pricing-tier:pro
x-proxy-tier:origin
x-unavatar-cost:1

  3. How Unavatar caching works

    master

    Unavatar caches avatar lookups to improve speed and stability.

    • First request: Fetches from upstream and stores in cache (counts as a usage/cost).
    • Subsequent requests: Served from cache until the ttl expires (free and no usage consumed).
    • TTL Expiration: The next request after expiration refreshes the cache and is billed/rate-limited according to the request tier.

    Inspecting Cache Status

    You can verify cache behavior using these response headers:

    • x-cache-status: HIT (served from cache) or MISS (fetched/refreshed from upstream).
    • cache-control: Shows the cache policy and effective TTL (e.g., public, max-age=3600).

  4. Get domain logos and favicons

    master

    You can retrieve logos and favicons from any hostname using the domain provider or specific search engine providers.

    • Domain Provider: Uses a fallback chain (DuckDuckGo, Google, then Microlink) to find an image for a hostname. Route: unavatar.io/domain/{hostname}.
    • DuckDuckGo: Specifically uses DuckDuckGo's icon service. Route: unavatar.io/duckduckgo/{domain}.
    • Google: Specifically uses Google's favicon service. Route: unavatar.io/google/{domain}.
    unavatar.io/domain/microlink.io
unavatar.io/duckduckgo/microsoft.com
unavatar.io/google/stremio.com

  5. Handle response errors programmatically

    master

    Unavatar uses HTTP status codes and stable error codes to categorize failures. You should use the code field for programmatic logic and the message field for user-facing feedback.

    • Client-side issues: Return status: "fail" (HTTP 4xx).
    • Service-side issues: Return status: "error" (HTTP 5xx).
    • Unknown failures: Return EINTERNAL (HTTP 500).

    Common error codes include:

    • EAPIKEY: Invalid API key via header or ?token query param.
    • EPKDOMAIN: Request origin not in publishable key's allowed domains.
    • ENOTFOUND: Route not found.
    • ERATE: Anonymous daily rate limit exceeded.
    • EINTERNAL: Unexpected internal server failure.
    | HTTP | Code                 | Typical trigger                                         |
| ---- | -------------------- | ------------------------------------------------------- |
| 400  | `ESESSIONID`         | Missing `session_id` in `/checkout/success`             |
| 400  | `ESESSION`           | Checkout session not paid or not found                  |
| 400  | `ESIGNATURE`         | Missing `stripe-signature` header                       |
| 400  | `EWEBHOOK`           | Invalid/failed Stripe webhook processing                |
| 400  | `EAPIKEYVALUE`       | Missing `apiKey` query parameter                        |
| 400  | `EAPIKEYLABEL`       | Missing `label` query parameter                          |
| 400  | `EAUTOROUTE`         | `/:key` used with a username instead of email/domain    |
| 400  | `EPKREMOVE`          | Attempted to remove a publishable key directly          |
| 400  | `EPKUPDATE`          | Attempted to update a publishable key directly          |
| 400  | `EPKINVALID`         | Publishable key does not start with `pk_`               |
| 401  | `EEMAIL`             | Invalid or missing authenticated email                  |
| 401  | `EUSERUNAUTHORIZED`  | Missing/invalid auth for protected routes               |
| 401  | `EAPIKEY`            | Invalid API key via header or `?token` query param      |
| 403  | `ETTL`               | Custom `ttl` requested without pro plan                 |
| 403  | `EPRO`               | Provider restricted to pro plan                        |
| 403  | `EPKNOTALLOWED`      | Publishable key used on a secret-key-only endpoint      |
| 403  | `EPKDOMAIN`         | Request origin not in publishable key's allowed domains |
| 404  | `ENOTFOUND`          | Route not found                                         |
| 404  | `EAPIKEYNOTFOUND`    | API key not found                                       |
| 409  | `EAPIKEYEXISTS`      | Custom API key already exists                           |
| 409  | `EAPIKEYLABELEXISTS` | API key label already exists                            |
| 409  | `EAPIKEYMIN`         | Attempt to remove last remaining key                    |
| 429  | `ERATE`              | Anonymous daily rate limit exceeded                     |
| 500  | `ECHECKOUT`          | Stripe checkout session creation failed                 |
| 500  | `EAPIKEYFAILED`      | API key retrieval after checkout failed                 |
| 500  | `EINTERNAL`          | Unexpected internal server failure                      |

  6. Use the unavatar CLI binaries

    master

    The unavatar package provides two binaries to connect to an unavatar server and display avatars directly in your terminal:

    • unavatar: Connects to the production server at https://unavatar.io.
    • unavatar-dev: Connects to a local server running at http://[::]:3000.

  7. Add attribution for free plans

    master

    Free plans require visible attribution on any page or surface displaying unavatar.io avatars.

    Requirements for valid attribution:

    • The link must point directly to https://unavatar.io/ (no redirects, shorteners, or tracking wrappers).
    • The link must be crawlable (present in rendered HTML, not blocked by robots.txt, authentication, or region gating).
    • Do not use rel="nofollow" or rel="noindex".
    • target="_blank" is allowed.

    Web Placements: Add the link in the site footer, about page, credits page, or any page rendering avatars.

    Mobile/Non-Web Placements: Add the attribution link to your app's marketing site, app store listing description, or credits screen.

  9. Resolve avatars from email addresses

    master

    Unavatar can resolve user avatars from an email address using a provider chain (Gravatar, then GitHub). You can use automatic resolution or target a specific provider.

    Automatic Resolution

    Pass the email address as the only path segment or prefix it with email/. The API will automatically attempt to find the avatar via Gravatar and GitHub.

    • Route: unavatar.io/email/{email} or unavatar.io/{email}

    Explicit Providers

    If you know which service holds the avatar, you can call the provider directly:

    • Gravatar: unavatar.io/gravatar/{email-or-hash}. Note that emails are normalized and hashed with SHA-256. To avoid exposing plain-text emails in logs, pass a pre-computed MD5 or SHA-256 hash.
    • GitHub: unavatar.io/github/{email}. Resolves via public profile email or commit history.
    // Automatic
unavatar.io/email/hello@microlink.io
unavatar.io/hello@microlink.io

// Explicit
unavatar.io/gravatar/hello@microlink.io
unavatar.io/github/sindresorhus@gmail.com

  10. Basic usage of @unavatar/core

    master

    Use @unavatar/core as a Node.js library to resolve avatars programmatically. You can resolve avatars using explicit input types like email or domain, or by targeting specific providers like GitHub.

    To use it, require the package and invoke the returned function. Note that the library is initialized by calling the required module as a function.

    const unavatar = require('@unavatar/core')()

// Resolve with explicit input type
const result = await unavatar.email('hello@microlink.io')

// Domain resolution
const domainResult = await unavatar.domain('reddit.com')

// Specific provider
const githubResult = await unavatar.github('kikobeats')

  11. Quick start with unavatar.io

    master

    unavatar.io retrieves avatars from over 72 platforms using a single URL structure. You can look up avatars by email, username, or domain. The endpoint structure determines the lookup method.

    Common lookup patterns:

    • Email: unavatar.io/email/{email}
    • Username: unavatar.io/{provider}/{username} (e.g., unavatar.io/github/kikobeats)
    • Domain: unavatar.io/domain/{domain} (e.g., unavatar.io/domain/reddit.com)

    No API keys or SDKs are required to start using the service.

    https://unavatar.io/github/kikobeats

  12. Configure Domain Restrictions for Publishable Keys

    master

    To prevent unauthorized use of your publishable keys, you can configure domain restrictions in the unavatar dashboard. When enabled, requests are only accepted if the Origin or Referer header matches the allowed domains.

    Supported formats:

    • example.com: Exact domain match.
    • *.example.com: All subdomains of example.com.
    • app.example.com: A specific subdomain.