مستندات 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 - آپلود فایل

یک فایل را برای حساب احراز هویت‌شده آپلود می‌کند.

فیلدنوعالزامیتوضیح
uploadsfileیکی از این سه موردفایلی که باید آپلود شود، تا 100MB (حد یک درخواست از طریق شبکه ما). در هر درخواست یک فایل؛ این اندپوینت آپلود گروهی چند فایل را پشتیبانی نمی‌کند.
urlstringلینک عمومی http(s) یک عکس یا فیلم. ما خودمان آن را دانلود می‌کنیم، پس فایل‌ها تا 200MB قابل قبول‌اند.
upload_idstringفایلی که پیش‌تر تکه‌تکه با POST /api/chunk فرستاده‌اید، تا 200MB.
filenamestringخیرهمراه با upload_id: نام اصلی فایل.
expires_inintegerخیرحذف خودکار این آپلود پس از این تعداد ثانیه (از 60 تا 31,536,000، یعنی 1 دقیقه تا 1 سال). برای آپلود معمولی و دائمی آن را نفرستید.
allow_duplicatebooleanخیرحتی اگر حساب شما همین فایل را قبلاً آپلود کرده باشد، یک نسخه جدید ذخیره شود (پایین‌تر duplicate را ببینید).
keep_originalbooleanخیرعکس دقیقاً همان‌طور که آپلود شده نگه داشته شود. بدون آن، فایل‌های JPG/PNG بزرگ‌تر از 1 MB به WebP بهینه می‌شوند. متادیتا مثل GPS در هر دو حالت حذف می‌شود.
visibilitystringخیرunlisted (پیش‌فرض): فایل و صفحه‌اش برای هر کسی که لینک را داشته باشد کار می‌کند، ولی در هیچ جا فهرست نمی‌شود. private: فقط فایل؛ لینک صفحه همه به‌جز شما را مستقیم به فایل می‌برد (بدون نظر، واکنش و تبلیغ). public: در سایت فهرست می‌شود و قابل ایندکس است.
titlestringخیرحداکثر 90 نویسه، در صفحه آپلود نمایش داده می‌شود.
descriptionstringخیرحداکثر 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شناسه یکتای فایل.
typeimage یا video.
pathآدرس ذخیره‌سازی فایل به‌همان شکلی که آپلود شده است. ممکن است اندکی بعد، هنگام تبدیل فایل (WebP/MP4)، تغییر کند؛ پس به‌جای path، مقدار src را ذخیره کنید.
srcلینک مستقیم و دائمی فایل؛ همیشه فایل فعلی را باز می‌کند و برای src در <img>/<video> و برای ذخیره‌کردن مناسب است.
directصفحه فایل در YourImageShare (عنوان، توضیح، نظرها، گزینه‌های اشتراک‌گذاری).
thumbتصویر بندانگشتی WebP با عرض 280px (برای فیلم، اولین فریم) یا null.
width, heightاندازه نمایشی به پیکسل (در حالت ایستاده؛ برای فیلم، اندازه فریم) یا null اگر معلوم نباشد.
sizeحجم فایل به بایت، به‌صورتی که ذخیره شده است.
lockedاگر آپلود رمزدار باشد true است.
visibilityprivate، 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 را بزنید:

  1. یک شناسه آپلود انتخاب کنید: 32 نویسه هگزادسیمال تصادفی.
  2. برای هر تکه، POST /api/chunk (multipart/form-data) را همراه با upload_id، index (از 0)، total (تعداد تکه‌ها) و بایت‌ها در chunk بفرستید. پاسخ {"type": "success", "chunk_size": 5242880} است.
  3. 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 مورد در هر صفحه برمی‌گرداند.

پارامترمحلالزامیتوضیح
pagequeryخیرشماره صفحه، پیش‌فرض 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 با کلید واقعی خود جایگزین کنید. آن را به‌عنوان مقصد عکس/فایل تنظیم کنید تا اسکرین‌شات‌ها خودکار آپلود شوند.

دانلود YourImageShare.sxcu

حذف: لینک «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 را در فایل رویداد قالب افزونه با کلید فقط‌آپلود واقعی خود جایگزین کنید.

دانلود برای phpBB

SMF (Simple Machines Forum)

یک بسته واقعی SMF - از Admin > Package Manager نصبش کنید، سپس YOUR_UPLOAD_ONLY_KEY را در Sources/yis_forumupload.php با کلید فقط‌آپلود واقعی خود جایگزین کنید.

دانلود برای SMF

MyBB

