Dokumentation

Detta är den produktnära referensen för det offentliga API:t. Samma identitet, tenant, stilversion, avatarfamilj, stilalternativ, storlek och WebP-utdata är avsedda att vara stabila inom en major-version.

Kärn-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

Drift-endpoints

GET /healthz är offentlig för lastbalanserare och tillgänglighetskontroller. GET /metrics är endast tillgänglig via loopback och returnerar 404 för icke-lokala peers.

Namespace-stöd

Använd tenant och style_version för att hålla visuella identitetsutrymmen separata mellan produkter eller utrullningsfaser.

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

Anonyma ID:n

Skicka ett stabilt internt id eller en envägs-applikationshash i stället för råa personuppgifter.

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

Hastighetsgränser

Den offentliga tjänsten använder origin-baserade hastighetsgränser, med striktare gränser för /v1/avatar/link, direkta avatarförfrågningar med persist=true och /og.png eftersom objektlagringsskrivningar och Open Graph-rendering är dyrare än direkt rendering.

Timeouts

Avatar-generering och lagringsoperationer begränsas av serverbaserade timeouts så att dyra förfrågningar inte kan monopolisera origin-servern obegränsat.

Fel

400: ogiltigt kind-värde, algoritm eller format som inte stöds, storlek eller saknad identitet
408: timeout vid generering eller lagring
429: hastighetsgränsen överskreds
500: renderings- eller lagringsfel

OpenAPI

För genererade klienter eller verktyg, använd /docs/openapi.json.