A name. A URL.
An avatar.

Quick start

Put a URL-encoded name after the domain. Bimoji returns a square SVG with initials, a deterministic background, and readable text.

https://bimoji.bitech.id/John%20Doe

John DoeSame name and settings, same avatar.

No signup, API key, or SDK. Use the URL directly inside an image tag.

<img src="https://bimoji.bitech.id/John%20Doe" alt="John Doe" />

Parameters

Optional query parameters customize your avatar. Omitted values use these defaults.

Hex values are case-insensitive. Use bg=0E77AE or encode the hash as bg=%230E77AE. A literal # starts a URL fragment and is not sent to the server.

Automatic foreground chooses white or dark text for at least 4.5:1 contrast. An explicit color override uses your chosen color. Numeric radius is clamped at half the avatar size, which makes a circle.

https://bimoji.bitech.id/John%20Doe?bg=0E77AE&color=FFFFFF&radius=16

Names & initials

Names are normalized to Unicode NFC, trimmed, and repeated whitespace is collapsed. Letter case does not change avatar identity or the default colors.

• One word uses its first grapheme: John → J.
• Two initials use the first and last meaningful words: John Michael Doe → JD.
• Three initials use the first, second, and last words: John Michael Andrew Doe → JMD.
• Hyphens and punctuation separate words: john-doe → JD.
• uppercase=false produces lowercase initials. It does not preserve input casing.

Unicode letters and numbers are supported. Combining marks stay with their base character. Emoji-only input uses its first grapheme. If there are fewer words than requested initials, Bimoji uses the available words.

Keep names to 80 Unicode code points after whitespace normalization. Encode paths with encodeURIComponent(name). For reserved names or names containing slashes, use the alternate endpoint:

https://bimoji.bitech.id/api/avatar?name=docs

Reserved paths include api, docs, health, about, framework paths, and metadata assets such as robots.txt and sitemap.xml.

Font presets

Choose a controlled system font stack. SVGs have no external font requests; appearance may vary with fonts installed on the viewing device.

sans

rounded

serif

mono

sans

Arial, Helvetica, sans-serif

rounded

Arial Rounded MT Bold, Arial, Helvetica, sans-serif

serif

Georgia, Times New Roman, serif

mono

Courier New, Courier, monospace

Arbitrary font families and font URLs are not accepted.

Usage examples

<img
  src="https://bimoji.bitech.id/Ayu%20Prameswari?bg=0E77AE&color=FFFFFF"
  alt="Ayu Prameswari"
  width="48"
  height="48"
/>

function UserAvatar({ name }: { name: string }) {
  return (
    <img
      src={`https://bimoji.bitech.id/api/avatar?name=${encodeURIComponent(name)}`}
      alt={name}
      width={48}
      height={48}
    />
  );
}

.team-avatar {
  width: 48px;
  height: 48px;
  background-image: url("https://bimoji.bitech.id/PT%20Bitech");
  background-size: cover;
}

Use image alt text for meaningful avatars. A CSS background is decorative; give the surrounding element an accessible label if the image carries information.

const response = await fetch(
  "https://bimoji.bitech.id/John%20Doe?font=mono"
);
if (!response.ok) throw new Error("Avatar request failed");
const svg = await response.text();

Caching

Successful responses are public and immutable for one year. Their ETag identifies the complete effective configuration. Clients may send If-None-Match to receive a bodyless 304 when unchanged.

Content-Type: image/svg+xml; charset=utf-8
Cache-Control: public, max-age=31536000, immutable
ETag: "<canonical-avatar-key>"
X-Bimoji-Version: v1
X-Content-Type-Options: nosniff

Query order and equivalent defaults share one stored variant. Different effective colors, fonts, or other settings have distinct identities. CDN caches must retain the full query string; never configure them to ignore avatar parameters.

V1 rendering remains stable. Incompatible future algorithms will be versioned deliberately. System font availability can affect how the same SVG looks across devices.

Errors & limits

Invalid input returns 400 with a short JSON error and Cache-Control: no-store. Unknown or repeated parameters are rejected. Boolean values must be exactly true or false.

{ "error": "Size must be an integer from 16 to 1024." }

URLs are limited to 2,048 characters. Empty names, invalid hex colors, unsupported control characters, unknown fonts, and out-of-range values are rejected safely. Reserved path names return 404; the alternate endpoint supports them. Unsupported HTTP methods return 405.

GET and HEAD are supported. SVG responses allow cross-origin fetching as well as ordinary image embedding.

Privacy & availability

Names are public URL input. When PostgreSQL is configured, Bimoji stores the name, normalized settings, SVG, timestamps, and aggregate origin request count. Avoid putting sensitive information in an avatar URL.

The application does not store IP addresses, user-agent strings, tracking cookies, or fingerprints. CDN and hosting infrastructure may maintain their own request logs. A local theme preference is stored only in your browser.

If database access fails, avatars continue to render deterministically in memory. Health checks report application availability without requiring the database:

{ "status": "ok", "service": "bimoji", "version": "v1" }