# AvatarMelayu — Dokumentasi API

AvatarMelayu ialah perkhidmatan avatar placeholder percuma berwajah Melayu dan Malaysia yang dijana AI. Developer dan pereka menampal satu URL, contohnya https://avatarmelayu.com/i/150?img=3, ke dalam tag img untuk mendapatkan gambar profil contoh, tanpa daftar dan tanpa API key.

## Asas

```
https://avatarmelayu.com/i
https://avatarmelayu.com/i/300
```

Saiz dalam piksel, 16 hingga 1000, sentiasa segi empat sama. Lalai 150.

## Parameter

| Parameter | Nilai | Kesan |
|---|---|---|
| `img` | `1`, `2`, … | Avatar tertentu ikut ID awamnya (lihat galeri). |
| `u` | sebarang teks | Teks yang sama sentiasa memberi avatar yang sama. |
| `g` | `lelaki`, `perempuan`, `gabungan` | Tapis ikut jantina. |
| `cat` | `bertudung` (Bertudung), `bersongkok` (Bersongkok), `profesional` (Profesional), `pelajar` (Pelajar), `kanak-kanak` (Kanak-kanak), `warga-emas` (Warga Emas), `baju-melayu` (Baju melayu) | Tapis ikut kategori. |
| `fmt` | `jpg`, `webp`, `png` | Format imej. Lalai: WebP untuk pelayar yang menyokongnya, JPG untuk yang lain. |
| `shape` | `circle` | Avatar bulat dengan latar lutsinar (PNG atau WebP). |

Jika tiada avatar sepadan dengan penapis, avatar rawak dipulangkan supaya reka bentuk anda tidak rosak.

## Avatar konsisten

```
https://avatarmelayu.com/i/64?u=aina@contoh.my
```

## Avatar inisial

```
https://avatarmelayu.com/i/initials/Ali%20Bakar?size=150&bg=2563eb&color=ffffff&shape=circle
```

## Contoh kod

```html
<img src="https://avatarmelayu.com/i/150?img=3" width="150" height="150" alt="Avatar">
```

```jsx
const Avatar = ({ user }) => (
  <img src={`https://avatarmelayu.com/i/64?u=${encodeURIComponent(user.email)}`} alt={user.name} />
);
```

## API JSON

```
GET https://avatarmelayu.com/api/avatars?g=lelaki&per_page=10
GET https://avatarmelayu.com/api/avatars/3
```

Spesifikasi OpenAPI: https://avatarmelayu.com/openapi.json

## Had & cache

- 120 permintaan seminit per IP; HTTP 429 jika melebihi.
- URL dengan img atau u di-cache selama sehari dan disemak semula dengan ETag, jadi gambar yang dikemas kini muncul dalam masa sehari. URL rawak tidak di-cache supaya setiap tag img mendapat wajah berbeza. Nombor ID tidak pernah diguna semula.

## Lesen & etika

Semua avatar dijana AI dan tidak menggambarkan individu sebenar. Avatar dilesenkan CC0 untuk kegunaan sebagai placeholder dalam mockup, prototaip dan demo. Jangan gunakannya untuk menyamar sebagai seseorang atau dalam konteks yang mengelirukan. Jika sesuatu avatar mirip orang sebenar, ia boleh dilaporkan untuk dibuang.

_Dikemas kini: 2026-10-30_