Dokumentation

Dies ist die produktorientierte Referenz für die öffentliche API. Dieselbe Identität, derselbe Tenant, dieselbe Stilversion, Avatar-Familie, Stiloptionen, Größe und WebP-Ausgabe sollen innerhalb einer Major-Version stabil bleiben.

Kern-Endpunkte

GET /v1/avatar: returns an avatar asset directly
GET /v1/avatar/link: stores the generated avatar in configured object storage and returns signed-link metadata
GET /avatar/<kind>/<identity>/webp: path-style public avatar URL
GET /docs/openapi.json: machine-readable API description

Betriebs-Endpunkte

GET /healthz ist öffentlich für Load Balancer und Uptime-Prüfungen. GET /metrics ist nur über Loopback erreichbar und gibt 404 für nicht-lokale Peers zurück.

Namespace-Unterstützung

Nutze tenant und style_version, um visuelle Identitätsräume zwischen Produkten oder Rollout-Phasen zu trennen.

GET https://hashavatar.app/v1/[email protected]&tenant=acme&style_version=v2&algorithm=sha512&kind=wizard&background=white&accessory=hat&color=deep-sea-blue&expression=cool&shape=squircle&format=webp&size=256

Anonyme IDs

Sende eine stabile interne ID oder einen Einweg-Anwendungs-Hash statt roher personenbezogener Daten.

printf '%s' '[email protected]' | sha256sum | cut -d' ' -f1

Rate Limits

Der öffentliche Dienst wendet origin-seitige Rate Limits an, mit strengeren Limits für /v1/avatar/link, direkte Avatar-Anfragen mit persist=true und /og.png, weil Objekt-Speicher-Schreibvorgänge und Open-Graph-Rendering teurer sind als direktes Rendering.

Timeouts

Avatar-Erzeugung und Speicheroperationen sind durch serverseitige Timeouts begrenzt, sodass teure Anfragen den Origin nicht unbegrenzt blockieren können.

Fehler

400: ungültiger kind-Wert, nicht unterstützter Algorithmus oder Format, ungültige Größe oder fehlende Identität
408: Timeout bei Erzeugung oder Speicherung
429: Rate Limit überschritten
500: Rendering- oder Speicherfehler

OpenAPI

Für generierte Clients oder Werkzeuge verwende /docs/openapi.json.