Llumi Cut · Nordic Byte

توثيق الـ API

Llumi Cut خدمة HTTP. ترفع الملفات، وترسل خطًا زمنيًا بصيغة JSON، وتنزّل النتيجة. تلخّص هذه الصفحة الحقول؛ أما المخطط الكامل المُتحقق منه فتجده في /openapi.json على كل تثبيت.

المصادقة

لكل تثبيت مفتاحه الخاص. أرسله مع كل مسار /v1:

Authorization: Bearer <مفتاحك>

التسلسل

  1. ارفع كل ملف عبر POST /v1/assets?kind=image|video|audio مع الملف كمحتوى ثنائي في جسم الطلب. يعيد {"id": "…"}.
  2. أدخل المونتاج في الطابور عبر POST /v1/renders مع الخط الزمني بصيغة JSON. استخدم الترويسة Idempotency-Key حتى لا تُنشئ إعادة المحاولة عملية إنتاج ثانية.
  3. استعلم عبر GET /v1/renders/{id} حتى تصبح قيمة status هي completed، ثم نزّل كل ملف من result.files.

نقاط النهاية

الطريقةالمسارالوظيفة
GET/healthحالة الخدمة
POST/v1/assets?kind=image|video|audioيرفع ملفًا ثنائيًا ويعيد معرّفه
POST/v1/rendersيتحقق من الخط الزمني ويدخله في الطابور
GET/v1/rendersآخر 100 عملية إنتاج
GET/v1/renders/{id}الحالة والتقدّم والأحداث والأخطاء
POST/v1/renders/{id}/cancelيلغي عملية إنتاج في الطابور أو قيد التنفيذ
POST/v1/renders/{id}/retryيعيد محاولة عملية إنتاج متوقفة
DELETE/v1/renders/{id}يحذف عملية إنتاج متوقفة وملفاتها
GET/v1/renders/{id}/files/{name}ينزّل أحد المخرجات
POST/v1/maintenance/purge?older_than_days=Nيحذف عمليات الإنتاج المتوقفة الأقدم من N يومًا

الخط الزمني

الحقول الإلزامية فقط title وduration وclips. يجب أن يساوي مجموع مدد اللقطات قيمة duration.

الحقلالقيم
duration3–600 s
width · aspect640 أو 1280 أو 1920 (الضلع الأطول) · 16:9، 9:16، 1:1
fps24 أو 30
backgroundلون الأشرطة الجانبية، #RRGGBB
transition · transition_durationcut، fade، fadeblack، fadewhite، dissolve، slideleft، slideright، wipeleft، wiperight، smoothleft، smoothright، circleopen، circleclose · 0.1–2 s
image_motionnone، zoom_in، zoom_out، pan_left، pan_right، auto
fade_in · fade_outظهور واختفاء تدريجي للفيديو كله وصوته، 0–5 s
audio_asset_id · pausesأغنية رئيسية اختيارية وحتى عشرة توقفات بصمت رقمي

اللقطات (clips[])

الحقلالقيم
asset_id · durationصورة أو فيديو · حتى 60 s
trim_start · speedثانية البداية في الملف المصدر · 0.25–4
volumeصوت المقطع نفسه، 0–2 (القيمة 0 تكتمه)
fitcontain (مع أشرطة) أو cover (يملأ الإطار بالاقتصاص)
freeze · motionيجمّد الإطار الأول · حركة Ken Burns
effectsحتى ستة من grayscale، sepia، vintage، noir، warm، cool، blur، sharpen، vignette، invert، mirror، flip
brightness · contrast · saturation−0.5–0.5 · 0.3–2 · 0–3
transition · transition_durationالانتقال من اللقطة السابقة

الصوت (audio_tracks[])

asset_id، start، trim_start، duration، volume (0–2)، fade_in، fade_out، loop وduck. المسار الذي يحمل duck: true ينخفض بنحو 10 dB أثناء تشغيل الأغنية أو صوت متحدث أو صوت أحد المقاطع.

العناوين (texts[])

text (حتى خمسة أسطر)، start، end، position (تسعة مواضع) أو x/y ككسور من الإطار، size، color، outline_color، outline، box، box_color، box_opacity، font، bold، italic وanimation (none، fade، slide_up، slide_left، pop، typewriter).

الطبقات (overlays[])

asset_id (صورة أو فيديو)، start، end، position أو x/y، width، height (عند تحديد الاثنين يُملأ الصندوق: شاشة مقسّمة وشبكات)، margin، opacity، trim_start، volume، fade، border وborder_color.

الترجمة (captions[])

start وend وtext. تُصدَّر بصيغتي SRT وWebVTT، ومع burn_subtitles: true تُدمج في الصورة.

المخرجات

video.mp4 (H.264 + AAC)، audio.wav (المسار الصوتي النهائي)، song.wav (فقط مع أغنية رئيسية)، subtitles.srt، subtitles.vtt، qc.json (المدة والدقة ومصادر الصوت والتحذيرات) وmanifest.json.

الحدود