Τεκμηρίωση

Αυτή είναι η product-facing reference για το public API. Το ίδιο identity, tenant, style version, avatar family, style options, size και WebP output προορίζονται να παραμένουν stable μέσα σε major release.

Core Endpoints

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

Operational Endpoints

Το GET /healthz είναι public για load balancers και uptime checks. Το GET /metrics είναι loopback-only και επιστρέφει 404 σε non-local peers.

Namespace Support

Χρησιμοποιήστε tenant και style_version για να κρατάτε χωριστούς χώρους οπτικής ταυτότητας μεταξύ προϊόντων ή rollout phases.

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

Ανώνυμα IDs

Στείλτε internal stable id ή one-way application hash αντί για raw personal data.

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

Rate Limits

Το public service εφαρμόζει origin-side rate limits, με αυστηρότερα limits σε /v1/avatar/link, direct avatar requests με persist=true και /og.png, επειδή object storage writes και Open Graph image rendering είναι ακριβότερα από direct rendering.

Timeouts

Avatar generation και storage operations περιορίζονται από server-side timeouts ώστε ακριβά requests να μην μονοπωλούν το origin επ' αόριστον.

Σφάλματα

400: invalid kind, unsupported algorithm ή format, size ή missing identity
408: generation ή storage timeout
429: rate limit exceeded
500: rendering ή storage failure

OpenAPI

Για generated clients ή tooling, χρησιμοποιήστε /docs/openapi.json.