مستندات API
با API سایت YourImageShare میتوانید فایلها را با کد آپلود کنید، فهرستشان را بگیرید و حذفشان کنید. این یک API ساده از نوع JSON/REST است؛ نیازی به SDK نیست و فقط یک کلاینت HTTP و یک کلید API کافی است. کتابخانههای رسمی JavaScript، Python و MCP هم در دسترساند.
همه کتابخانههای کلاینت و ابزارهای زیر متنباز هستند. میتوانید کد را ببینید، مشکلات را گزارش کنید یا در مخزن رسمی GitHub ما مشارکت کنید: github.com/yourimageshare/yourimageshare.
آدرس پایه: https://yourimageshare.com/api · قالب: ورودی و خروجی JSON، بهجز آپلودها که multipart/form-data هستند · احراز هویت: یک کلید API در هر درخواست. · مشخصات قابل خواندن برای ماشین: /openapi.json (OpenAPI 3.1)، برای عاملها و ابزارهای تولید کد که ترجیح میدهند این صفحه را تجزیه نکنند.
دریافت کلید API
وارد شوید، به حساب من بروید و تب API را باز کنید. کلید شما همانجا نمایش داده میشود، همراه با دکمه Regenerate. با ساخت دوباره کلید، کلید قبلی بلافاصله از کار میافتد؛ پس پیش از کلیک، آن را در همه جاهایی که استفاده میکنید بهروز کنید.
در همین تب یک کلید دوم و مستقل هم هست: کلید فقطآپلود. برای اینکه کِی باید آن را بهجای کلید اصلی استفاده کنید، به نکته زیر و بخش افزونههای انجمن نگاه کنید.
احراز هویت
کلید را در هدر بفرستید (روش پیشنهادی، چون رشته کوئری معمولاً در لاگ دسترسی، لاگ پروکسی و هدر Referer ثبت میشود):
X-API-Key: YOUR_API_KEY پارامتر کوئری ?key= هم کار میکند؛ این روش برای سازگاری با یکپارچهسازیهای قدیمی و دستورهای سریع curl نگه داشته شده است. اگر هر دو باشند، هدر اولویت دارد.
?key=YOUR_API_KEY نکته: با کلید خود مثل رمز عبور رفتار کنید؛ هر کسی که آن را داشته باشد میتواند در حساب شما آپلود کند، فهرست بگیرد، ویرایش کند و حذف کند. هر درخواست موفق ثبت میشود و بهصورت نمودار، به تفکیک روز و نوع درخواست، در تب API صفحه حساب شما دیده میشود. اگر کلید باید جایی باشد که دیگران ببینند، مثلاً افزونه انجمن یا فایل پیکربندی عمومی، بهجای آن از کلید فقطآپلود همان تب استفاده کنید: این کلید فقط آپلود میکند و فهرستگرفتن، دریافت اطلاعات، ویرایش و حذف آپلودها با آن خطای 401 میدهد.
اندپوینتها
آپلود، فهرست و حذف از یک احراز هویت و یک محدودیت درخواست مشترک استفاده میکنند؛ فایلهای حجیم را میتوان ابتدا تکهتکه فرستاد.
POST /api - آپلود فایل
یک فایل را برای حساب احراز هویتشده آپلود میکند.
| فیلد | نوع | الزامی | توضیح |
|---|---|---|---|
uploads | file | یکی از این سه مورد | فایلی که باید آپلود شود، تا 100MB (حد یک درخواست از طریق شبکه ما). در هر درخواست یک فایل؛ این اندپوینت آپلود گروهی چند فایل را پشتیبانی نمیکند. |
url | string | لینک عمومی http(s) یک عکس یا فیلم. ما خودمان آن را دانلود میکنیم، پس فایلها تا 200MB قابل قبولاند. | |
upload_id | string | فایلی که پیشتر تکهتکه با POST /api/chunk فرستادهاید، تا 200MB. | |
filename | string | خیر | همراه با upload_id: نام اصلی فایل. |
expires_in | integer | خیر | حذف خودکار این آپلود پس از این تعداد ثانیه (از 60 تا 31,536,000، یعنی 1 دقیقه تا 1 سال). برای آپلود معمولی و دائمی آن را نفرستید. |
allow_duplicate | boolean | خیر | حتی اگر حساب شما همین فایل را قبلاً آپلود کرده باشد، یک نسخه جدید ذخیره شود (پایینتر duplicate را ببینید). |
keep_original | boolean | خیر | عکس دقیقاً همانطور که آپلود شده نگه داشته شود. بدون آن، فایلهای JPG/PNG بزرگتر از 1 MB به WebP بهینه میشوند. متادیتا مثل GPS در هر دو حالت حذف میشود. |
visibility | string | خیر | unlisted (پیشفرض): فایل و صفحهاش برای هر کسی که لینک را داشته باشد کار میکند، ولی در هیچ جا فهرست نمیشود. private: فقط فایل؛ لینک صفحه همه بهجز شما را مستقیم به فایل میبرد (بدون نظر، واکنش و تبلیغ). public: در سایت فهرست میشود و قابل ایندکس است. |
title | string | خیر | حداکثر 90 نویسه، در صفحه آپلود نمایش داده میشود. |
description | string | خیر | حداکثر 500 نویسه. |
نوعهای پذیرفتهشده: عکسهای JPG, PNG, GIF, WEBP, AVIF, BMP, TIFF, HEIC یا HEIF؛ فیلمهای MP4, WEBM, AVI, MOV, MKV, MPEG, WMV, FLV یا 3GP (فهرست دقیق ممکن است با گذر زمان بیشتر شود). HEIC/HEIF و TIFF بهصورت WebP ذخیره میشوند، فیلمهایی غیر از MP4/WebM به MP4 تبدیل میشوند و عکسهای بزرگتر JPEG/PNG اندکی بعد از آپلود، اگر حجمشان بهطور محسوسی کمتر شود، به WebP تبدیل میشوند. حداکثر حجم: 200MB؛ فایلهای بزرگتر یا ناخوانا با خطای 422 رد میشوند.
پاسخ - 200 OK:
{
"type": "success",
"msg": "success",
"data": {
"id": "aB3xY9qRz1",
"type": "image",
"path": "https://i.yourimageshare.com/aB3xY9qRz1.png",
"src": "https://yourimageshare.com/ib/aB3xY9qRz1.png",
"direct": "https://yourimageshare.com/ib/aB3xY9qRz1",
"thumb": "https://i.yourimageshare.com/thumb-aB3xY9qRz1.webp",
"width": 1920,
"height": 1080,
"size": 482113,
"locked": false,
"visibility": "unlisted",
"title": null,
"description": null,
"expires_at": null,
"duplicate": false,
"delete_url": "https://yourimageshare.com/delete#iV3x...k9"
}
} | فیلد | توضیح |
|---|---|
id | شناسه یکتای فایل. |
type | image یا video. |
path | آدرس ذخیرهسازی فایل بههمان شکلی که آپلود شده است. ممکن است اندکی بعد، هنگام تبدیل فایل (WebP/MP4)، تغییر کند؛ پس بهجای path، مقدار src را ذخیره کنید. |
src | لینک مستقیم و دائمی فایل؛ همیشه فایل فعلی را باز میکند و برای src در <img>/<video> و برای ذخیرهکردن مناسب است. |
direct | صفحه فایل در YourImageShare (عنوان، توضیح، نظرها، گزینههای اشتراکگذاری). |
thumb | تصویر بندانگشتی WebP با عرض 280px (برای فیلم، اولین فریم) یا null. |
width, height | اندازه نمایشی به پیکسل (در حالت ایستاده؛ برای فیلم، اندازه فریم) یا null اگر معلوم نباشد. |
size | حجم فایل به بایت، بهصورتی که ذخیره شده است. |
locked | اگر آپلود رمزدار باشد true است. |
visibility | private، unlisted یا public (فیلد درخواست بالا را ببینید). |
title, description | همانطور که تنظیم شدهاند، یا null. متنها مثل وبسایت بررسی محتوایی میشوند. |
delete_url | فقط برای آپلودهای جدید: یک لینک خصوصی که این آپلود را بدون کلید API حذف میکند. فقط یک بار نمایش داده میشود (فقط هش آن ذخیره میشود)؛ اگر لازم دارید، نگهش دارید. |
expires_at | زمان حذف خودکار این آپلود با قالب ISO 8601، یا null اگر منقضی نمیشود. |
duplicate | اگر حساب شما قبلاً همین فایل را آپلود کرده باشد true است: همان آپلود برگردانده میشود و چیز جدیدی ذخیره نمیشود. برای آپلودهای دارای انقضا یا با allow_duplicate=1 اعمال نمیشود. |
آپلودهای دارای انقضا: وقتی expires_at فرا برسد، فایل از فضای ذخیرهسازی حذف میشود و صفحه آپلود حدود 5 دقیقه بعد 410 Gone برمیگرداند. این کار بعداً قابل بازگشت یا تمدید نیست؛ اگر خواستید زودتر حذفش کنید از اندپوینت DELETE استفاده کنید، و اگر خواستید بیشتر بماند، دوباره با expires_in جدید آپلود کنید.
POST /api/chunk - فایلهای حجیم
هر درخواست حداکثر 100MB میتواند داشته باشد. برای فایلهای بزرگتر (تا 200MB)، یا برای کوچک نگهداشتن هر درخواست در اینترنت کند، فایل را در تکههای حداکثر 5MB بفرستید و در پایان POST /api را بزنید:
- یک شناسه آپلود انتخاب کنید: 32 نویسه هگزادسیمال تصادفی.
- برای هر تکه،
POST /api/chunk(multipart/form-data) را همراه باupload_id،index(از 0)،total(تعداد تکهها) و بایتها درchunkبفرستید. پاسخ{"type": "success", "chunk_size": 5242880}است. POST /apiرا باupload_idوfilenameبهجایuploadsبزنید، بهعلاوه هر فیلد آپلود دیگر. پاسخ همان پاسخ معمولی آپلود است.
تکههای یک آپلود ناتمام بعد از 2 ساعت حذف میشوند. فقط POST /api پایانی در محدودیتهای آپلود حساب میشود.
GET /api/{id} و PATCH /api/{id} - یک آپلود
GET یکی از آپلودهای شما را با همان فیلدهای فهرست پایین برمیگرداند. PATCH مقدار visibility، title یا description آن را تغییر میدهد (فیلد فرم یا JSON؛ عنوان یا توضیح خالی آن را پاک میکند) و آپلود بهروزشده را برمیگرداند. هر دو به کلید کامل API نیاز دارند؛ اگر چنین آپلودی در حساب شما نباشد 404 میدهند.
curl -X PATCH https://yourimageshare.com/api/aB3xY9qRz1 \
-H "X-API-Key: YOUR_API_KEY" -d visibility=public -d title="Sunset" POST /api/{id}/replace - جایگزینی فایل
فایل پشت یکی از آپلودهای شما را عوض میکند و شناسه، صفحه و همه لینکها را حفظ میکند. هر نوع مجاز قابل قبول است، حتی نوعی متفاوت (یک عکس میتواند فیلم شود). فایل جدید را بهصورت uploads بفرستید (یا upload_id یک فایل تکهتکهشده با POST /api/chunk)؛ keep_original مثل آپلود کار میکند. فایل جدید همان بررسیها و تبدیلهای آپلود جدید را میگذراند و نسخه قبلی حذف میشود. به کلید کامل API نیاز دارد؛ اگر چنین آپلودی در حساب شما نباشد 404 و اگر رمزدار یا دارای محدودیت بازدید باشد 409 میدهد.
curl -X POST https://yourimageshare.com/api/aB3xY9qRz1/replace \
-H "X-API-Key: YOUR_API_KEY" -F uploads=@new-version.png GET /api - فهرست آپلودهای شما
فهرست صفحهبندیشده آپلودهای حساب احراز هویتشده (از هر منبعی: API، وبسایت یا ویرایشگر) را از جدید به قدیم و با 50 مورد در هر صفحه برمیگرداند.
| پارامتر | محل | الزامی | توضیح |
|---|---|---|---|
page | query | خیر | شماره صفحه، پیشفرض 1. |
پاسخ - 200 OK:
{
"type": "success",
"data": [
{
"id": "aB3xY9qRz1",
"type": "image",
"title": null,
"path": "https://i.yourimageshare.com/aB3xY9qRz1.webp",
"src": "https://yourimageshare.com/ib/aB3xY9qRz1.webp",
"direct": "https://yourimageshare.com/ib/aB3xY9qRz1",
"thumb": "https://i.yourimageshare.com/thumb-aB3xY9qRz1.webp",
"width": 1920,
"height": 1080,
"size": 482113,
"locked": false,
"visibility": "unlisted",
"description": null,
"expires_at": null,
"created_at": "2026-07-23T15:43:28+01:00"
}
],
"meta": { "current_page": 1, "last_page": 1, "total": 1 }
} معنی فیلدها اینجا همان معنیشان در پاسخ آپلود بالاست (برای آپلود رمزدار، path و thumb لینکهای امضاشده و کوتاهمدت هستند). برای دریافت یک آپلود با id آن از GET /api/{id} استفاده کنید.
DELETE /api/{id} - حذف یک آپلود
یکی از آپلودهای حساب احراز هویتشده را برای همیشه حذف میکند. این کار از طریق API قابل بازگشت نیست. {id} مقداری است که اندپوینتهای آپلود یا فهرست بهعنوان id برمیگردانند.
پاسخ - 200 OK:
{ "type": "success", "msg": "Deleted." } اگر آپلودی با این شناسه در حساب شما نباشد 404 برمیگردد (یا هرگز مال شما نبوده، یا قبلاً حذف شده است).
POST /api/compare - اسلایدر قبل/بعد
از دو عکس آپلودشده خودتان یک مقایسه قبل/بعد میسازد: صفحهای با اسلایدر در /c/{id} که در هر وبسایتی هم میتوان آن را جاسازی کرد. کلید فقطآپلود هم کار میکند. before و after (شناسه آپلودها، الزامی) و در صورت تمایل title، label_before و label_after (پیشفرض "Before" و "After") را بفرستید.
پاسخ - 201 Created:
{
"type": "success",
"id": "P7uAYy04VA",
"url": "https://yourimageshare.com/c/P7uAYy04VA",
"embed_url": "https://yourimageshare.com/embed/c/P7uAYy04VA",
"embed": { "script": "<blockquote class=\"YISEmbed\" ...", "iframe": "<iframe ..." }
} اگر هر یک از شناسهها جزو عکسهای آپلودشده شما نباشد 422 برمیگردد (فیلمها و عکسهای رمزدار قابل استفاده نیستند).
محدودیت درخواست
هر کلید API سهمیه مستقل در دقیقه و در روز دارد، بهعلاوه یک سقف روزانه کلیتر برای هر IP، تا جلوی استفاده از چند کلید پشتسرهم از یک IP گرفته شود. آپلودها، فهرستها و حذفها محدودیتهای مشترک دارند.
| بازه | محدودیت پیشفرض | دامنه |
|---|---|---|
| در دقیقه | 20 درخواست | برای هر کلید API |
| در روز | 500 درخواست | برای هر کلید کامل API |
| در روز | 2,000 درخواست | برای هر کلید فقطآپلود (افزونههایی که کل کتابخانه رسانه را منتقل میکنند) |
| در روز | 2,000 درخواست | برای هر آدرس IP |
| در ماه (UTC) | 3,000 آپلود | برای هر حساب، مجموع همه کلیدهای آن |
| در دقیقه | 300 تکه | برای هر کلید API، فقط POST /api/chunk |
سهمیه آپلود ماهانه. هر حساب میتواند ماهانه 3,000 فایل از طریق API آپلود کند؛ این شمارش روی همه کلیدها و ابزارهایی که از آنها استفاده میکنند (SDKها، افزونهها، افزونههای مرورگر، MCP با کلید) حساب میشود. فقط آپلودهای موفق شمرده میشوند: فهرستگرفتن، حذف و درخواستهای ناموفق شمرده نمیشوند و فایلی که تکهتکه ارسال شود یک بار حساب میشود. شمارش از اول هر ماه (UTC) دوباره شروع میشود. شمارش این ماه را در حساب من > API میبینید. بعد از رسیدن به سقف، POST /api مقدار 429 را همراه با تاریخ بازنشانی برمیگرداند. این سقف از ۰۱ ژانویه ۲۰۲۷ اعمال میشود.
این محدودیتها ممکن است تغییر کنند. هر پاسخ شامل هدرهای استاندارد محدودیت درخواست است:
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 14 با عبور از هر محدودیت، خطای 429 برمیگردد و هدر Retry-After میگوید چند ثانیه صبر کنید.
خطاها
همه پاسخهای خطا، صرفنظر از اندپوینت یا علت، قالب یکسانی دارند:
{ "type": "error", "errors": "A human-readable description of what went wrong." } | وضعیت | معنی |
|---|---|
| 401 | کلید API وجود ندارد یا نامعتبر است. |
| 403 | حساب یا IP فعلی شما از آپلود مسدود شده است. |
| 404 | آپلودی با این شناسه در این حساب پیدا نشد (دریافت، ویرایش، حذف). |
| 413 | درخواست بزرگتر از 100MB است. فایل را تکهتکه (POST /api/chunk) یا با لینک آن در url بفرستید (تا 200MB). |
| 422 | خطای اعتبارسنجی: فایل یا لینکی ارسال نشده، نوع فایل پشتیبانی نمیشود، داده عکس ناخوانا است، ابعاد از حد 30000x30000px بیشتر است، فایل بزرگتر از 200MB است، upload_id ناتمام یا منقضی است، یا url قابل دانلود نبوده است (پیام دلیلش را میگوید). |
| 429 | از محدودیت درخواست عبور کردهاید؛ بخش محدودیت درخواست بالا را ببینید. |
| 500 | مشکلی غیرمنتظره در سمت سرور رخ داده است. تلاش دوباره بیخطر است. |
کتابخانههای کلاینت
SDKهای رسمی که اندپوینتهای بالا را با نتایج تایپدار پوشش میدهند و بهجای کار با HTTP خام، هنگام خطای API استثنا ایجاد میکنند.
JavaScript / TypeScript
بدون وابستگی، در Node.js و مرورگرها کار میکند. همچنین در JSR با نام @yourimageshare/yourimageshare موجود است - npx jsr add @yourimageshare/yourimageshare - با همان سورس، که مستقیم بهصورت TypeScript منتشر شده است.
npm install yourimageshare Python
یک وابستگی (requests)، Python 3.8+.
pip install yourimageshare PHP
بدون وابستگی Composer (از افزونه curl خود PHP استفاده میکند)، PHP 7.4+. سورس در GitHub.
composer require yourimageshare/yourimageshare-php Go
بدون وابستگی (فقط کتابخانه استاندارد)، Go 1.18+. برای مستندات کامل به pkg.go.dev نگاه کنید.
go get github.com/yourimageshare/yourimageshare/go Rust
دو وابستگی (ureq برای HTTP بلاکینگ - بدون نیاز به async runtime - بهعلاوه serde)، Rust 1.70+. سورس در GitHub.
cargo add yourimageshare Ruby
بدون وابستگی gem (Net::HTTP و json کتابخانه استاندارد)، Ruby 2.7+. سورس در GitHub.
gem install yourimageshare .NET
یک وابستگی (System.Text.Json خود مایکروسافت)، با هدف netstandard2.0 تا هم در .NET Framework و هم در .NET جدید کار کند. سورس در GitHub. روی همین API زنده ساخته و بررسی شده است؛ انتشار در NuGet بهزودی.
dotnet add package YourImageShare Dart / Flutter
یک وابستگی (http، بسته خود تیم Dart)، Dart 2.17+. سورس در GitHub. روی همین API زنده ساخته و بررسی شده است؛ انتشار در pub.dev بهزودی.
dart pub add yourimageshare Elixir
یک وابستگی (Req)، Elixir 1.14+. تاپلهای {:ok, result}| {:error, reason} برمیگرداند - معادل مستقیم شیوه مدیریت خطای این API در همه SDKهای دیگر - بهعلاوه نسخههای bang که استثنا ایجاد میکنند. سورس در GitHub، مستندات در HexDocs.
{:yourimageshare, "~> 1.1"} سرور MCP
برای عاملهای کدنویسی هوش مصنوعی (Claude Code، Cursor و دیگر ابزارهای سازگار با MCP) - یک اسکرینشات را در گزارش باگ، توضیح PR یا گفتگوی پشتیبانی بهصورت یک لینک واقعی بگذارید، نه یک متن base64 یا یک مرحله آپلود دستی. با Claude Desktop و هر کلاینت MCP دیگر هم به همین شکل کار میکند.
میزبانیشده، بدون نیاز به نصب: آن را بهعنوان سرور MCP راهدور اضافه کنید (در Claude: Settings › Connectors › Add custom connector؛ همچنین ChatGPT، Cursor، VS Code و کلاینتهای دیگری که آدرس سرور میگیرند) و کلید API را در آدرس بگذارید:
https://yourimageshare.com/mcp?key=YOUR_API_KEY کلاینتهایی که اجازه تنظیم هدر میدهند میتوانند بهجای آن از https://yourimageshare.com/mcp با Authorization: Bearer YOUR_API_KEY استفاده کنند. آدرسی که کلید شما در آن است مثل رمز عبور عمل میکند: آن را خصوصی نگه دارید و اگر لو رفت، از حساب من کلید جدید بگیرید. در سرور میزبانیشده، upload_image یک لینک عمومی (تا 200MB) یا محتوای base64 درونخطی (تا 15MB) میپذیرد. بدون کلید، https://yourimageshare.com/mcp هم مثل وبسایت بهصورت ناشناس آپلود میکند: فقط unlisted یا private، با محدودیتهای کمتر، و آپلود با delete_url برگرداندهشده حذف میشود. ابزارهای دیگر به کلید نیاز دارند.
محلی: مستقیم با npx اجرایش کنید، بدون مرحله نصب (میتواند فایلها را از دیسک شما هم بخواند):
npx yourimageshare-mcp ابزارها: upload_image (فایل محلی، محتوای درونخطی یا لینک، تا 200MB، با visibility، عنوان و حذف خودکار اختیاری)، list_uploads، get_upload، update_upload و delete_upload.
همچنین در رجیستری رسمی MCP (با نام io.github.yourimageshare/yourimageshare) و در Glama فهرست شده است، اگر کلاینت MCP شما از یکی از آنها نصب میکند.
با MCP آشنا نیستید؟ راهنمای اتصال Claude و ChatGPT به این API از طریق MCP را برای آموزش کامل راهاندازی ببینید.
هر ده مورد با مجوز MIT منتشر شدهاند. برای زبان خود کتابخانه رسمی پیدا نکردید؟ نمونهکدهای زیر نشان میدهند چطور مستقیم API را صدا بزنید.
نمونه کد
curl
# Upload a file
curl "https://yourimageshare.com/api" \
-H "X-API-Key: YOUR_API_KEY" \
-F "uploads=@/path/to/photo.jpg"
# Upload from a link (files up to 200MB; one direct upload request stops at 100MB -
# bigger files go in pieces, see Large Files above)
curl "https://yourimageshare.com/api" \
-H "X-API-Key: YOUR_API_KEY" \
-F "url=https://example.com/video.mp4"
# Upload a file that auto-deletes after 1 hour
curl "https://yourimageshare.com/api" \
-H "X-API-Key: YOUR_API_KEY" \
-F "uploads=@/path/to/photo.jpg" \
-F "expires_in=3600"
# List uploads
curl "https://yourimageshare.com/api" -H "X-API-Key: YOUR_API_KEY"
# Upload a file without a page of its own (file only) and give it a title
curl "https://yourimageshare.com/api" \
-H "X-API-Key: YOUR_API_KEY" \
-F "uploads=@/path/to/photo.jpg" \
-F "visibility=private" \
-F "title=Sunset"
# Look up one upload, then make it public
curl "https://yourimageshare.com/api/aB3xY9qRz1" -H "X-API-Key: YOUR_API_KEY"
curl -X PATCH "https://yourimageshare.com/api/aB3xY9qRz1" \
-H "X-API-Key: YOUR_API_KEY" -d "visibility=public"
# Delete an upload
curl -X DELETE "https://yourimageshare.com/api/aB3xY9qRz1" -H "X-API-Key: YOUR_API_KEY" JavaScript (fetch)
const API_KEY = 'YOUR_API_KEY';
const BASE = 'https://yourimageshare.com/api';
async function uploadFile(file) {
const form = new FormData();
form.append('uploads', file);
const res = await fetch(BASE, {
method: 'POST',
headers: { 'X-API-Key': API_KEY },
body: form,
});
const json = await res.json();
if (json.type !== 'success') throw new Error(json.errors);
return json.data;
}
async function listUploads(page = 1) {
const res = await fetch(`${BASE}?page=${page}`, {
headers: { 'X-API-Key': API_KEY },
});
return res.json();
}
async function deleteUpload(id) {
const res = await fetch(`${BASE}/${id}`, {
method: 'DELETE',
headers: { 'X-API-Key': API_KEY },
});
return res.json();
} Python (requests)
import requests
API_KEY = "YOUR_API_KEY"
BASE = "https://yourimageshare.com/api"
HEADERS = {"X-API-Key": API_KEY}
# Upload a file
with open("/path/to/photo.jpg", "rb") as f:
res = requests.post(BASE, headers=HEADERS, files={"uploads": f})
res.raise_for_status()
upload = res.json()["data"]
# List uploads
res = requests.get(BASE, headers=HEADERS, params={"page": 1})
uploads = res.json()
# Delete an upload
res = requests.delete(f"{BASE}/{upload['id']}", headers=HEADERS) PHP (curl)
<?php
$apiKey = 'YOUR_API_KEY';
$base = 'https://yourimageshare.com/api';
// Upload a file
$curl = curl_init($base);
curl_setopt_array($curl, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ["X-API-Key: $apiKey"],
CURLOPT_POSTFIELDS => ['uploads' => new CURLFile('/path/to/photo.jpg')],
CURLOPT_RETURNTRANSFER => true,
]);
$upload = json_decode(curl_exec($curl), true)['data'];
curl_close($curl);
// List uploads
$curl = curl_init("$base?page=1");
curl_setopt($curl, CURLOPT_HTTPHEADER, ["X-API-Key: $apiKey"]);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$uploads = json_decode(curl_exec($curl), true);
curl_close($curl); Go (net/http)
SDK رسمی Go بالا این کار را برایتان انجام میدهد - این نسخه خام برای کسانی است که ترجیح میدهند وابستگی اضافه نکنند.
package main
import (
"bytes"
"encoding/json"
"io"
"mime/multipart"
"net/http"
"os"
)
const apiKey = "YOUR_API_KEY"
const base = "https://yourimageshare.com/api"
func uploadFile(path string) (map[string]any, error) {
file, err := os.Open(path)
if err != nil {
return nil, err
}
defer file.Close()
body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
part, _ := writer.CreateFormFile("uploads", path)
io.Copy(part, file)
writer.Close()
req, _ := http.NewRequest("POST", base, body)
req.Header.Set("Content-Type", writer.FormDataContentType())
req.Header.Set("X-API-Key", apiKey)
res, err := http.DefaultClient.Do(req)
if err != nil {
return nil, err
}
defer res.Body.Close()
var result map[string]any
json.NewDecoder(res.Body).Decode(&result)
return result, nil
} ابزارهای اسکرینشات
یک افزونه مرورگر بهعلاوه پیکربندیها و اسکریپتهای آماده برای ارسال مستقیم اسکرینشات به YourImageShare، بدون آپلود دستی. همه از همان اندپوینت /api که بالا توضیح داده شد آپلود میکنند.
افزونه مرورگر (Chrome و Firefox)
افزونه YourImageShare Capture برای Chrome و Firefox به اسکریپت و فایل پیکربندی نیازی ندارد. بخش قابل مشاهده، یک ناحیه انتخابی با کشیدن، یا کل صفحه اسکرولشونده را میگیرد، یک ویرایشگر داخلی برای فلش، متن، محو کردن/پوشاندن و حاشیهنویسیهای دیگر باز میکند، سپس نتیجه را دانلود میکند، در کلیپبورد کپی میکند، یا با یک کلیک مستقیم در YourImageShare منتشر میکند. انتشار از همان اندپوینت /api بالا استفاده میکند - کلید API را یک بار در تنظیمات افزونه وارد کنید و هر انتشار بعدی بلافاصله یک لینک قابل اشتراکگذاری برمیگرداند. در نسخه دسکتاپ Chrome (و مرورگرهای Chromium دیگر)، Firefox دسکتاپ و Firefox برای Android کار میکند.
دریافت YourImageShare Capture برای Firefox دریافت YourImageShare Capture برای Chrome
ShareX
آپلودر سفارشی زیر را دانلود کنید، سپس در ShareX به Destinations > Custom uploader settings > Import > from file بروید، فایل .sxcu دانلودشده را باز کنید و YOUR_API_KEY را در فیلد Headers با کلید واقعی خود جایگزین کنید. آن را بهعنوان مقصد عکس/فایل تنظیم کنید تا اسکرینشاتها خودکار آپلود شوند.
حذف: لینک «Delete» ShareX برای هر آپلود، صفحه حذف ما را در مرورگرتان باز میکند (همان delete_url یکبارمصرف آپلود)، پس میتوانید یک اسکرینشات را مستقیم از تاریخچه ShareX حذف کنید. آپلودها را از حساب من هم میتوانید حذف کنید. پیکربندی را پیش از اکتبر 2026 دانلود کردهاید؟ برای داشتن این قابلیت دوباره دانلودش کنید.
Flameshot (لینوکس)
یک اسکریپت شل کوچک که flameshot gui را اجرا میکند، اسکرینشات را آپلود میکند و لینک را در کلیپبورد کپی میکند. آن را بهجای میانبر پیشفرض Flameshot به یک میانبر صفحهکلید در محیط دسکتاپ خود متصل کنید.
دانلود yis-flameshot-upload.sh
# One-time setup
chmod +x yis-flameshot-upload.sh
export YIS_API_KEY="YOUR_API_KEY" # or add to ~/.config/yourimageshare/api_key
# Then bind this to a hotkey instead of calling flameshot directly:
/path/to/yis-flameshot-upload.sh Greenshot (ویندوز)
یک اسکریپت PowerShell برای مقصد داخلی External command در Greenshot. با Windows PowerShell 5.1 که همراه ویندوز میآید سازگار است و نصب اضافهای نمیخواهد.
دانلود yis-greenshot-upload.ps1
# One-time setup
setx YIS_API_KEY "YOUR_API_KEY"
# In Greenshot: Preferences > Destinations > External command > Settings
# Command: powershell.exe
# Arguments: -ExecutionPolicy Bypass -File "C:\path\to\yis-greenshot-upload.ps1" "%1" افزونههای انجمن
یک دکمه واقعی «آپلود عکس» کنار ویرایشگر پست انجمن خود اضافه کنید. هر افزونه از همان اندپوینت /api بالا آپلود میکند و BBCode را در محل مکاننما درج میکند - بدون تب جداگانه، بدون کپی و جایگذاری دستی.
در موارد زیر بهجای کلید API از کلید فقطآپلود خود استفاده کنید. هر افزونه کلید را در سورس صفحه هر بازدیدکننده میگذارد، و کلید فقطآپلود (حساب من > تب API) فقط میتواند آپلود کند - حتی اگر کسی آن را از صفحه بیرون بکشد، نمیتواند آپلودهای شما را فهرست یا حذف کند.
آپلودهای انجمن بهصورت پیشفرض private هستند: عکس در پست کار میکند، ولی YourImageShare صفحهای مخصوص آن نمیسازد (بدون نظر، واکنش و تبلیغ). هر افزونه تنظیمی برای تغییر به unlisted دارد، اگر برای هر کسی که لینک را دارد صفحه هم بخواهید.
phpBB
یک افزونه واقعی phpBB 3.2/3.3. آن را در ext/ از حالت فشرده خارج کنید، در Customise > Manage extensions فعالش کنید، سپس YOUR_UPLOAD_ONLY_KEY را در فایل رویداد قالب افزونه با کلید فقطآپلود واقعی خود جایگزین کنید.
SMF (Simple Machines Forum)
یک بسته واقعی SMF - از Admin > Package Manager نصبش کنید، سپس YOUR_UPLOAD_ONLY_KEY را در Sources/yis_forumupload.php با کلید فقطآپلود واقعی خود جایگزین کنید.
MyBB
یک افزونه واقعی MyBB 1.8. آن را در inc/plugins/ کپی کنید، در Configuration > Plugins فعالش کنید، سپس YOUR_UPLOAD_ONLY_KEY را در فایل افزونه با کلید فقطآپلود واقعی خود جایگزین کنید.
FluxBB، PunBB و ZetaBoards
اینها سیستم افزونه رسمی ندارند؛ پس یک قطعه کد کوچک است که مستقیم در قالب (FluxBB/PunBB) یا پنل مدیریت (ZetaBoards) چسبانده میشود - دستورالعمل کامل کپی و جایگذاری برای هر کدام:
افزونه WordPress
کتابخانه رسانه خود را بهجای دیسک محلی به YourImageShare منتقل کنید. آپلودهای جدید عکس/فیلم خودکار از همان اندپوینت /api بالا میروند، فایل محلی (و هر اندازه بندانگشتی تولیدشده) پس از تأیید آپلود حذف میشود، و هر آدرس پیوست WordPress - ویرایشگر بلوکی، تصویر شاخص، گالریها، REST API - به فایل میزبانیشده در YourImageShare میرسد. بدون شورتکد، بدون تغییر در روند کار.
- کتابخانه رسانه موجود را در پسزمینه (یا با
wp yis offload --all) یکجا منتقل کنید، نه فقط آپلودهای جدید - عکسها و فیلمهایی که قبلاً در پستها گذاشته شدهاند پس از حذف فایلهای محلیشان هم کار میکنند
- تصاویر بندانگشتی و srcset از بندانگشتی 280px ما استفاده میکنند، پس جایگاههای کوچک عکس فایلهای تماماندازه بارگیری نمیکنند
- فایلها تا 200MB، تکهتکه فرستاده میشوند تا فیلمهای بزرگ به هاست اشتراکی فشار نیاورند
- هر فایل منتقلشده را هر زمان بخواهید به فضای محلی برگردانید
- یک ستون در کتابخانه رسانه نشان میدهد چه چیزی منتقل شده و چه چیزی هنوز محلی است
- فایلهای منتقلشده بهصورت private ذخیره میشوند: هر جا سایت شما از آنها استفاده کند بارگیری میشوند، ولی در YourImageShare صفحهای مخصوص ندارند
از کلید فقطآپلود شما استفاده میکند، نه کلید API. کلید کامل API اختیاری فقط وقتی لازم است که بخواهید فایلهای منتقلشده با حذفشدن در WordPress از YourImageShare هم حذف شوند.
دریافت از WordPress.org دانلود فایل ZIP
در WordPress: Plugins > Add New، عبارت YourImageShare Media Offload را جستجو کنید، سپس Install و Activate را بزنید.
میانبر آیفون و آیپد
از منوی اشتراکگذاری هر برنامه - Photos، Files، Safari، یک اسکرینشات - آپلود کنید و لینک را در کلیپبورد خود داشته باشید. بدون نصب برنامه و بدون حساب کاربری.
برای ساختن خودتان در برنامه Shortcuts (حدود دو دقیقه):
- یک میانبر جدید بسازید و نامش را "Upload to YourImageShare" بگذارید. در جزئیات آن Show in Share Sheet را روشن کنید و عکس و رسانه را بپذیرید.
- Get Contents of URL را اضافه کنید: آدرس
https://yourimageshare.com/api/widget، متدPOST، بدنه درخواست Form با دو فیلد:uploads(File) = Shortcut Input، وclient(Text) =ios-shortcut. - Get Dictionary Value را برای
dataاضافه کنید، سپس یکی دیگر برایsrc- این لینک مستقیم است. - Copy to Clipboard و Show Notification ("Link copied") را اضافه کنید.
بدون کلید، آپلودها ناشناس و unlisted هستند، با محدودیت روزانه. برای آپلود در حساب خود یک هدر X-API-Key با کلید فقطآپلود خود (حساب من > API) اضافه کنید. پاسخ شامل delete_url هم هست اگر بخواهید لینک حذف را نگه دارید.
PicGo و PicList
PicGo و PicList عکسهای جایگذاریشده یا کشیدهشده را برای ویرایشگرهای Markdown - Typora، VS Code، Obsidian، Joplin - آپلود میکنند و لینک را در متن شما میگذارند. افزونه ما YourImageShare را به یکی از سرویسهای آپلود عکس آنها تبدیل میکند.
- در PicGo یا PicList: Plugins، عبارت
yourimageshareرا جستجو و نصب کنید، سپس YourImageShare را بهعنوان آپلودر انتخاب کنید. خط فرمان:picgo install yourimageshare - یا افزونه را دانلود کنید و بهعنوان افزونه محلی وارد کنید (ابتدا از حالت فشرده خارجش کنید)
- تنظیمات: کلید فقطآپلود (اختیاری - خالی = آپلود ناشناس و unlisted)، visibility، و اینکه لینک مستقیم عکس (برای Markdown) برگردد یا لینک صفحه
- لینکی که برمیگرداند با بهینهشدن بعدی عکسهای بزرگ به WebP هم کار میکند
ربات تلگرام
بدون خروج از تلگرام، برای عکس، فیلم یا GIF لینک بگیرید. آن را برای @YourImageShare_bot بفرستید و لینک بلافاصله برمیگردد - بدون حساب کاربری و بدون کلید API. ربات از همان اندپوینت /api بالا آپلود میکند.
- یک عکس، فیلم، GIF یا فایل عکس یا فیلم بفرستید؛ آلبومی تا 10 مورد در یک پاسخ برمیگردد
- در یک گروه، روی یک عکس یا فیلم
/linkرا ریپلای کنید تا ربات لینک آن را برای همه بفرستد /autodeleteباعث میشود آپلودهای بعدیتان پس از 1 ساعت، 1 روز، 1 هفته یا 30 روز خودشان حذف شوند- هر نتیجه یک دکمه Delete دارد که فقط برای کسی که فایل را آپلود کرده کار میکند
- لینکها unlisted هستند: فقط کسانی که لینک را دارند میتوانند فایل را ببینند
- اگر سایت به زبان تلگرام شما موجود باشد، ربات به همان زبان جواب میدهد
کیفیت کامل را نگه دارید: تلگرام عکسهایی را که به روش عادی فرستاده شوند فشرده میکند. آنها را بهصورت فایل بفرستید (📎 → File) تا نسخه اصلی آپلود شود. تلگرام به رباتها اجازه میدهد فایلها را تا 20 MB دریافت کنند، پس فایلهای بزرگتر را در وبسایت آپلود کنید.
ربات Discord
هر عکس، GIF یا فیلم را در Discord به یک لینک دائمی تبدیل کنید. لینکهای پیوست خود Discord بعد از مدتی از کار میافتند؛ لینکهای YourImageShare نه. بدون حساب کاربری و بدون کلید API. ربات از همان اندپوینت /api بالا آپلود میکند.
/uploadبا یک فایل: حذف خودکار اختیاری پس از 1، 7 یا 30 روز، و only_me برای نمایش لینک فقط به خودتان- روی یک پیام راستکلیک کنید → Apps → Rehost on YourImageShare تا تا 6 عکس یا فیلم آن را در یک پاسخ دوباره میزبانی کنید
- آن را به یک سرور اضافه کنید، یا به حساب خودتان تا در هر چت یا پیام خصوصی استفاده کنید
- هر نتیجه یک دکمه Delete دارد که فقط برای کسی که فایل را آپلود کرده کار میکند
- لینکها unlisted هستند: فقط کسانی که لینک را دارند میتوانند فایل را ببینند
GitHub Action برای Playwright و Cypress
وقتی تستهای end-to-end در یک پولریکوئست شکست میخورند، بدون دانلود فایلهای زیپ آرتیفکت علت را ببینید. این اکشن اسکرینشات خطاها و تفاوتهای بصری را آپلود میکند و آنها را بهصورت عکس در یک کامنت پولریکوئست نشان میدهد که با هر اجرا بهروز میشود.
- با Playwright و Cypress کار میکند و خودش تشخیص میدهد پروژه از کدام استفاده میکند
- مقایسههای بصری ناموفق بهصورت Expected، Actual و Diff نشان داده میشوند، با لینک به یک اسلایدر قبل/بعد (
toHaveScreenshotدر Playwright؛ برای Cypress افزونههای cypress-image-diff-js و cypress-visual-regression) - کامنت پس از رفع تستها به «all tests passed» تغییر میکند؛ همان گزارش در خلاصه job هم میرود
- اسکرینشاتها private هستند (فقط فایل عکس، بدون صفحه) و بهطور پیشفرض بعد از 30 روز حذف میشوند
- کلید فقطآپلود شما را بهعنوان secret مخزن با نام
YOURIMAGESHARE_API_KEYلازم دارد؛ هرگز بیلد شما را شکست نمیدهد
- uses: yourimageshare/playwright-pr-screenshots@v1
if: always()
with:
api-key: ${{ secrets.YOURIMAGESHARE_API_KEY }} پروژههای جامعه کاربران
بعضی از بهترین یکپارچهسازیهای YourImageShare را خود کاربران ساختهاند. این پروژهها را اعضای جامعه با API عمومی بالا ساختهاند. نگهداری آنها با سازندگانشان است، پس برای سؤال یا گزارش باگ از طریق صفحه پروژه با سازنده تماس بگیرید.
- YourImageShare Uploads for FlatBB - افزونهای برای انجمن FlatBB از madromas (MadWay Inc.).
- یک دکمه آپلود به ویرایشگر پست FlatBB اضافه میکند: یک یا چند عکس یا فیلم انتخاب کنید و Markdown در محل مکاننما درج میشود
- هر آپلود را بهصورت بندانگشتی قابل کلیک، عکس تماماندازه یا لینک ساده درج میکند (فیلمها بهصورت لینک)
- آپلودها با یک کلید API فقطآپلود از سرور انجمن شما میگذرند، پس کلید هرگز به مرورگر بازدیدکنندگان نمیرسد
- فایلها در YourImageShare میزبانی میشوند، نه روی دیسک انجمن شما، با visibility پیشفرضی که خودتان انتخاب میکنید (private، unlisted یا public)
- در کنار آپلودر خود FlatBB کار میکند، با محدودیت حجم فایل جداگانه
سپاسگزاریم
از همه کسانی که با YourImageShare چیزی میسازند و کارشان را با دیگران به اشتراک میگذارند صمیمانه سپاسگزاریم. پروژههای جامعه کاربران YourImageShare را به جاهایی میبرند که ما خودمان هرگز نمیرسیدیم. با API چیزی ساختهاید؟ برایمان بنویسید تا با خوشحالی آن را اینجا اضافه کنیم.
از وبلاگ
راهنماها و آموزشهای گامبهگام برای توسعهدهندگان
- آپلود فوری اسکرینشات با ShareX، Flameshot یا Greenshot
- افزودن دکمه واقعی آپلود عکس به انجمن phpBB، SMF یا MyBB
- آموزش MCP: اتصال Claude، ChatGPT و عاملهای هوش مصنوعی به YourImageShare
- YourImageShare Capture: افزونه اسکرینشات برای Chrome و Firefox
- انتقال کتابخانه رسانه WordPress به آپلود عکس رایگان
- ربات تلگرام YourImageShare: دریافت لینک برای هر عکس یا فیلم
آماده امتحان کردن هستید؟
دریافت کلید API ←