واجهة imgpile API

ارفع الصور والفيديوهات وشاركها وادِرها برمجيًا.

https://imgpile.com/api/v1 — كل نقاط النهاية

https://cdn.imgpile.com/api/v1/media — رفع الملفات فقط (انظر بالأسفل)

احصل على رمز API

تسجيل الدخول أو تسجيل لإنشاء رمز API.

المفاهيم

لدى imgpile كائنان أساسيان. فهم الفرق سيوفر عليك الوقت.

الوسائط

ملف واحد (صورة أو فيديو). يحتوي على رابط CDN مباشر — مثالي للربط المباشر (hotlinking) أو التضمين أو المشاركة.

منشور

صفحة قابلة للمشاركة تحتوي على عنصر وسائط واحد أو أكثر. تتضمن عنوانًا ووصفًا وتصويتًا وتعليقات ووسومًا.

هل تحتاج فقط إلى رابط صورة مباشر؟ ارفع إلى /media. استخدم urls.original من الاستجابة. تم.

هل تريد منشورًا قابلاً للمشاركة مع تعليقات وتصويت؟ ارفع الوسائط أولًا، ثم استدعِ /posts باستخدام معرّفات الوسائط.

بدء سريع

ارفع ملفًا واحدًا واحصل على رابط CDN مباشر. مثالي لـ ShareX أو بوتات ديسكورد، أو أي سكربت يحتاج فقط لاستضافة صورة.

ملاحظة: تُرفع الملفات إلى cdn.imgpile.com, ليس imgpile.com.

curl -X POST https://cdn.imgpile.com/api/v1/media \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "[email protected]"

الاستجابة:

{
  "message": "Media created successfully",
  "media": {
    "slug": "abc1234",
    "type": "image/jpeg",
    "urls": {
      "original": "https://cdn.imgpile.com/f/abc1234.jpg",
      ...
    }
  }
}

ارفع عدة ملفات، ثم اجمعها في منشور مع بيانات وصفية والتصويت والتعليقات.

1. ارفع كل ملف إلى cdn.imgpile.com واحتفظ بمعرّف الوسائط الذي تم إرجاعه:

curl -X POST https://cdn.imgpile.com/api/v1/media \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "[email protected]"
# Returns: { "media": { "id": 12345, ... } }

2. أنشئ منشورًا بهذه المعرّفات:

curl -X POST https://imgpile.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"media_ids": [12345, 12346]}'
# Returns: { "post": { "slug": "xyz789", ... } }

3. (اختياري) أضف عنوانًا ووصفًا:

curl -X PATCH https://imgpile.com/api/v1/posts/xyz789 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "My post", "description": "Summer 2026"}'

منشورك أصبح الآن مباشرًا على https://imgpile.com/p/xyz789

ارفع صورة من متصفح أو Node.js:

const formData = new FormData();
formData.append('file', fileInput.files[0]);

const response = await fetch('https://cdn.imgpile.com/api/v1/media', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_TOKEN',
    },
    body: formData,
});

const { media } = await response.json();
console.log(media.urls.original); // https://cdn.imgpile.com/f/abc1234.jpg

إعداد ShareX

حمّل إعدادات أداة الرفع المخصصة لدينا واستوردها إلى ShareX — لا حاجة لتعديل JSON يدويًا.

تنزيل imgpile.sxcu

انقر على الزر أعلاه لتنزيل imgpile.sxcu.
انقر مرتين على الملف — سيقوم ShareX باستيراده وجعل imgpile مُحمّلًا متاحًا.
فتح الوجهات → إعدادات المُحمّل المخصص → الرؤوس واستبدل YOUR_TOKEN_HERE بمفتاح API الخاص بك (أنشئ واحدًا في مقدمة).
تعيين الوجهات → مُحمّل الصور → imgpile. التقط لقطة شاشة — سيصل الرابط إلى الحافظة لديك كـ https://cdn.imgpile.com/f/….

المصادقة

