API 참조

문서

공개 API의 제품용 참조입니다. 동일한 identity, tenant, style version, avatar family, style options, size, WebP output은 major version 내에서 안정적으로 유지되도록 설계되었습니다.

핵심 endpoint

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

GET /healthz는 로드 밸런서와 uptime 확인을 위해 공개됩니다. GET /metrics는 loopback 전용이며 로컬이 아닌 peer에는 404를 반환합니다.

Namespace 지원

tenant와 style_version을 사용해 제품 또는 rollout 단계 사이의 시각적 identity 공간을 분리하세요.

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

원시 개인정보 대신 안정적인 내부 ID 또는 애플리케이션 단방향 해시를 보내세요.

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

속도 제한

공개 서비스는 origin 측 속도 제한을 적용하며, 객체 스토리지 쓰기와 Open Graph 렌더링이 직접 렌더링보다 비싸기 때문에 /v1/avatar/link, persist=true가 있는 직접 아바타 요청, /og.png에는 더 엄격한 제한이 적용됩니다.

타임아웃

비싼 요청이 origin을 무기한 점유하지 않도록 아바타 생성과 스토리지 작업은 서버 측 타임아웃으로 제한됩니다.

오류

400: 잘못된 kind, 지원되지 않는 알고리즘 또는 형식, 크기, 또는 누락된 식별자
408: 생성 또는 스토리지 타임아웃
429: 속도 제한 초과
500: 렌더링 또는 스토리지 실패

OpenAPI

생성된 클라이언트나 도구에는 다음을 사용하세요 /docs/openapi.json.