AiVideoEditor
ابدأ مجانًا
القائمة

رُوجع 2026-11-10 · إصدار API 2026-11-09 · قراءة Markdown

رفع الوسائط والاحتفاظ بها

تنتقل بايتات الوسائط مباشرة إلى تخزين كائنات خاص مؤقت. تعيد REST وMCP تعليمات التحميل؛ ولا تقبلان محتوى ملفات ثنائيًا في JSON الأدوات. يجب تكوين التخزين على النشر وإلا أعاد إنشاء التحميل provider_unavailable.

دورة حياة التحميل

  1. اطلب POST /api/v1/media/upload-intents باسم الملف وMIME المعلن وعدد البايتات. احفظ assetId وsessionId المُعادين كهويّتين منفصلتين.
  2. افحص method. بالنسبة إلى presigned_put، ارفع الملف كاملًا إلى uploadUrl باستخدام الترويسات المُعادة. بالنسبة إلى multipart_initiated، قسّم باستخدام partSizeBytes، وارفع كل جزء مرقّم إلى عنوان URL الخاص به واحفظ إيصال ETag الخاص به. لا تضف أبدًا مفتاح حامل AiVideoEditor إلى طلبات التخزين.
  3. أنهِ عند POST /api/v1/media/{assetId}/finalize بـ sessionId، وبالنسبة إلى multipart، multipart.parts يحتوي كل partNumber وetag.
  4. استخدم معرّف الأصل المنهى في 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. احتفظ بالأصلية. إذا انتهت صلاحية الوسائط أو كانت قيد الحذف، فارفعها مرة أخرى قبل النشر.