Dokumentacija

Ovo je product-facing reference za public API. Isti identity, tenant, style version, avatar family, style options, size i WebP output trebaju ostati stable tokom 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 je public za load balancers i uptime checks. GET /metrics je loopback-only i vraća 404 za non-local peers.

Namespace Support

Koristi tenant i style_version da razdvojiš visual identity spaces između products ili 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

Anonymous IDs

Pošalji internal stable id ili one-way application hash umjesto raw personal data.

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

Rate Limits

Public service primjenjuje origin-side rate limits, sa strožijim limits za /v1/avatar/link, direct avatar requests sa persist=true i /og.png jer su object storage writes i Open Graph image rendering skuplji od direct rendering.

Timeouts

Avatar generation i storage operations su bounded server-side timeouts da expensive requests ne mogu neograničeno držati origin.

Errors

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

OpenAPI

Za generated clients ili tooling, koristi /docs/openapi.json.