رُوجع 2026-11-10 · إصدار API 2026-11-09 · قراءة Markdown
رفع الوسائط والاحتفاظ بها
تنتقل بايتات الوسائط مباشرة إلى تخزين كائنات خاص مؤقت. تعيد REST وMCP
تعليمات التحميل؛ ولا تقبلان محتوى ملفات ثنائيًا في JSON الأدوات.
يجب تكوين التخزين على النشر وإلا أعاد إنشاء التحميل
provider_unavailable.
دورة حياة التحميل
- اطلب
POST /api/v1/media/upload-intentsباسم الملف وMIME المعلن وعدد البايتات. احفظassetIdوsessionIdالمُعادين كهويّتين منفصلتين. - افحص
method. بالنسبة إلىpresigned_put، ارفع الملف كاملًا إلىuploadUrlباستخدام الترويسات المُعادة. بالنسبة إلىmultipart_initiated، قسّم باستخدامpartSizeBytes، وارفع كل جزء مرقّم إلى عنوان URL الخاص به واحفظ إيصال ETag الخاص به. لا تضف أبدًا مفتاح حامل AiVideoEditor إلى طلبات التخزين. - أنهِ عند
POST /api/v1/media/{assetId}/finalizeبـsessionId، وبالنسبة إلى multipart،multipart.partsيحتوي كلpartNumberوetag. - استخدم معرّف الأصل المنهى في
mediaIdsالمسودة. نية التحميل وحدها لا تجعل الأصل قابلًا للنشر.
يفحص الخادم البايتات الفعلية والتنسيق على نسخة نهائية غير قابلة للتغيير. الحجم/MIME المعلنان مدخلات حجز، لا إثبات صلاحية الملف. عائلات الأساس المدعومة هي JPEG وPNG وMP4؛ ويمكن لكل وجهة فرض حدود أشد. الحد الأقصى الحالي لحجم الملف هو 500 MiB (524,288,000 بايت). الملفات بحجم 50 MiB أو أكثر تستخدم multipart، عادةً بأجزاء 16 MiB. اتبع دائمًا الأحجام وعناوين URL وانتهاء الصلاحية المُعادة بدلًا من اشتقاقها من هذه الافتراضات.
{
"sessionId": "<session UUID from upload-intents>",
"multipart": {
"parts": [
{ "partNumber": 1, "etag": "<ETag returned by storage>" }
]
}
}
هذا توضيح لشكل multipart؛ ضمّن كل جزء فعلي. إنهاء
الرفع الفردي (Single-PUT) يرسل sessionId فقط. امنح كل عملية تغيير API جديدة
Idempotency-Key خاصًا بها؛ واحتفظ به لإعادة المحاولات المطابقة الآمنة.
الاستئناف أو التخلي
عناوين URL الموقّعة المنتهية ليست عناوين وسائط دائمة. اطلب عناوين URL أجزاء multipart جديدة
باستخدام POST /media/{id}/upload-parts مع fromPart وtoPart (نطاق شامل من 64 جزءًا على الأكثر). راجع مرجع واجهة البرمجة لشكل الطلب
المحدود. لا تعيد رفع الأجزاء المكتملة بلا داعٍ ولا تكمل تجميع multipart
مباشرة عبر التخزين: الإنشاء يتحكم فيه الخادم.
استخدم POST /media/{id}/abandon عند إلغاء تحميل غير مكتمل. يحرر هذا
حجزته عبر سير عمل التنظيف المشترك. قد تتطلب صلاحية الجلسة أو استهلاك
حالة multipart نية جديدة؛ لا تخمّن مفاتيح كائنات التخزين.
الاحتفاظ المؤقت
تعيد GET /media/{id} الحالة ومعلومات deleteAfter الديناميكية، لا
عنوان URL عامًا دائمًا. تحمي الاستخدامات المجدولة والجارية الوسائط عبر العمل.
تحتفظ السياسة الافتراضية بوسائط المسودات غير المستخدمة 14 يومًا، والوسائط المستقرة
72 ساعة، والعمل الفاشل أو الملتبس 7 أيام بعد المحاولة ذات الصلة.
يعتمد الاحتفاظ الفعلي على كل المراجع المتبقية؛ وقد يكون deleteAfter بقيمة null.
احتفظ بالأصلية. إذا انتهت صلاحية الوسائط أو كانت قيد الحذف، فارفعها مرة أخرى قبل النشر.