Dokumentacja

To produktowa referencja public API. Ten sam identity, tenant, style version, avatar family, style options, size i WebP output mają pozostać stabilne w ramach major release.

Główne Endpointy

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

Endpointy Operacyjne

GET /healthz jest publiczne dla load balancers i uptime checks. GET /metrics jest tylko loopback i zwraca 404 dla non-local peers.

Obsługa Namespace

Użyj tenant i style_version, aby oddzielić przestrzenie wizualnej tożsamości między produktami albo etapami rollout.

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

Anonimowe ID

Wysyłaj wewnętrzny stabilny id albo jednokierunkowy application hash zamiast surowych danych osobowych.

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

Rate Limity

Public service stosuje origin-side rate limits; ostrzejsze limity dotyczą /v1/avatar/link, direct avatar requests z persist=true oraz /og.png, ponieważ object storage writes i Open Graph image rendering są droższe niż direct rendering.

Timeouts

Avatar generation i storage operations są ograniczone server-side timeouts, aby kosztowne żądania nie mogły bez końca zajmować origin.

Błędy

400: nieprawidłowy kind, nieobsługiwany algorithm albo format, size lub brak identity
408: generation albo storage timeout
429: przekroczono rate limit
500: rendering albo storage failure

OpenAPI

Dla generated clients albo tooling użyj /docs/openapi.json.