Documentazione

Questo è il riferimento orientato al prodotto per l'API pubblica. La stessa identità, tenant, versione stile, famiglia avatar, opzioni stile, dimensione e output WebP sono pensati per rimanere stabili entro una major version.

Endpoint principali

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

Endpoint operativi

GET /healthz è pubblico per load balancer e controlli uptime. GET /metrics è limitato al loopback e restituisce 404 ai peer non locali.

Supporto namespace

Usa tenant e style_version per mantenere separati gli spazi di identità visiva tra prodotti o fasi di 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

ID anonimi

Invia un id interno stabile o un hash applicativo unidirezionale invece di dati personali grezzi.

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

Rate limit

Il servizio pubblico applica rate limit lato origin, con limiti più stretti su /v1/avatar/link, richieste avatar dirette con persist=true e /og.png perché le scritture su object storage e il rendering Open Graph sono più costosi del rendering diretto.

Timeout

La generazione avatar e le operazioni di storage sono limitate da timeout server-side, così le richieste costose non possono monopolizzare l'origin indefinitamente.

Errori

400: kind non valido, algoritmo o formato non supportato, dimensione o identità mancante
408: timeout di generazione o storage
429: rate limit superato
500: errore di rendering o storage

OpenAPI

Per client generati o strumenti, usa /docs/openapi.json.