بيئة الإنتاج
توثيق Mixanalytic API
المرجع الرسمي لواجهة API على https://mixanalytic.com. استخدمها لرفع الصوت وتلقي تحليل مكس مدعوم بـ AI، مع اختيار الوحدات وأنماط استجابة مختصرة أو كاملة.
عنوان URL الأساسي: https://mixanalytic.com/api
المصادقة
أرسل مفتاح API في ترويسة X-API-Key مع كل طلب.
curl -X GET "https://mixanalytic.com/api/test-data" \
-H "X-API-Key: YOUR_API_KEY"
- 401 مفتاح مفقود أو غير صالح
- 403 مفتاح خطة مجانية دون صلاحية الوصول إلى API
- 429 تجاوز حد معدل الطلبات
نطاقات الصلاحيات: يُستخدم write للرفع/التحليل في Mix Analyzer. يقرأ content بيانات أبحاث المحتوى بعد حجب المعلومات الحساسة. يحفظ content_write مسودات محتوى غير عامة. نطاقات المحتوى مخصصة للمسؤولين فقط.
نقاط النهاية
| الطريقة | المسار | الغرض |
|---|---|---|
| GET | /api/test-data | فحص الاتصال/المصادقة. |
| POST | /api/upload | رفع ملف صوتي وتحليله. |
| GET | /api/analyze/<file_id> | إعادة التحليل باستخدام معرّف الملف (إذا كان الملف الأصلي لا يزال موجودًا). |
| GET | /api/content/analysis-feed | موجز أبحاث لوكلاء المحتوى بعد حجب المعلومات الحساسة، مخصص للمسؤولين فقط. |
| POST | /api/content/drafts | نقطة نهاية لحفظ/تحديث مسودات وكلاء المحتوى، مخصصة للمسؤولين فقط. |
| GET | /api/ai-stats?days=30 | إحصاءات استخدام تحليل AI. |
طلب الرفع
POST/api/upload
| الحقل | النوع | مطلوب | ملاحظات |
|---|---|---|---|
| file | multipart file | نعم | الصيغ المسموحة: mp3, wav, flac, m4a, aac, ogg. الحد الأقصى 100MB. |
| modules | string/list | لا | تُستخدم جميع الوحدات افتراضيًا إذا لم يُحدّد هذا الحقل. |
| detail_level | string | لا | full (افتراضي) أو summary. |
إذا كانت قيمة detail_level غير صالحة تُعاد 400. الملفات الأكبر من الحد المسموح تُعيد 413.
اختيار الوحدات
تحكّم في وحدات التحليل التي تُعاد وتُحسب باستخدام modules.
الصيغ المدعومة:
- سلسلة نصية مفصولة بفواصل: modules=frequency_balance,clarity,mood
- سلسلة نصية لمصفوفة JSON: modules=["frequency_balance","clarity","mood"]
- مفتاح متكرر (استعلام/نموذج): modules=frequency_balance&modules=clarity
- جميع الوحدات: modules=all أو modules=*
| الوحدة | الوصف |
|---|---|
| frequency_balance | تقييم الترددات والتوازن عبر 7 نطاقات. |
| dynamic_range | النطاق الديناميكي، عامل القمة، PLR. |
| stereo_field | مقاييس الاتساع/الطور/الارتباط. |
| clarity | مقاييس الوضوح الطيفي وتحديد التفاصيل. |
| harmonic_content | المفتاح الموسيقي والتعقيد التوافقي. |
| transients | بيانات الهجوم الصوتي وكثافة العابرات وقوة الضربة في الترددات المنخفضة. |
| 3d_spatial | اتساق الارتفاع/العمق/العرض. |
| surround_compatibility | توافق الصوت الأحادي + تقييم الطور. |
| headphone_optimization | تقييم تحسين التشغيل عبر السماعات الرأسية. |
| speaker_optimization | تقييم تحسين التشغيل عبر مكبرات الصوت. |
| genre | تصنيف النوع الموسيقي ودرجة الثقة. |
| voice | حضور الغناء وخصائص الصوت البشري. |
| instruments | اكتشاف الآلات ومعلومات التوزيع الموسيقي. |
| mood | ملف المزاج مع الطاقة والقيمة الوجدانية. |
| keywords | كلمات مفتاحية ووسوم دلالية. |
| loudness | قِس LUFS والذروة الحقيقية والقص وأهداف البث ليبقى الماستر عاليًا بما يكفي دون تشويه أو قمم ناتجة عن الترميز أو مفاجآت على المنصات. |
| noise | قِس مستوى الضوضاء وطنين الشبكة والهسيس والشوائب لتنظيف التسجيلات قبل أن يجعلها الماسترينغ أعلى وأسطع وأصعب في الإخفاء. |
| format_quality | افحص الترميز بفقد والقطع الطيفي وعمق البت كي لا تستخدم خطأً مصادر MP3 أو AAC متدهورة أو مصادر مرفوعة الدقة في الماسترينغ قبل الإصدار. |
| reference | المرجع |
| visualizations | عناوين URL للأصول المرئية الناتجة عن التحليل. |
| ai_insights | ملخص وتوصيات يولّدها LLM. |
التحكّم في حجم الاستجابة
استخدم detail_level:
- full (افتراضي): حمولة كاملة
- summary: حمولة مختصرة لعملاء الواجهة الأمامية/الهاتف
أمثلة
1) رفع + تحليل كامل
curl -X POST "https://mixanalytic.com/api/upload" \
-H "X-API-Key: YOUR_API_KEY" \
-F "file=@/path/to/track.mp3"
2) رفع + وحدات مختارة
curl -X POST "https://mixanalytic.com/api/upload" \
-H "X-API-Key: YOUR_API_KEY" \
-F "file=@/path/to/track.mp3" \
-F "modules=frequency_balance,dynamic_range,genre,mood,keywords"
3) رفع + وحدات مختارة + حمولة ملخصة
curl -X POST "https://mixanalytic.com/api/upload" \
-H "X-API-Key: YOUR_API_KEY" \
-F "file=@/path/to/track.mp3" \
-F "modules=frequency_balance,stereo_field,clarity,ai_insights" \
-F "detail_level=summary"
4) نقطة نهاية الاختبار
curl -X GET "https://mixanalytic.com/api/test-data" \
-H "X-API-Key: YOUR_API_KEY"
5) JavaScript من جهة العميل
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('modules', 'frequency_balance,dynamic_range,mood,ai_insights');
formData.append('detail_level', 'summary');
const res = await fetch('https://mixanalytic.com/api/upload', {
method: 'POST',
headers: { 'X-API-Key': 'YOUR_API_KEY' },
body: formData
});
const data = await res.json();
console.log(data.analysis, data.returned_modules);
البيانات الوصفية القياسية للاستجابة
تتضمن استجابات التحليل الناجحة:
- requested_modules
- returned_modules
- detail_level
- available_modules
رموز الأخطاء
| الحالة | المعنى | السبب المعتاد |
|---|---|---|
| 400 | طلب غير صالح | قيمة module/detail_level غير صالحة، أو حقل الملف مفقود، أو الملف فارغ. |
| 401 | غير مصادَق عليه | مفتاح API مفقود أو غير صالح أو منتهي الصلاحية. |
| 403 | الوصول ممنوع | فئة الحساب لا تسمح بالوصول إلى API. |
| 404 | غير موجود | /api/analyze/<file_id> الملف لم يعد متاحًا (حُذف لحماية الخصوصية). |
| 413 | الحمولة كبيرة جدًا | الملف أكبر من 100MB. |
| 429 | تجاوز حد معدل الطلبات | طلبات أكثر من المسموح في الدقيقة/الساعة/اليوم. |
| 500 | خطأ في الخادم | فشل في التحليل/وقت التشغيل. |
ملاحظات للواجهة الأمامية
- يُفضّل استخدام detail_level=summary لعملاء الويب/الهاتف.
- اطلب الوحدات اللازمة للعرض الأول فقط لتقليل زمن الانتظار وحجم الحمولة.
- عالج 429 و500 بإعادة المحاولة مع زيادة مدة الانتظار بين المحاولات.
- لا تكشف مفاتيح الإنتاج طويلة الصلاحية في الحزم العامة.