Appearance

HTTP API ​

The Suils HTTP API is the simplest way to generate avatars: build a URL, request it, get an image. No authentication, no SDK, no version prefix.

https://avatars.suils.es/<style>/<format>?seed=<seed>&size=<px>&backgroundColor=<hex>
  • <style> — a style slug (lowercase) from the catalog, e.g. suils, kawaii, unicorn.
  • <format> — svg (default), png, jpg, webp, avif, or json.

Deterministic by seed ​

Pass any string as seed. The same style + seed always returns the same avatar, on every request — perfect as a default profile picture keyed on a user ID.

https://avatars.suils.es/unicorn/svg?seed=user-8f3a2c
https://avatars.suils.es/unicorn/svg?seed=user-8f3a2c
Avatar preview

Omit seed and you get the style's default avatar. URL‑encode seeds that contain spaces or special characters.

https://avatars.suils.es/cat/svg?seed=Milo
Avatar preview
https://avatars.suils.es/robot/svg?seed=Ada
Avatar preview

Options ​

The API accepts three query parameters:

OptionApplies toDescription
seedallAny string. Determines which parts are composed.
sizeallOutput size in pixels. The public instance caps at 1024; raise it via MAX_SIZE when self‑hosting.
backgroundColorallHex color without the #, e.g. b6e3f4. Omit for the style's own background.
https://avatars.suils.es/kawaii/png?seed=Jane&size=256&backgroundColor=b6e3f4
https://avatars.suils.es/kawaii/png?seed=Jane&size=256&backgroundColor=b6e3f4
Avatar preview

TIP

Connect several options with &, as usual for query strings.

Formats ​

SVG

Recommended

Default. Scales to any size, tiny, no size cap.

PNG

Rasterized on demand. Transparent background by default.

JPG

Rasterized on demand. White background (no transparency).

WebP

Rasterized on demand. Smaller than PNG.

AVIF

Rasterized on demand. Smallest raster format.

JSON

Returns the SVG plus the resolved traits as JSON.

https://avatars.suils.es/zeus/svg?seed=Sky
Avatar preview
https://avatars.suils.es/zeus/png?seed=Sky
Avatar preview
https://avatars.suils.es/zeus/webp?seed=Sky
Avatar preview

JSON ​

The json format returns the SVG together with the resolved traits (the parts chosen for that seed) — handy for building your own tooling:

https://avatars.suils.es/unicorn/json?seed=Robot
json
{
  "style": "unicorn",
  "seed": "Robot",
  "options": { "…": "the parts chosen for this seed" },
  "svg": "<svg …>…</svg>"
}

Listing styles ​

Request /styles to get every style the instance serves, sorted alphabetically:

https://avatars.suils.es/styles
json
{ "styles": ["alchemist", "alien", "android", "…"] }

CORS & caching ​

  • CORS — every response sends Access-Control-Allow-Origin: *, so you can request avatars from any origin (including fetch).
  • Caching — image and JSON responses are sent with Cache-Control: public, max-age=86400. Since avatars are deterministic, they're safe to cache aggressively on your own CDN too.
  • Unknown style — returns 404 with a JSON body listing the valid styles.

Fair use ​

The public instance at avatars.suils.es is free to use. Please be reasonable with request volume. For guaranteed availability, higher limits, or commercial scale, host your own instance — it's one docker compose command.