یک افزونه واقعی MyBB 1.8. آن را در inc/plugins/ کپی کنید، در Configuration > Plugins فعالش کنید، سپس YOUR_UPLOAD_ONLY_KEY را در فایل افزونه با کلید فقط‌آپلود واقعی خود جایگزین کنید.

دانلود برای MyBB

FluxBB، PunBB و ZetaBoards

این‌ها سیستم افزونه رسمی ندارند؛ پس یک قطعه کد کوچک است که مستقیم در قالب (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 را بزنید.

دکمه آپلود برای هر وب‌سایت

در هر سایتی - فرم نظرات، صفحه پشتیبانی، انجمنی که برایش افزونه نداریم، سایت ایستا - به بازدیدکنندگان خود دکمه «آپلود» بدهید. دو خط کد را بچسبانید؛ بدون حساب کاربری و بدون کد سمت سرور.

<a class="yis-upload" href="https://yourimageshare.com/" data-target="#message" data-format="bbcode">Image and video hosting by YourImageShare</a>
<script src="https://yourimageshare.com/w.js" async></script>

هر دو صفت اختیاری هستند: بدون آن‌ها دکمه لینک‌ها را همراه با دکمه Copy نشان می‌دهد. کادر آپلود دور همین لینک ساخته می‌شود.

  • آپلودها مستقیم در صفحه شما انجام می‌شوند: روی دکمه کلیک کنید، فایل‌ها را روی آن رها کنید، یا اسکرین‌شات را در آن جای‌گذاری کنید - چند فایل همزمان، با نوار پیشرفت و تصویر بندانگشتی
  • عکس‌هایی که مستقیم در فیلد مشخص‌شده در data-target (هر textarea، input یا کادر قابل ویرایش) جای‌گذاری یا رها شوند هم آپلود می‌شوند و لینک‌ها به همان فیلد اضافه می‌شوند؛ بدون هدف، لینک‌ها زیر دکمه همراه با دکمه Copy نشان داده می‌شوند
  • data-format: url (لینک مستقیم فایل، پیش‌فرض)، page، bbcode، html یا markdown؛ data-label متن دکمه را تغییر می‌دهد
  • data-key (اختیاری): کلید فقط‌آپلود شما (حساب من > API). آپلودها آن‌وقت با محدودیت‌های خودتان به حساب شما می‌روند. بدون کلید، آپلودها ناشناس و unlisted هستند، با محدودیت روزانه برای هر بازدیدکننده و هر سایت
  • توسعه‌دهندگان می‌توانند رویداد yis:upload را روی کادر آپلود گوش کنند: event.detail.item مقدار {id, type, page, url, thumb} را دارد
  • فایل‌ها تا 95 MB از طریق دکمه آپلود می‌شوند (فایل‌های بزرگ‌تر را در وب‌سایت آپلود کنید). بررسی محتوایی و شرایط ما مثل همیشه اعمال می‌شود؛ هر بازدیدکننده لینک حذف مخصوص خودش را می‌گیرد

دکمه در یک کادر ایزوله خودش رسم می‌شود، پس CSS سایت شما نمی‌تواند آن را خراب کند. لینک کوچک «Image and video hosting by YourImageShare» داخل کادر آپلود همیشه دیده می‌شود.

میان‌بر آیفون و آی‌پد

از منوی اشتراک‌گذاری هر برنامه - Photos، Files، Safari، یک اسکرین‌شات - آپلود کنید و لینک را در کلیپ‌بورد خود داشته باشید. بدون نصب برنامه و بدون حساب کاربری.

برای ساختن خودتان در برنامه Shortcuts (حدود دو دقیقه):

  1. یک میان‌بر جدید بسازید و نامش را "Upload to YourImageShare" بگذارید. در جزئیات آن Show in Share Sheet را روشن کنید و عکس و رسانه را بپذیرید.
  2. Get Contents of URL را اضافه کنید: آدرس https://yourimageshare.com/api/widget، متد POST، بدنه درخواست Form با دو فیلد: uploads (File) = Shortcut Input، و client (Text) = ios-shortcut.
  3. Get Dictionary Value را برای data اضافه کنید، سپس یکی دیگر برای src - این لینک مستقیم است.
  4. 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 هم کار می‌کند

دانلود افزونه PicGo

ربات تلگرام

بدون خروج از تلگرام، برای عکس، فیلم یا GIF لینک بگیرید. آن را برای @YourImageShare_bot بفرستید و لینک بلافاصله برمی‌گردد - بدون حساب کاربری و بدون کلید API. ربات از همان اندپوینت /api بالا آپلود می‌کند.

  • یک عکس، فیلم، GIF یا فایل عکس یا فیلم بفرستید؛ آلبومی تا 10 مورد در یک پاسخ برمی‌گردد
  • در یک گروه، روی یک عکس یا فیلم /link را ریپلای کنید تا ربات لینک آن را برای همه بفرستد
  • /autodelete باعث می‌شود آپلودهای بعدی‌تان پس از 1 ساعت، 1 روز، 1 هفته یا 30 روز خودشان حذف شوند
  • هر نتیجه یک دکمه Delete دارد که فقط برای کسی که فایل را آپلود کرده کار می‌کند
  • لینک‌ها unlisted هستند: فقط کسانی که لینک را دارند می‌توانند فایل را ببینند
  • اگر سایت به زبان تلگرام شما موجود باشد، ربات به همان زبان جواب می‌دهد

کیفیت کامل را نگه دارید: تلگرام عکس‌هایی را که به روش عادی فرستاده شوند فشرده می‌کند. آن‌ها را به‌صورت فایل بفرستید (📎 → File) تا نسخه اصلی آپلود شود. تلگرام به ربات‌ها اجازه می‌دهد فایل‌ها را تا 20 MB دریافت کنند، پس فایل‌های بزرگ‌تر را در وب‌سایت آپلود کنید.

باز کردن @YourImageShare_bot در تلگرام

ربات Discord

هر عکس، GIF یا فیلم را در Discord به یک لینک دائمی تبدیل کنید. لینک‌های پیوست خود Discord بعد از مدتی از کار می‌افتند؛ لینک‌های YourImageShare نه. بدون حساب کاربری و بدون کلید API. ربات از همان اندپوینت /api بالا آپلود می‌کند.

  • /upload با یک فایل: حذف خودکار اختیاری پس از 1، 7 یا 30 روز، و only_me برای نمایش لینک فقط به خودتان
  • روی یک پیام راست‌کلیک کنید → Apps → Rehost on YourImageShare تا تا 6 عکس یا فیلم آن را در یک پاسخ دوباره میزبانی کنید
  • آن را به یک سرور اضافه کنید، یا به حساب خودتان تا در هر چت یا پیام خصوصی استفاده کنید
  • هر نتیجه یک دکمه Delete دارد که فقط برای کسی که فایل را آپلود کرده کار می‌کند
  • لینک‌ها unlisted هستند: فقط کسانی که لینک را دارند می‌توانند فایل را ببینند

افزودن YourImageShare به Discord

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 }}

