تخطَّ إلى المحتوى

رفع ملف

POST /public/v1/upload

يرفع وسائط إلى مكتبتك ويعيد id وpath اللذين يحتاجهما إنشاء منشور. وكل منشور بوسائط يبدأ من هنا، لأن جسم JSON الخاص بالمنشور لا يحمل الوسائط نفسها.

إن كنت تفعل ذلك من التطبيق، فراجع مكتبة الوسائط. وهذه العملية متاحة أيضًا بالأمر sharek upload في أداة CLI من شارك، وبالأداة uploadWidgetTool في خادم MCP من شارك، وهي تعرض نافذة رفع في محادثة أداة الذكاء الاصطناعي.

multipart/form-data بحقل واحد اسمه file:

Terminal window
curl -X POST https://dash.sharek.app/api/public/v1/upload \
-H "Authorization: your-api-key" \
-F "file=@/path/to/photo.jpg"

لا تضبط Content-Type بنفسك. دع عميل HTTP لديك يضبط حد الأجزاء.

صف الوسائط:

{
"id": "media-id",
"name": "a1b2c3d4e5.jpg",
"originalName": null,
"path": "https://media.example.com/a1b2c3d4e5.jpg",
"thumbnail": null,
"alt": null,
"status": "ready"
}

خذ id وpath إلى مصفوفة image الخاصة بالمنشور:

"image": [ { "id": "media-id", "path": "https://media.example.com/a1b2c3d4e5.jpg" } ]

وقيمة status هي ready، فيمكن إدراج الملف في منشور فورًا. ولقراءتها مجددًا لاحقًا، استدع GET /public/v1/media/:id/status بمعرف الوسائط id، فيعيد id وpath وstatus لذلك الملف، أو 404 Media not found حين لا يكون المعرف في مكتبتك.

يكتشف النوع من بايتات الملف الفعلية، لا من اسمه ولا من Content-Type الذي ترسله، فإعادة تسمية ملف لن تمرره من هنا.

النوع الصيغ الحجم الأقصى
الصور JPEG, PNG, GIF, WebP, AVIF, BMP, TIFF 10 MB
الفيديو MP4 1 GB

وأي شيء آخر يرفض. وملفات AVIF وBMP وTIFF تخزن، لكن إنشاء منشور لا يقبل إلا مسارات تنتهي بـ .png أو .jpg أو .jpeg أو .gif أو .webp أو .mp4، فاحفظها بصيغة JPEG أو PNG أو WebP أولًا إن كانت ستدخل في منشور. ولاحظ أن القائمة هي ما يخزنه شارك؛ وقد ترفض منصة بعينها صيغة لا تدعمها حين ينشر المنشور.

ويخزن شارك الملف باسم مولد بالامتداد المكتشف، وهذا هو name الذي يعود إليك. واسم ملفك لا يحفظ، لذا تكون قيمة originalName هي null.

الاستجابة المعنى
400 {"msg": "No file provided"} لا حقل file في الطلب. راجع اسم الحقل.
400 Unsupported file type. البايتات ليست من الأنواع المقبولة.
400 File is too large. فوق الحد الأقصى لنوعه.
400 Failed to read file تعذر على شارك قراءة بداية الملف لاكتشاف نوعه. أرسله مجددًا.

يعود الخطأ الأول بالشكل {"msg": ...}. وتعود الثلاثة الأخرى بالشكل المعتاد، {"statusCode": 400, "message": "File is too large.", "error": "Bad Request"}.

  • الرفع غير مقيد. فـ إنشاء منشور هو المقيد وحده.
  • الوسائط المرفوعة تبقى في مكتبة الوسائط ويمكن إعادة استخدامها عبر المنشورات. ولإعادة استخدام ملف رفعته من قبل، يعيد سرد الوسائط قيمتي id وpath الخاصتين به مرة أخرى.
  • إن كان الملف على عنوان HTTPS عام أصلًا، فاستخدم الرفع من عنوان وتجاوز التنزيل.