مستندات

آواتار

آواتارها

آدرس آواتار، پارامترها، تصویر پیش‌فرض، کش و رفتار CORS.

درخواست آواتار

GET https://avatarak.ir/avatar/{hash}

کلید API لازم نیست. {hash} همان هش SHA-256 ایمیل است (۶۴ نویسه‌ی هگز).

<img src="https://avatarak.ir/avatar/84059b07d4be67b806386c0aad8070a23f18836bbaae342275dc0a83414c32ee?s=200"
     width="100" height="100" alt="عکس پروفایل">

پارامترها

پارامتر پیش‌فرض توضیح
s (یا size) 80 اندازه‌ی مربع به پیکسل، از 16 تا 512. مقدار خارج از این بازه به نزدیک‌ترین حد برگردانده می‌شود. برای تصویر شفاف روی صفحه‌های پرتراکم، حدود ۲ برابر اندازه‌ی نمایش را بخواهید.
d (یا default) mp وقتی آواتار عمومی وجود ندارد چه برگردد: mp یک سیلوئت خنثی (SVG)، identicon یک الگوی ساخته‌شده (SVG)، blank یک PNG شفاف ۱×۱، 404 پاسخ خالی 404. هر مقدار دیگر مثل mp رفتار می‌کند. آدرس (URL) پذیرفته نمی‌شود.

پاسخ

  • یک تصویر مربع که از وسط برش خورده. JPEG، یا WebP وقتی هدر Accept شما شامل image/webp باشد.
  • تصویر پیش‌فرض به‌صورت image/svg+xml (mp و identicon)، image/png (blank) یا 404 برمی‌گردد.

آیدنتیکن (identicon)

d=identicon یک الگوی متقارن ۵×۵ از روی خودِ هش می‌کشد، پس هر آدرس تصویر مخصوص و قابل‌تشخیص خودش را دارد. این تصویر فقط به هش بستگی دارد: آدرس ناشناس، تأییدنشده، خصوصی و آدرسی که فقط عکس ندارد همه یک‌اندازه تصادفی دیده می‌شوند، پس نمی‌شود با آن فهمید آدرسی حساب دارد یا نه.

هدر مقدار
Cache-Control public, max-age=3600 برای عکس، public, max-age=300 برای پیش‌فرض
ETag موجود است؛ با If-None-Match پاسخ 304 Not Modified می‌گیرید
Vary Accept
Access-Control-Allow-Origin * (از هر صفحه‌ای قابل‌استفاده است، حتی داخل <canvas>)
Cross-Origin-Resource-Policy cross-origin

آدرس عکس با آپلود عکس جدید عوض نمی‌شود؛ مرورگر یا CDN وقتی کش تمام شود (حداکثر یک ساعت) نسخه‌ی تازه را می‌گیرد.

چه وقت عکس برمی‌گردد؟

فقط وقتی همه‌ی این‌ها برقرار باشد: ایمیل توسط صاحبش تأیید شده باشد، عمومی باشد، کلید نمایش عکس روشن باشد و عکسی تنظیم شده باشد. در غیر این‌صورت تصویر پیش‌فرض می‌گیرید، و برای ایمیل ناشناخته، تأییدنشده و خصوصی دقیقاً یکسان است. این عمدی است؛ حریم خصوصی و محدودیت‌ها را ببینید.

آواتار خود پروفایل

صفحه‌های عمومی پروفایل به‌جای ایمیل از آدرسی بر پایه‌ی نام کاربری استفاده می‌کنند:

GET https://avatarak.ir/{username}/avatar

همان پارامترهای s و d را می‌پذیرد و هرگاه پروفایل عمومی و نمایش عکس روشن باشد، عکس را برمی‌گرداند. ایمیلی در کار نیست، پس تأیید ایمیل لازم نیست. وقتی عکسی نباشد، این آدرس حروف اول نام را روی رنگی که از نام کاربری انتخاب می‌شود برمی‌گرداند (d=initials، پیش‌فرض همین‌جا)؛ d=mp، identicon، blank و 404 هم کار می‌کنند. حروف اول فقط روی همین آدرس هست و هرگز روی /avatar/{hash} نیست، چون نشان دادن نام برای یک هش لو می‌دهد که آن ایمیل حساب دارد.

مثال‌ها

const url = `https://avatarak.ir/avatar/${hash}?s=96&d=404`;
const res = await fetch(url);
const hasAvatar = res.ok;   // 404 means "no public avatar": show your own placeholder
<?php
$url = 'https://avatarak.ir/avatar/' . hash('sha256', strtolower(trim($email))) . '?s=96';
echo '<img src="' . htmlspecialchars($url) . '" width="48" height="48" alt="">';
.user-avatar {
  background: url('https://avatarak.ir/avatar/HASH?s=128') center / cover;
  border-radius: 50%;
}

محدودیت

درخواست‌های آواتار به ۶۰۰ در دقیقه برای هر آدرس IP محدودند. مرورگرها و CDNها پاسخ را کش می‌کنند، پس صفحه‌های معمولی خیلی پایین‌تر می‌مانند؛ اگر کاربران زیادی را از یک آدرس سرویس می‌دهید، جلوی آن یک CDN بگذارید. حریم خصوصی و محدودیت‌ها را ببینید.