وثائق API

الحصول على مفتاح API

سجّل الدخول، ثم انتقل إلى حسابي وافتح تبويب API. سيظهر مفتاحك هناك مع زر إعادة إنشاء. إعادة إنشاء المفتاح تُبطل المفتاح القديم فوراً، لذا حدّثه في كل مكان يُستخدم فيه قبل أن تضغط الزر.

يحتوي هذا التبويب أيضاً على مفتاح للرفع فقط مستقل - راجع النصيحة أدناه وإضافات المنتديات لمعرفة متى تستخدمه بدلاً من المفتاح الكامل.

المصادقة

أرسل مفتاحك في ترويسة - وهذا هو الأفضل، لأن سلاسل الاستعلام غالباً ما تنتهي في سجلات الوصول وسجلات الوكيل وترويسات Referer:

X-API-Key: YOUR_API_KEY

كما يعمل المعامل ?key= في الاستعلام، وهو متاح للتوافق مع التكاملات القديمة وأوامر curl السريعة. إذا وُجد الاثنان معاً، تكون الأولوية للترويسة.

?key=YOUR_API_KEY

نقاط الوصول

الرفع والعرض والحذف تشترك في المصادقة وحدود الاستخدام نفسها؛ ويمكن إرسال الملفات الكبيرة على أجزاء أولاً.

POST /api - رفع ملف

يرفع ملفاً واحداً للحساب الموثَّق.

الأنواع المقبولة: صور JPG, PNG, GIF, WEBP, AVIF, BMP, TIFF, HEIC أو HEIF؛ وفيديو MP4, WEBM أو AVI (وقد تتوسع القائمة بمرور الوقت). يتم تخزين 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"
  }
}

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، إضافة إلى أي حقول رفع أخرى. الاستجابة هي استجابة الرفع العادية.

تُحذف أجزاء الرفع غير المكتمل بعد ساعتين. فقط طلب 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 [email protected]

GET /api - عرض ملفاتك المرفوعة

يعرض قائمة مقسمة إلى صفحات بملفات الحساب الموثَّق (من أي مصدر - API أو الموقع أو المحرر)، الأحدث أولاً، 50 في الصفحة.

الاستجابة - 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 الملف لاحقاً.

DELETE /api/{id} - حذف ملف مرفوع

يحذف نهائياً أحد ملفات الحساب الموثَّق. لا يمكن التراجع عن ذلك من خلال API. {id} هو القيمة المعادة في id من نقطتي الرفع أو العرض.

الاستجابة - 200 OK:

{ "type": "success", "msg": "Deleted." }

404 إذا لم يوجد ملف بهذا المعرّف في حسابك (إما أنه لم يكن لك قط، أو أنه حُذف بالفعل).

حدود الاستخدام

لكل مفتاح API حصص مستقلة في الدقيقة وفي اليوم، إضافة إلى سقف يومي أوسع لكل عنوان IP كإجراء احتياطي ضد استخدام عنوان واحد لعدة مفاتيح. الرفع والعرض والحذف تشترك في الحدود نفسها.

قد تتغير هذه الحدود. تتضمن كل استجابة ترويسات قياسية لحدود الاستخدام:

X-RateLimit-Limit: 20
X-RateLimit-Remaining: 14

يُرجَع الخطأ 429 عند تجاوز أي حد، مع ترويسة Retry-After تخبرك بعدد الثواني التي عليك انتظارها.

الأخطاء

تستخدم كل استجابات الخطأ الشكل نفسه، بغض النظر عن نقطة الوصول أو السبب:

{ "type": "error", "errors": "A human-readable description of what went wrong." }

مكتبات العميل

مكتبات SDK رسمية تغلّف نقاط الوصول أعلاه بنتائج مُنمَّطة وتُطلق استثناءات عند أخطاء API بدلاً من التعامل المباشر مع HTTP.

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 المتزامنة - دون جلب بيئة تشغيل غير متزامنة - إضافة إلى serde)، وRust 1.70+. المصدر على GitHub.

cargo add yourimageshare

Ruby

بلا أي اعتماديات من الحزم (Net::HTTP من المكتبة القياسية + json)، وRuby 2.7+. المصدر على GitHub.

gem install yourimageshare

.NET

اعتمادية واحدة (System.Text.Json من Microsoft)، وتستهدف 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} - المكافئ المباشر لمعالجة الأخطاء في هذه الواجهة ضمن كل مكتبات SDK الأخرى - إضافة إلى نسخ بعلامة التعجب تُطلق استثناءات. المصدر على GitHub، والوثائق على HexDocs.

{:yourimageshare, "~> 1.1"}

خادم MCP

لوكلاء البرمجة بالذكاء الاصطناعي (Claude Code وCursor وغيرها من الأدوات المتوافقة مع MCP) - أدرج لقطة شاشة في بلاغ خطأ أو وصف PR أو محادثة دعم كرابط حقيقي بدلاً من نص base64 أو خطوة رفع يدوية. ويعمل بالطريقة نفسها مع Claude Desktop وأي عميل MCP آخر. شغّله مباشرة بـ npx دون خطوة تثبيت:

npx yourimageshare-mcp

الأدوات: upload_image (ملف محلي أو محتوى مضمّن أو رابط، حتى 200MB، مع إمكانية تحديد الظهور والعنوان والحذف التلقائي)، وlist_uploads وget_upload وupdate_upload وdelete_upload.

متوفر أيضاً في سجل MCP الرسمي (باسم io.github.yourimageshare/yourimageshare) ومدرج على Smithery وGlama، إن كان عميل MCP لديك يثبّت من أحدهما.

جديد على MCP؟ راجع كيفية ربط Claude وChatGPT بواجهة API هذه عبر MCP لشرح كامل للإعداد.

أمثلة برمجية

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)

تغلّف مكتبة 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 لأندرويد.

احصل على YourImageShare Capture لـ Firefox احصل على YourImageShare Capture لـ Chrome

ShareX

نزّل أداة الرفع المخصصة أدناه، ثم في ShareX انتقل إلى Destinations > Custom uploader settings > Import > from file، وافتح ملف .sxcu الذي نزّلته، واستبدل YOUR_API_KEY في حقل Headers بمفتاحك الحقيقي. اجعلها وجهة الصور/الملفات لديك وستُرفع اللقطات تلقائياً.

تنزيل YourImageShare.sxcu

Flameshot (لينكس)

سكربت shell صغير يشغّل 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 عند المؤشر - بلا تبويب منفصل ولا نسخ ولصق يدوي.

عمليات الرفع من المنتديات خاصة افتراضياً: تعمل الصورة في المشاركة، لكن 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، تُرسل على أجزاء كي لا تُجهد الفيديوهات الكبيرة الاستضافة المشتركة
• استعادة أي ملف منقول إلى التخزين المحلي في أي وقت
• عمود في مكتبة الوسائط يبيّن ما تم نقله وما بقي محلياً
• تُخزَّن الملفات المنقولة بوضع خاص: تُحمَّل أينما يستخدمها موقعك، لكن بدون صفحة خاصة بها على YourImageShare

احصل عليها من WordPress.org تنزيل ملف ZIP

في WordPress: Plugins > Add New، ابحث عن YourImageShare Media Offload، ثم اضغط Install وActivate.

من المدونة