API برای برنامهنویسها
با یک کلید API از برنامه، سایت یا اسکریپت خودت تصویر آپلود کن، لینک بگیر و فایلها، آلبومها و سطل بازیافت را مدیریت کن. نشانی پایه، احراز هویت، نمونهکد و خطاها.
در این آموزش
اگر برنامهنویسی، میتوانی میوشات را مستقیم در کد خودت به کار ببری: فرم آپلود سایتت، ربات پیامرسان، اسکریپت پشتیبانگیری یا هر چیز دیگری. این آموزش خلاصهای برای شروع است؛ راهنمای کامل همهی مسیرها، با کلاس آمادهی 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 میگوید چقدر) |
هر کلید در دقیقه تعداد محدودی درخواست دارد؛ عددش در بخش «توسعهدهندگان» نوشته شده.