افزونه و اپ‌ها

API برای برنامه‌نویس‌ها

با یک کلید API از برنامه، سایت یا اسکریپت خودت تصویر آپلود کن، لینک بگیر و فایل‌ها، آلبوم‌ها و سطل بازیافت را مدیریت کن. نشانی پایه، احراز هویت، نمونه‌کد و خطاها.

۳ دقیقه خواندن به‌روز شده ۲۹ مهر ۱۴۰۵
در این آموزش
  1. نشانی پایه و احراز هویت
  2. اولین درخواست: حسابم چه دارد؟
  3. آپلود یک تصویر
  4. مسیرهای اصلی
  5. خطاها

اگر برنامه‌نویسی، می‌توانی میوشات را مستقیم در کد خودت به کار ببری: فرم آپلود سایتت، ربات پیام‌رسان، اسکریپت پشتیبان‌گیری یا هر چیز دیگری. این آموزش خلاصه‌ای برای شروع است؛ راهنمای کامل همه‌ی مسیرها، با کلاس آماده‌ی PHP و آزمایش زنده‌ی کلید، در بخش «توسعه‌دهندگان» منوی سایت است.

نشانی پایه و احراز هویت

همه‌ی درخواست‌ها به این نشانی می‌روند:

https://mewshot.com/api/v1

کلید را (از «برنامه‌ها ← ساخت کلید») در هدر بفرست:

Authorization: Bearer msk_…

اگر سرورت هدر Authorization را نمی‌رساند، هدر X-API-Key: msk_… هم پذیرفته می‌شود. کلید هیچ‌وقت در نشانی (query string) پذیرفته نمی‌شود.

اولین درخواست: حسابم چه دارد؟

curl https://mewshot.com/api/v1/me \
  -H "Authorization: Bearer msk_YOUR_KEY"

پاسخ، نام پلن و تاریخ پایانش، فضای استفاده‌شده و آزاد و محدودیت‌های پلن (حداکثر حجم هر فایل، فرمت‌های مجاز، آلبوم، سطل بازیافت و ویرایشگر) را می‌دهد.

آپلود یک تصویر

curl https://mewshot.com/api/v1/images \
  -H "Authorization: Bearer msk_YOUR_KEY" \
  -F "file=@screenshot.png" \
  -F "title=صفحه‌ی ورود"

پاسخ موفق کد ۲۰۱ دارد:

{
  "ok": true,
  "data": {
    "id": "aB3dE9",
    "title": "صفحه‌ی ورود",
    "view_url": "https://mewshot.com/v/aB3dE9",
    "download_url": "https://mewshot.com/d/aB3dE9",
    "format": "png",
    "size": 184320,
    "width": 1440,
    "height": 900,
    "views": 0,
    "downloads": 0
  }
}

view_url همان «لینک صفحه» است و download_url «لینک دانلود». با فیلد album (کد آلبوم) فایل همان لحظه به آلبوم هم اضافه می‌شود.

همین کار با PHP

$ch = curl_init('https://mewshot.com/api/v1/images');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('SITE_API_KEY')],
    CURLOPT_POSTFIELDS => ['file' => new CURLFile('screenshot.png')],
    CURLOPT_RETURNTRANSFER => true,
]);
$res = json_decode(curl_exec($ch), true);
echo $res['ok'] ? $res['data']['view_url'] : $res['error']['message'];

مسیرهای اصلی

روش و مسیرکار
GET /meحساب، پلن، فضا و محدودیت‌ها
POST /imagesآپلود (فیلد file)
GET /imagesفهرست فایل‌ها (page، per_page تا ۱۰۰، جست‌وجو با q)
GET /images/{id}یک فایل
POST /images/{id}/renameتغییر نام (فیلد title)
DELETE /images/{id}حذف؛ اگر پلن سطل بازیافت دارد به سطل می‌رود
POST /images/{id}/replaceجایگزینی فایل با همان لینک (پلن‌های دارای ویرایشگر)
GET /trash و POST /trash/{id}/restoreسطل بازیافت و برگرداندن
GET /albums و POST /albumsفهرست و ساختن آلبوم

برای هر مسیری که با DELETE یا PATCH است، نسخه‌ی POST هم هست (مثل POST /images/{id}/delete) برای محیط‌هایی که این روش‌ها را نمی‌فرستند.

خطاها

هر خطا این شکل را دارد:

{ "ok": false, "error": { "code": "quota_exceeded", "message": "…" } }
کدیعنی
missing_key / invalid_keyکلید فرستاده نشده یا درست نیست
key_pausedکلید از سقف پلن بیرون است؛ کلیدی را حذف کن یا پلن را ارتقا بده
quota_exceededفضای حساب کافی نیست
plan_featureاین امکان در پلن صاحب کلید نیست
rate_limitedدرخواست‌ها زیاد است؛ کمی صبر کن (هدر Retry-After می‌گوید چقدر)

هر کلید در دقیقه تعداد محدودی درخواست دارد؛ عددش در بخش «توسعه‌دهندگان» نوشته شده.

مطمئنی؟