Tài liệu

Đây là tài liệu tham chiếu hướng sản phẩm cho API công khai. Cùng định danh, tenant, phiên bản kiểu, họ avatar, tùy chọn kiểu, kích thước và đầu ra WebP được thiết kế ổn định trong cùng một major version.

Endpoint chính

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 vận hành

GET /healthz công khai cho load balancer và kiểm tra uptime. GET /metrics chỉ dành cho loopback và trả 404 cho peer không cục bộ.

Hỗ trợ namespace

Dùng tenant và style_version để tách không gian định danh trực quan giữa sản phẩm hoặc giai đoạn 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 ẩn danh

Gửi id nội bộ ổn định hoặc hash một chiều của ứng dụng thay vì dữ liệu cá nhân thô.

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

Giới hạn tốc độ

Dịch vụ công khai áp dụng giới hạn tốc độ phía origin, với giới hạn chặt hơn cho /v1/avatar/link, request avatar trực tiếp có persist=true và /og.png vì ghi object storage và render Open Graph tốn kém hơn render trực tiếp.

Timeout

Tạo avatar và thao tác lưu trữ bị giới hạn bởi timeout phía máy chủ để request tốn kém không thể chiếm origin vô hạn.

Lỗi

400: kind không hợp lệ, thuật toán hoặc định dạng không được hỗ trợ, kích thước hoặc thiếu định danh
408: timeout khi tạo hoặc lưu trữ
429: vượt giới hạn tốc độ
500: lỗi render hoặc lưu trữ

OpenAPI

Cho client được sinh hoặc công cụ, dùng /docs/openapi.json.