نقاط النهاية للقراءة (GET) هي عامة ولا تتطلب مصادقة. جميع نقاط النهاية الأخرى تتطلب رمز bearer.

curl https://imgpile.com/api/v1/posts

للطلبات الموثّقة، مرّر مفتاحك في Authorization الرأس:

curl -H "Authorization: Bearer YOUR_TOKEN" https://cdn.imgpile.com/api/v1/media -F "[email protected]"

وجهة رفع الملفات cdn.imgpile.com; انظر الوسائط → رفع لمزيد من التفاصيل.

أنشئ مفتاحًا في قسم مقدمة أعلاه.

الأخطاء

تُرجع واجهة الـ API أكواد حالة HTTP القياسية. تتضمن استجابات الأخطاء نص JSON مع message (أو error) حقل يصف ما الذي حدث خطأ.

أكواد الحالة

الكود	المعنى
`200`	OK — تم تنفيذ الطلب بنجاح
`201`	Created — تم إنشاء المورد
`400`	Bad Request — طلب غير صحيح الصياغة
`401`	Unauthenticated — مفتاح مفقود أو غير صالح
`403`	ممنوع — ليس لديك صلاحية لتنفيذ هذا الإجراء
`404`	غير موجود — المورد غير موجود
`422`	Validation failed — يحتوي نص الطلب على حقول غير صالحة
`429`	Rate Limited — عدد كبير جدًا من الطلبات، خفف السرعة
`451`	غير متاح لأسباب قانونية — تطابق الملف مع بصمة (hash) محظورة
`500`	Server Error — حدث خطأ من جانبنا

أمثلة لاستجابات الأخطاء

401 Unauthenticated

{ "message": "Unauthenticated." }

403 Forbidden

{ "message": "This action is unauthorized." }

422 Validation failed

{
  "message": "The file field is required.",
  "errors": {
    "file": ["The file field is required."]
  }
}

429 Rate limited

{ "message": "Too Many Attempts." }

تحقق من Retry-After رأس الاستجابة بالثواني حتى تتم إعادة ضبط الحد.

451 محتوى محظور

{ "error": "This file is not allowed." }

ترقيم الصفحات لواجهة برمجة التطبيقات

قائمة نقاط النهاية (GET /posts, GET /media) إرجاع نتائج مُقسّمة إلى صفحات. حجم الصفحة الافتراضي هو 10؛ يمكنك طلب ما يصل إلى 250 باستخدام ?limit=N.

استخدم ?page=N للتنقل بين الصفحات. تتضمن الاستجابة بيانات وصفية للترقيم:

{
  "data": [ ... ],
  "links": {
    "first": "https://imgpile.com/api/v1/posts?page=1",
    "last": "https://imgpile.com/api/v1/posts?page=42",
    "prev": null,
    "next": "https://imgpile.com/api/v1/posts?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "to": 10,
    "per_page": 10,
    "total": 421,
    "last_page": 42
  }
}

عند التكرار، اتبع links.next حتى يصبح null, أو تحقق meta.current_page مقابل meta.last_page.

تصفية المحتوى

بشكل افتراضي، يتم سرد نقاط النهاية (GET /posts, GET /media) إرجاع المحتوى الآمن فقط (حالة الإشراف approved). لإدراج المحتوى للبالغين أيضًا (nsfw), تمرير ?nsfw=1:

curl https://imgpile.com/api/v1/posts?nsfw=1

محتوى محظور (rejected, أي البريد المزعج أو الإساءة) لا يتم إرجاعه أبدًا إلى نقاط النهاية العامة للتغذية بغض النظر عن ?nsfw الوسم.

تتضمن كل استجابة لمنشور ووسائط moderation_status حتى تتمكن من التحذير أو التمويه أو إخفاء العناصر المعلّمة في عميلك:

{
  "moderation_status": "approved" | "pending" | "nsfw" | "rejected",
  ...
}

