API الوسائط: تحويل الفيديو والصوت
اضغط الفيديو وحوّله واقتطع منه وغيّر أبعاده واكتم صوته وحوّله إلى GIF، وحوّل الصوت أو اضغطه، عبر نقطة نهاية الوسائط.
إجابة مختصرة
ارفع الملف برفع مباشر، ثم أرسل POST /api/v1/media/process/ مع objectKey بوصفه sourceKey، وعملية operation (convert أو compress-video أو compress-audio أو trim-video أو trim-audio أو resize-video أو change-video-speed أو mute-video أو video-to-gif أو gif-to-mp4) والصيغة المطلوبة. استعلم عن المهمة المُرجعة. ويقتصر حجم الملفات المرفوعة على 50 MB لكل ملف.
العمليات والخيارات
المدخلات: MP4 وMOV وMKV وAVI وWebM وMP3 وWAV وM4A وFLAC وOGG وAAC وGIF.
| operation | حقول مفيدة |
|---|---|
| convert | format: mp4, webm, mkv, mp3, wav, flac, m4a, ogg, aac, gif |
| compress-video | crf (18–40، والقيمة الأعلى = حجم أصغر) أو targetMb لحجم مستهدف |
| compress-audio | bitrate، مثل "128k" |
| trim-video / trim-audio | start وduration بالثواني |
| resize-video / change-video-resolution | width, height |
| change-video-speed | speed، مثل 1.5 |
| mute-video, video-to-gif, gif-to-mp4 | format؛ وduration لتحديد طول GIF |
ضغط فيديو
قياس فعلي في بيئة الإنتاج: عاد ملف MP4 بدقة 720p مدته 10 ثوانٍ وحجمه 2.5 MB كملف H.264/AAC بحجم 1.6 MB في نحو 19 ثانية. وتستغرق مقاطع الفيديو الطويلة أو ذات معدل البت المرتفع وقتًا أطول بالتناسب.
curl -X POST 'https://maxscanner.app/api/v1/media/process/' \
-H "Authorization: Bearer $MAXSCANNER_API_KEY" \
-H 'Content-Type: application/json' \
-d '{ "operation": "compress-video", "sourceKey": "users/<id>/media/inbox/…-clip.mp4", "filename": "clip.mp4", "format": "mp4" }'نصائح عملية
- استعلم عن مهام الوسائط بوتيرة أقل (كل 10 ثوانٍ)، وامنح مقاطع الفيديو الطويلة عدة دقائق
- فضّل مخرجات MP4: فهي تعمل في كل مكان، ومن هذه الواجهة تكون عادةً أصغر من WebM الذي يُرمَّز لصالح السرعة
- اقتطع المقطع قبل ضغطه لتوفير الوقت
- تحقق من GET /api/v1/media/health/ قبل أي دفعة كبيرة: فهي تُبلغ عما إذا كان عامل الوسائط متاحًا
الأسئلة الشائعة
ما أكبر فيديو يمكنني معالجته؟
حاليًا 50 MB لكل عملية رفع. يقبل عامل الوسائط نفسه ما يصل إلى 500 MB، لذا تواصل مع الدعم إذا كنت تحتاج إلى ملفات أكبر.
هل يُحتفظ بالصوت عند ضغط الفيديو؟
نعم، بصيغة AAC، ما لم تستخدم mute-video.