راهنمای راه‌اندازی در GitHub

پروژه‌های جامعه کاربران

بعضی از بهترین یکپارچه‌سازی‌های YourImageShare را خود کاربران ساخته‌اند. این پروژه‌ها را اعضای جامعه با API عمومی بالا ساخته‌اند. نگهداری آن‌ها با سازندگانشان است، پس برای سؤال یا گزارش باگ از طریق صفحه پروژه با سازنده تماس بگیرید.

  • YourImageShare Uploads for FlatBB - افزونه‌ای برای انجمن FlatBB از madromas (MadWay Inc.).
    • یک دکمه آپلود به ویرایشگر پست FlatBB اضافه می‌کند: یک یا چند عکس یا فیلم انتخاب کنید و Markdown در محل مکان‌نما درج می‌شود
    • هر آپلود را به‌صورت بندانگشتی قابل کلیک، عکس تمام‌اندازه یا لینک ساده درج می‌کند (فیلم‌ها به‌صورت لینک)
    • آپلودها با یک کلید API فقط‌آپلود از سرور انجمن شما می‌گذرند، پس کلید هرگز به مرورگر بازدیدکنندگان نمی‌رسد
    • فایل‌ها در YourImageShare میزبانی می‌شوند، نه روی دیسک انجمن شما، با visibility پیش‌فرضی که خودتان انتخاب می‌کنید (private، unlisted یا public)
    • در کنار آپلودر خود FlatBB کار می‌کند، با محدودیت حجم فایل جداگانه

    سورس در GitHub · صفحه FlatBB Marketplace

سپاس‌گزاریم

از همه کسانی که با YourImageShare چیزی می‌سازند و کارشان را با دیگران به اشتراک می‌گذارند صمیمانه سپاس‌گزاریم. پروژه‌های جامعه کاربران YourImageShare را به جاهایی می‌برند که ما خودمان هرگز نمی‌رسیدیم. با API چیزی ساخته‌اید؟ برایمان بنویسید تا با خوشحالی آن را اینجا اضافه کنیم.

از وبلاگ

آماده امتحان کردن هستید؟

دریافت کلید API ←