approved — آمن لجميع الفئات.
pending — بانتظار الإشراف الآلي.
nsfw — محتوى للبالغين؛ يتم إرجاعه فقط من نقاط النهاية العامة عندما ?nsfw=1.
rejected — بريد مزعج/إساءة؛ لا يتم إرجاعه أبدًا إلى نقاط النهاية العامة.

المنشورات المخفية يمكن الوصول إليها عبر slug الخاص بها لكن لا تظهر أبدًا في التغذيات. المنشورات الخاصة تتطلب ?key=xxx معامل الاستعلام (يمكن للمالك العثور عليه في رابط مشاركة المنشور).

حدود المعدل

الطلبات العامة (بدون رمز): 30 طلبًا/دقيقة لكل عنوان IP
الطلبات المُصادقة: 120 طلبًا/دقيقة لكل مستخدم
رفع الملفات: 1,000 ملف/يوم لكل مستخدم/عنوان IP
الحد الأقصى لحجم الملف: 100 ميغابايت
الأنواع المقبولة: image/* و video/*

تتضمن كل استجابة رؤوس حدود المعدل (X-RateLimit-Limit, X-RateLimit-Remaining).

كائن الوسائط

يتم إرجاعها من نقاط النهاية الخاصة بالوسائط وتُضمَّن داخل استجابات المنشورات.

الحقل	النوع	الوصف
slug	`string`	معرّف فريد من 7 أحرف. يُستخدم في عناوين URL.
filename	`string`	اسم ملف التخزين (نفس slug).
title	`string\|null`	عنوان يقدمه المستخدم.
description	`string\|null`	وصف يقدمه المستخدم.
type	`string`	نوع MIME — مثل `image/jpeg`, `video/mp4`.
width	`integer`	عرض بالبكسل.
height	`integer`	ارتفاع بالبكسل.
moderation_status	`enum`	أحد `approved`, `pending`, `nsfw`, أو `rejected`. انظر تصفية المحتوى.
processed	`boolean`	`false` أثناء إنشاء النسخ بأحجام مختلفة؛ `true` عندما تصبح جاهزة.
created_at	`timestamp`	طابع زمني بصيغة ISO 8601.
urls	`object`	عناوين CDN URLs بكل حجم متاح — راجع عناوين URL المباشرة للصور.
user	`object\|null`	الرافع (اسم المستخدم، الصورة الرمزية). تكون Null لرفع الضيوف.

كائن المنشور

حاوية قابلة للمشاركة لعنصر وسائط واحد أو أكثر.

الحقل	النوع	الوصف
id	`integer`	معرّف رقمي. استخدم `slug` لعناوين URL.
slug	`string`	معرّف فريد من 7 أحرف. يُستخدم في عناوين URL.
title	`string\|null`	عنوان المنشور.
description	`string\|null`	وصف المنشور.
score	`integer`	النتيجة الصافية للتصويت (التصويتات المؤيدة ناقص التصويتات المعارِضة).
view_count	`integer`	إجمالي عدد مرات مشاهدة الصفحة.
media_count	`integer`	عدد عناصر الوسائط في هذا المنشور.
moderation_status	`enum`	أحد `approved`, `pending`, `nsfw`, أو `rejected`. انظر تصفية المحتوى.
isUpvotedByUser	`boolean`	ما إذا كان المستخدم المُصادَق عليه قد صوّت لهذا المنشور تأييدًا.
isDownvotedByUser	`boolean`	ما إذا كان المستخدم المُصادَق عليه قد صوّت لهذا المنشور معارضة.
created_at	`timestamp`	طابع زمني بصيغة ISO 8601.
user	`object\|null`	الكاتب (اسم المستخدم، الصورة الرمزية). تكون Null لمنشورات الضيوف.
media	`array`	مصفوفة من كائنات الوسائط. يتم تضمينه فقط في طلبات المنشور الواحد.
first_media	`object\|null`	أول وسائط (معاينة). يتم تضمينه فقط في استجابات الخلاصة.
الحقول الخاصة بالمالك (يتم إرجاعها فقط لمالك المنشور):
visibility	`enum`	`public`, `hidden`, أو `private`.
access_key	`string\|null`	مطلوب لعرض منشور خاص. أضفه كـ `?key=xxx`.

نقاط نهاية الوسائط

ملفات فردية (صور أو فيديوهات). لكل وسائط عنوان CDN URL مباشر يمكنك الربط به مباشرة أو تضمينه في أي مكان.

POST /media يتطلب المصادقة

مضيف الرفع

أرسل عمليات الرفع إلى https://cdn.imgpile.com/api/v1/media — ليس imgpile.com. يتم تخزين الملفات على مصدر مخصص؛ وسيؤدي إرسال POST إلى المضيف الرئيسي إلى الفشل.

تستخدم جميع نقاط النهاية الأخرى imgpile.com/api/v1 كما هو معتاد.

ارفع صورة أو فيديو. أرسل كـ multipart/form-data.

معامل	الوصف
fileمطلوب	الملف المراد رفعه. الحد الأقصى 100 ميجابايت. يدعم image/* و video/*.
post_idاختياري	إرفاقه بمنشور موجود.

الطلب

curl -X POST https://cdn.imgpile.com/api/v1/media \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "[email protected]"

الاستجابة 201

{
  "message": "Media created successfully",
  "media": {
    "slug": "abc1234",
    "filename": "abc1234",
    "type": "image/jpeg",
    "width": 1920,
    "height": 1080,
    "moderation_status": "approved",
    "urls": {
      "original": "https://cdn.imgpile.com/f/abc1234.jpg",
      ...
    }
  }
}

GET /media عام

قائمة عناصر الوسائط مع التصفية والترقيم (pagination).

معامل	الوصف
tag	تصفية حسب اسم الوسم
sort	`latest` (افتراضي) أو `random`
period	`day`, `week`, `month`, `year`, `all`
limit	النتائج لكل صفحة (الحد الأقصى 250، الافتراضي 10)
username	تصفية حسب اسم المستخدم
nsfw	اضبط على `1` لتضمين محتوى NSFW. الافتراضي: SFW فقط.

الطلب

curl https://imgpile.com/api/v1/media?limit=20

الاستجابة 200

{
  "data": [
    {
      "slug": "abc1234",
      "type": "image/jpeg",
      "width": 1920,
      "height": 1080,
      "moderation_status": "approved",
      "urls": { ... }
    },
    ...
  ],
  "links": { ... },
  "meta": { "current_page": 1, "total": 421 }
}

GET /media/{slug} عام

احصل على عنصر وسائط واحد عبر slug الخاص به.

الطلب

curl https://imgpile.com/api/v1/media/abc1234

الاستجابة 200

{
  "data": {
    "slug": "abc1234",
    "type": "image/jpeg",
    "width": 1920,
    "height": 1080,
    "moderation_status": "approved",
    "urls": { ... }
  }
}

PATCH /media/{slug} يتطلب المصادقة

حدّث الوسائط التي تملكها.

معامل	الوصف
title	عنوان الوسائط
description	وصف الوسائط

الطلب

curl -X PATCH https://imgpile.com/api/v1/media/abc1234 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "New title"}'

الاستجابة 200

{
  "message": "Media updated successfully"
}

DELETE /media/{slug} يتطلب المصادقة

احذف الوسائط التي تملكها.

الطلب

curl -X DELETE https://imgpile.com/api/v1/media/abc1234 \
  -H "Authorization: Bearer YOUR_TOKEN"

الاستجابة 200

{
  "message": "Media deleted successfully."
}

نقاط نهاية المنشورات

صفحات قابلة للمشاركة تحتوي على عنصر وسائط واحد أو أكثر. تحتوي على عنوان ووصف وتصويت وتعليقات ووسوم.

GET /posts عام

عرض قائمة المنشورات العامة مع التصفية والترقيم (pagination).

معامل	الوصف
tag	تصفية حسب اسم الوسم
sort	`latest` (افتراضي) أو `random`
period	`day`, `week`, `month`, `year`, `all`
limit	النتائج لكل صفحة (الحد الأقصى 250، الافتراضي 10)
username	تصفية حسب اسم المستخدم
nsfw	اضبط على `1` لتضمين محتوى NSFW. الافتراضي: SFW فقط.

الطلب

curl https://imgpile.com/api/v1/posts?sort=latest

الاستجابة 200

{
  "data": [
    {
      "id": 30713,
      "slug": "MSGhYqy",
      "title": "Sunset photos",
      "score": 12,
      "view_count": 245,
      "media_count": 3,
      "moderation_status": "approved",
      "user": { "username": "alice", ... },
      "first_media": { ... }
    },
    ...
  ]
}

GET /posts/{slug} عام

احصل على منشور واحد مع وسائط مُرقّمة بالصفحات.

معامل	الوصف
mediaPage	رقم الصفحة للوسائط (الافتراضي 1)
perPage	عدد عناصر الوسائط لكل صفحة (الافتراضي 10)
key	مطلوب للمنشورات الخاصة. يمكن للمالك العثور عليه في رابط المشاركة.

الطلب

curl https://imgpile.com/api/v1/posts/MSGhYqy

# Private post with key:
curl "https://imgpile.com/api/v1/posts/xyz789?key=ab12cd34ef"

الاستجابة 200

{
  "data": {
    "id": 30713,
    "slug": "MSGhYqy",
    "title": "Sunset photos",
    "description": "...",
    "score": 12,
    "view_count": 245,
    "moderation_status": "approved",
    "user": { "username": "alice", ... },
    "media": [ ... ]
  }
}

POST /posts يتطلب المصادقة

إنشاء منشور جديد من الوسائط المرفوعة.

معامل	الوصف
media_idsمطلوب	مصفوفة بمعرّفات الوسائط المراد تضمينها في المنشور

الطلب

curl -X POST https://imgpile.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"media_ids": [12345, 12346]}'

الاستجابة 201

{
  "message": "Post created successfully",
  "post": {
    "id": 30720,
    "slug": "rtWJdHr"
  }
}

PATCH /posts/{slug} يتطلب المصادقة

تحديث منشور تملكه.

معامل	الوصف
title	عنوان المنشور (حد أقصى 255)
description	وصف المنشور
visibility	`public`, `hidden`, أو `private`. الإعداد إلى `private` يُنشئ تلقائيًا `access_key`.
is_nsfw	منطقي. علّم المنشور كمحتوى للبالغين بحيث يكون محميًا خلف خيار NSFW لدى المشاهد. بعد التعيين، لن يتم حل المنشور تلقائيًا تحت `nsfw`.
media_order	مصفوفة من slugs للوسائط بالترتيب المطلوب

الطلب

curl -X PATCH https://imgpile.com/api/v1/posts/rtWJdHr \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated title", "visibility": "private"}'

الاستجابة 200

{
  "message": "Post updated successfully",
  "visibility": "private",
  "access_key": "ab12cd34ef"
}

DELETE /posts/{slug} يتطلب المصادقة

حذف منشور تملكه.

الطلب

curl -X DELETE https://imgpile.com/api/v1/posts/rtWJdHr \
  -H "Authorization: Bearer YOUR_TOKEN"

الاستجابة 200

{
  "message": "Post deleted successfully"
}

معامل	الوصف
contentمطلوب	نص التعليق (حد أقصى 500 حرف)
parent_idاختياري	معرّف التعليق للرد عليه (للردود المتسلسلة)

المستخدمون

GET /users/{username}/posts عام

احصل على منشورات مستخدم.

الطلب

curl https://imgpile.com/api/v1/users/alice/posts

الاستجابة 200

{
  "data": [
    {
      "id": 30713,
      "slug": "MSGhYqy",
      "title": "Sunset photos",
      "score": 12,
      "moderation_status": "approved",
      "first_media": { ... }
    },
    ...
  ]
}

GET /users/{username}/media عام

احصل على وسائط مستخدم.

الطلب

curl https://imgpile.com/api/v1/users/alice/media

الاستجابة 200

{
  "data": [
    {
      "slug": "abc1234",
      "type": "image/jpeg",
      "moderation_status": "approved",
      "urls": { ... }
    },
    ...
  ]
}

GET /users/{username}/comments عام

احصل على تعليقات مستخدم (مُرقّمة بالصفحات).

الطلب

curl https://imgpile.com/api/v1/users/alice/comments

GET /users/{username}/followers عام

احصل على متابعي مستخدم (مُرقّمين بالصفحات).

الطلب

curl https://imgpile.com/api/v1/users/alice/followers

GET /users/{username}/following عام

احصل على المستخدمين الذين يتابعهم هذا المستخدم (مُرقّمين بالصفحات).

الطلب

curl https://imgpile.com/api/v1/users/alice/following

POST /users/{username}/follow يتطلب المصادقة

متابعة مستخدم.

الطلب

curl -X POST https://imgpile.com/api/v1/users/alice/follow \
  -H "Authorization: Bearer YOUR_TOKEN"

الاستجابة 200

{
  "message": "User followed."
}

DELETE /users/{username}/follow يتطلب المصادقة

إلغاء متابعة مستخدم.

الطلب

curl -X DELETE https://imgpile.com/api/v1/users/alice/follow \
  -H "Authorization: Bearer YOUR_TOKEN"

الاستجابة 200

{
  "message": "User unfollowed."
}

التصويت

POST /posts/{post}/upvote يتطلب المصادقة

التصويت لصالح منشور. عند الاستدعاء مرة أخرى تتم إزالة التصويت.

الطلب

curl -X POST https://imgpile.com/api/v1/posts/123/upvote \
  -H "Authorization: Bearer YOUR_TOKEN"

الاستجابة 200

{
  "message": "Post upvoted successfully",
  "score": 13
}

POST /posts/{post}/downvote يتطلب المصادقة

التصويت ضد منشور. عند الاستدعاء مرة أخرى تتم إزالة التصويت.

الطلب

curl -X POST https://imgpile.com/api/v1/posts/123/downvote \
  -H "Authorization: Bearer YOUR_TOKEN"

الاستجابة 200

{
  "message": "Post downvoted successfully",
  "score": 11
}

POST /comments/{comment}/upvote يتطلب المصادقة

التصويت لصالح تعليق. عند الاستدعاء مرة أخرى تتم إزالة التصويت.

الطلب

curl -X POST https://imgpile.com/api/v1/comments/456/upvote \
  -H "Authorization: Bearer YOUR_TOKEN"

POST /comments/{comment}/downvote يتطلب المصادقة

التصويت ضد تعليق. عند الاستدعاء مرة أخرى تتم إزالة التصويت.

الطلب

curl -X POST https://imgpile.com/api/v1/comments/456/downvote \
  -H "Authorization: Bearer YOUR_TOKEN"

عناوين URL المباشرة للصور

يتم تقديم كل ملف تم رفعه عبر CDN. تتضمن استجابة الوسائط urls كائنًا بجميع الأحجام المتاحة:

https://cdn.imgpile.com/f/{filename}.{ext}          — Original
https://cdn.imgpile.com/f/{filename}_xs.{ext}       — Extra small
https://cdn.imgpile.com/f/{filename}_sm.{ext}       — Small
https://cdn.imgpile.com/f/{filename}_md.{ext}       — Medium
https://cdn.imgpile.com/f/{filename}_lg.{ext}       — Large
https://cdn.imgpile.com/f/{filename}_xl.{ext}       — Extra large
https://cdn.imgpile.com/f/{filename}_thumb.jpg      — Thumbnail (videos)